|
| 1 | +--- |
| 2 | +name: codegen-html |
| 3 | +category: developer |
| 4 | +tags: |
| 5 | + - code-generation |
| 6 | + - frontend |
| 7 | + - html |
| 8 | + - preact |
| 9 | + - ui |
| 10 | + - zero-dependency |
| 11 | +description: Scaffold and iterate on standalone Preact + HTM applications with zero build dependencies |
| 12 | +metadata: |
| 13 | + forge: |
| 14 | + requires: |
| 15 | + bins: |
| 16 | + - jq |
| 17 | + env: |
| 18 | + required: [] |
| 19 | + one_of: [] |
| 20 | + optional: [] |
| 21 | + egress_domains: |
| 22 | + - cdn.tailwindcss.com |
| 23 | + - esm.sh |
| 24 | + timeout_hint: 60 |
| 25 | +--- |
| 26 | + |
| 27 | +# Codegen HTML Skill |
| 28 | + |
| 29 | +Scaffold and iteratively build standalone HTML applications using Preact + HTM via CDN. Zero local dependencies — no Node.js, no npm, no build step. Just open the HTML file in a browser. |
| 30 | + |
| 31 | +## Quick Start |
| 32 | + |
| 33 | +```bash |
| 34 | +# Scaffold a single-file app |
| 35 | +./scripts/codegen-html-scaffold.sh '{"project_name": "my-app", "output_dir": "/tmp/my-app", "mode": "single-file"}' |
| 36 | + |
| 37 | +# Scaffold a multi-file app |
| 38 | +./scripts/codegen-html-scaffold.sh '{"project_name": "my-app", "output_dir": "/tmp/my-app", "mode": "multi-file"}' |
| 39 | + |
| 40 | +# Read a file or list the project |
| 41 | +./scripts/codegen-html-read.sh '{"project_dir": "/tmp/my-app", "file_path": "."}' |
| 42 | + |
| 43 | +# Write/update a file |
| 44 | +./scripts/codegen-html-write.sh '{"project_dir": "/tmp/my-app", "file_path": "index.html", "content": "..."}' |
| 45 | +``` |
| 46 | + |
| 47 | +## CRITICAL: Scaffold Conventions (DO NOT VIOLATE) |
| 48 | + |
| 49 | +These rules prevent runtime errors: |
| 50 | + |
| 51 | +1. **Use `class` (not `className`)** — HTM maps directly to DOM attributes |
| 52 | +2. **Use Tailwind CSS utility classes** for all styling (loaded via CDN in `index.html`) |
| 53 | +3. **Do NOT create `<style>` blocks or `.css` files** — use Tailwind classes instead |
| 54 | +4. **Keep Preact/HTM imports unchanged** — do not change CDN URLs or versions |
| 55 | +5. **Use named exports** for components: `export function ComponentName() {}` |
| 56 | + |
| 57 | +## Code Style Guide |
| 58 | + |
| 59 | +- Use **Preact** with **HTM** (tagged template literals instead of JSX) |
| 60 | +- Use `class` (not `className`) — HTM maps directly to DOM attributes |
| 61 | +- Template literal syntax: `` html`<div class="app">${content}</div>` `` |
| 62 | +- Use `useState`, `useEffect`, `useRef` from Preact hooks |
| 63 | +- Components are plain functions returning `` html`...` `` template literals |
| 64 | +- All imports via CDN (`esm.sh`), pinned to specific versions |
| 65 | +- Use **Tailwind CSS utility classes** — the CDN is pre-loaded in `index.html` |
| 66 | +- Forge dark theme colors: `bg-zinc-950` (bg), `bg-zinc-900` (cards), `border-zinc-800` (borders), `text-zinc-200` (text), `text-zinc-400` (muted), `bg-indigo-500` (accent) |
| 67 | + |
| 68 | +## Tailwind CSS Reference |
| 69 | + |
| 70 | +Tailwind is loaded via CDN. Use utility classes directly in `class` attributes: |
| 71 | + |
| 72 | +- **Layout:** `flex`, `grid`, `gap-4`, `max-w-4xl`, `mx-auto`, `px-6`, `py-12` |
| 73 | +- **Colors:** `bg-zinc-950`, `bg-zinc-900`, `text-zinc-200`, `text-zinc-400`, `bg-indigo-500` |
| 74 | +- **Borders:** `border`, `border-zinc-800`, `rounded-lg`, `shadow-lg` |
| 75 | +- **Typography:** `text-3xl`, `font-bold`, `text-center`, `font-mono` |
| 76 | +- **Interactive:** `hover:bg-indigo-400`, `transition-colors`, `cursor-pointer` |
| 77 | + |
| 78 | +Do NOT write custom CSS when Tailwind utilities exist. |
| 79 | + |
| 80 | +## Safety Constraints |
| 81 | + |
| 82 | +- Output directory must be under `$HOME` or `/tmp` |
| 83 | +- Non-empty directories require `force: true` to overwrite |
| 84 | +- Path traversal (`..`, absolute paths) is rejected in read/write operations |
| 85 | +- No local tooling required — files can be opened directly in a browser |
| 86 | + |
| 87 | +## Iteration Workflow |
| 88 | + |
| 89 | +1. **Scaffold** the project with `codegen_html_scaffold` |
| 90 | +2. **Read** files to understand current state with `codegen_html_read` |
| 91 | +3. **Write** updated files with `codegen_html_write` |
| 92 | +4. Repeat steps 2-3 to iterate on the UI |
| 93 | + |
| 94 | +After scaffolding, the user can simply open `index.html` in a browser. No install or build step needed. |
| 95 | + |
| 96 | +## When to Use |
| 97 | + |
| 98 | +Use `codegen-html` when the user wants: |
| 99 | +- A quick UI prototype with no setup |
| 100 | +- A single HTML file they can share or open directly |
| 101 | +- Zero-dependency frontend (no Node.js required) |
| 102 | +- Simple interactive apps, dashboards, or demos |
| 103 | + |
| 104 | +For full React apps with build tooling and npm packages, use `codegen-react` instead. |
| 105 | + |
| 106 | +## Tool: codegen_html_scaffold |
| 107 | + |
| 108 | +Create a new Preact + HTM project with Forge-themed dark UI. |
| 109 | + |
| 110 | +**Input:** |
| 111 | + |
| 112 | +| Parameter | Type | Required | Description | |
| 113 | +|-----------|------|----------|-------------| |
| 114 | +| project_name | string | yes | Name for the project | |
| 115 | +| output_dir | string | yes | Absolute path for the project directory | |
| 116 | +| title | string | no | Page title. Default: project_name | |
| 117 | +| mode | string | no | `single-file` (one index.html) or `multi-file` (separate JS/CSS). Default: `single-file` | |
| 118 | +| force | boolean | no | Overwrite non-empty directory. Default: false | |
| 119 | + |
| 120 | +**Output:** JSON object with status, output_dir, mode, and list of files created. |
| 121 | + |
| 122 | +### Response Format |
| 123 | + |
| 124 | +```json |
| 125 | +{ |
| 126 | + "status": "created", |
| 127 | + "output_dir": "/tmp/my-app", |
| 128 | + "project_name": "my-app", |
| 129 | + "mode": "single-file", |
| 130 | + "files": ["index.html"] |
| 131 | +} |
| 132 | +``` |
| 133 | + |
| 134 | +## Tool: codegen_html_read |
| 135 | + |
| 136 | +Read a file or list the project directory. |
| 137 | + |
| 138 | +**Input:** |
| 139 | + |
| 140 | +| Parameter | Type | Required | Description | |
| 141 | +|-----------|------|----------|-------------| |
| 142 | +| project_dir | string | yes | Absolute path to the project directory | |
| 143 | +| file_path | string | yes | Relative path to read, or `"."` for directory listing | |
| 144 | + |
| 145 | +**Output:** JSON object with path, content (or listing), size, and modified timestamp. |
| 146 | + |
| 147 | +### Response Format (file) |
| 148 | + |
| 149 | +```json |
| 150 | +{ |
| 151 | + "path": "index.html", |
| 152 | + "content": "<!DOCTYPE html>...", |
| 153 | + "size": 2048, |
| 154 | + "modified": "2025-01-15T10:30:00Z" |
| 155 | +} |
| 156 | +``` |
| 157 | + |
| 158 | +### Response Format (directory listing) |
| 159 | + |
| 160 | +```json |
| 161 | +{ |
| 162 | + "path": ".", |
| 163 | + "type": "directory", |
| 164 | + "files": ["index.html", "app.js", "styles.css"] |
| 165 | +} |
| 166 | +``` |
| 167 | + |
| 168 | +## Tool: codegen_html_write |
| 169 | + |
| 170 | +Write or update a file in the project. |
| 171 | + |
| 172 | +**Input:** |
| 173 | + |
| 174 | +| Parameter | Type | Required | Description | |
| 175 | +|-----------|------|----------|-------------| |
| 176 | +| project_dir | string | yes | Absolute path to the project directory | |
| 177 | +| file_path | string | yes | Relative path to write | |
| 178 | +| content | string | yes | Complete file content | |
| 179 | + |
| 180 | +**Output:** JSON object with path, action (created/updated), and size. |
| 181 | + |
| 182 | +### Response Format |
| 183 | + |
| 184 | +```json |
| 185 | +{ |
| 186 | + "path": "index.html", |
| 187 | + "action": "updated", |
| 188 | + "size": 2150 |
| 189 | +} |
| 190 | +``` |
0 commit comments