From 8e531e506f1b259f14f6a89702c5c046dbb44b0a Mon Sep 17 00:00:00 2001
From: Sam Rolfe <samuelrolfe@gmail.com>
Date: Sat, 27 Jun 2026 12:28:44 +1000
Subject: [PATCH] =?UTF-8?q?Add=20design-build=20skill=20=E2=80=94=20code?=
 =?UTF-8?q?=20generation=20from=20DESIGN.md=20+=20spec?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 skills/design-build/SKILL.md | 128 +++++++++++++++++++++++++++++++++++
 1 file changed, 128 insertions(+)
 create mode 100644 skills/design-build/SKILL.md

diff --git a/skills/design-build/SKILL.md b/skills/design-build/SKILL.md
new file mode 100644
index 0000000..d074fb3
--- /dev/null
+++ b/skills/design-build/SKILL.md
@@ -0,0 +1,128 @@
+---
+name: design-build
+description: Generate production-ready HTML/Tailwind code from design specifications and DESIGN.md design tokens. Use when the user has a clear design direction and wants to build.
+---
+
+# /design-build
+
+Generate code from a design spec and optional DESIGN.md tokens. Produces single-file HTML with Tailwind CSS via CDN (phase 1). Future versions will scaffold React projects.
+
+## Flow
+
+### Step 1: Gather requirements
+
+Ask the user two questions:
+
+1. **"What are we building?"** — Description of the page, component, or interface. Be specific about functionality, layout, content.
+
+2. **"What style? Pick from awesome-design-md or describe it."** — Same as design-explore: URL to a DESIGN.md file, or free text description. If the user already explored in design-explore, they can reference the same DESIGN.md.
+
+### Step 2: If DESIGN.md URL provided, download and extract
+
+```bash
+curl -sL <DESIGN_MD_URL> -o /tmp/design-tokens.md
+```
+
+Read the file. Extract:
+- Palette (colors)
+- Typography (fonts, sizes)
+- Spacing
+- Border radius
+- Shadows
+- Identity/language notes
+
+### Step 3: Build the code prompt
+
+Create a detailed prompt for the coder-pro sub-agent:
+
+```
+You are building a production-quality UI component/page.
+
+## What to build
+{user's design description — what it is, what it does, layout, content}
+
+## Design tokens (MUST follow exactly)
+```
+{paste the extracted tokens directly}
+```
+
+## Technical requirements
+- Single HTML file with Tailwind CSS via CDN (<script src="https://cdn.tailwindcss.com">)
+- Include a custom <style> block for design-token-accurate values
+- Tailwind config block for custom colors/fonts matching the tokens
+- Semantic HTML5
+- Mobile-responsive (stack on narrow screens)
+- Include realistic placeholder content (not lorem ipsum — use domain-appropriate text)
+- Comment sections clearly
+- Add subtle hover transitions on interactive elements
+- No framework dependencies — vanilla HTML + Tailwind CDN
+```
+
+If NO DESIGN.md, replace the token section with general style guidance from the user's description.
+
+### Step 4: Call coder-pro
+
+```bash
+Agent(
+  subagent_type: "coder-pro",
+  description: "Generate UI code from design spec",
+  prompt: <the full code prompt from step 3>,
+  max_turns: 3
+)
+```
+
+Be specific in the agent prompt about what file to create. The agent should:
+1. Write the complete HTML file
+2. Output it as a single file to `<output_dir>/index.html`
+
+### Step 5: Save the output
+
+Create an output directory and save:
+
+```bash
+mkdir -p /home/sam/chats/sys_config/docker/penpot_designs/<project-name>
+```
+
+Write the generated code to `index.html` in that directory.
+
+Also save a `README.md` with:
+- The original design spec
+- The DESIGN.md URL used
+- How to preview: `cd <dir> && python3 -m http.server 3000`
+
+### Step 6: Show the result
+
+Tell the user:
+```
+Code generated → /home/sam/chats/sys_config/docker/penpot_designs/<project>/index.html
+
+To preview:
+  cd /home/sam/chats/sys_config/docker/penpot_designs/<project>/
+  python3 -m http.server 3000
+  → Open http://localhost:3000
+
+To get hot-reload:
+  npx live-server . --port=3000
+```
+
+If design-build is used after design-explore, reference: "Based on the mockups you approved, here's the code implementation."
+
+### Step 7: Iterate
+
+User can request changes: "Change the header to sticky, add a dark mode toggle"
+→ Feed the change request + the existing code back to coder-pro for targeted edits.
+
+---
+
+## DESIGN.md Format
+
+Same format as design-explore. See `~/.agents/skills/design-explore/SKILL.md` for the reference.
+
+## Output Location
+
+All generated projects go to:
+```
+/home/sam/chats/sys_config/docker/penpot_designs/<project-name>/
+```
+
+This keeps designs organized and previewable. Create the parent directory if it doesn't exist.