---
name: design-first
description: Get real design directions from an AI design tool (Claude Design or similar) before building UI. Gather real screenshots and features, write a brief that forbids invented content, run one generation at a time, export the HTML, render every artboard to PNG, review, then hand DESIGN.md + artboards to builders. Use when the user says "design it first", "get options from Claude Design", wants landing pages, app screens, UI states or a redesign, or wants several directions to choose from. Not for building the code itself.
---

# Design first

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.