kitdocs · github

Skill: design-first

raw markdown skills/design-first/SKILL.md

The full process, with checks, is in workflows/design-first.md in this kit. This skill is the operator's version: what to do, in order, and the traps.

Before you start

• Usage limits are shared. Design generations, your coding session and any background agents usually draw from one plan limit. Parallel generations on the most expensive model exhausted a plan in about an hour. Default to the standard model, run one generation at a time, and tell the user before running several.
• Use the user's own signed-in browser if you drive the tool by automation. Never open a second browser with a copied profile without asking, and never navigate away the user's other tabs.

The loop

1. Gather real context: what the product really does (read the code, never invent features), the identity (tokens, fonts, motifs), and real screenshots at 390 px with realistic demo data (seed a demo account on local dev). JPEG ≤ ~250 KB, named after the screen.
2. Write the brief with references/brief-template.md: story, real feature list, identity, numbered labelled artboards with real states, and hard rules: no invented testimonials, counts, pricing, features or data, and keep every existing control.
3. Start one conversation. Attach the screenshots, paste the brief, send. For a follow-up in the same visual language, start a new chat in the same project so it shares files and style. One generation per browser tab: switching conversations in a tab interrupts the running one.
4. Wait without burning turns: poll every 5–10 minutes. States to recognise: working, done, interrupted (resume), and limit reached (stop, report the reset time, don't retry). Let any self-check ("found issues, fixing…") finish.
5. Bring the result back: download the exported HTML, its support script, any linked shared-component files and uploads into ~/<project>-design/ (outside the repo). Serve that folder over http and render: bash (cd ~/<project>-design && python3 -m http.server 8765 &) node scripts/render-artboards.mjs http://127.0.0.1:8765/<File>.dc.html ~/<project>-design/png python3 scripts/contact-sheet.py ~/<project>-design/sheet.jpg ~/<project>-design/png/*.png (render-artboards.mjs renders every [data-screen-label] element, phones at 2×, using headless Chrome on a throwaway profile; set CHROME_PATH off macOS. contact-sheet.py needs Pillow.)
6. Review before presenting: read the tool's final message (its judgement calls), flag invented content and decoration (mock status bars, placeholder animations, mock icons), then show the contact sheet with a short summary and your "remove/ignore" list.

When it gets built

Building is a separate step: shared primitives first, then one agent per screen group in its own worktree (workflows/parallel-agents.md). Give builders the artboard PNGs + HTML, DESIGN.md, "reuse tokens and components, keep every behaviour, ignore mock chrome", and compare screenshots per screen at 390 px.

Traps

• Uploads stall at "Uploading…" in a hidden tab. Bring the tab to the front first.
• Rich-text composers (ProseMirror) ignore synthetic paste; document.execCommand("insertText", false, text) works.
• Model switch mid-conversation may force a costly re-read of the whole chat. Start a new chat instead.
• Export tokens go stale when the project changes. Reload and take a fresh download URL.
• Headless browsers opening the tool's served URL directly can hit a bot check. Download with curl, render from a local server.
• Never leave a monkeypatch (e.g. on file-input click) in the user's tab. Their next real upload would inject your files.
• Tab numbers shift when window focus changes. Address tabs by URL substring.