Designs you pick from several genuinely different directions. Every direction is
built only from what the product really does, and becomes a written design system
(DESIGN.md + tokens) that coding agents follow screen by screen. Nothing invented
reaches the code.
real product ──▶ brief ──▶ 2–3 directions ──▶ pick ──▶ export + render artboards
(screens, data, │
feature list) ▼
screenshots compared ◀── build per screen ◀── DESIGN.md + tokens
b1-today.jpg).Write down what is wrong or what is needed before opening the tool. For a redesign, a table of measured faults and their cost. For a new product, the story in two sentences and who uses it where (one-handed, between sets, bad Wi-Fi…). Check: every item can be verified by looking at a screen or a number.
Write the brief (template in skills/design-first/references/brief-template.md):
- opening line: what, for which product, one output file name, N different
directions (not N colour schemes), phone 390 px (desktop only if really used);
- WHAT THE PRODUCT IS: the real features, numbered, with real copy;
- the attached images: "every element on them is real";
- VISUAL IDENTITY from the code;
- ARTBOARDS: numbered, labelled (2a Logging a workout), with real states, not
just the happy path (empty, error, offline, loading);
- HARD RULES: no invented testimonials, user counts, ratings, pricing, logos,
features or data; keep every existing control; tap targets ≥ 44 px.
Check: a stranger could tell from the brief alone which features exist.
Generate one conversation at a time. Generations, your coding sessions and any background agents usually share one usage limit. Running three generations in parallel on the most expensive model, plus one agent, exhausted a plan in about an hour and stopped everything until the reset. Default to the standard model, run one generation, and say the cost before fanning out. Check: the tool reports done, and any self-check it runs ("found issues, fixing") has settled.
Export and render every artboard to an image. Download the HTML (plus any
linked shared-component files and uploads), serve the folder locally, and render
each artboard element (e.g. [data-screen-label]) to its own PNG, phones at 2×.
Make a contact sheet. Keep everything in a stable folder outside the repo
(~/<project>-design/) so build agents can read it.
Check: one PNG per labelled artboard, plus a contact sheet you have actually looked at.
Review for invented content before showing anyone. Read the tool's final message (it lists its judgement calls). Flag fake social proof, features the app lacks, false claims, and decoration (mock status bar "9:41", placeholder animations, mock tab-bar icons) so a builder ignores it. Check: a written list of "remove / ignore" items goes with the artboards.
Pick a direction, then fill the gaps. Choose by what fixes the measured faults, not by taste alone. If every direction solved one problem the same way (e.g. all three used a 52 px top bar + bottom tabs), that is the answer, not a style choice. Run a second, smaller round for screens the first round did not draw, including a sheet of states (first run, empty, failure, offline, loading). Check: every screen the app has now exists as an artboard.
Write DESIGN.md + tokens in the repo. Name the system. List colour tokens
(with light/dark values), type scale, spacing, radii, and the shared components
(primary/danger button, input, eyebrow label, segmented control, bottom sheet,
stepper…) with rules ("tokens only, never raw hex in screens"). If users can recolour
the accent, state that everything accent-coloured must still pass contrast recoloured
and in light mode.
Check: a new screen could be built from DESIGN.md without opening the artboards.
Build shared primitives first, on the main branch. Only then build screens,
one group per agent/worktree (see workflows/parallel-agents.md), each told: reuse
the app's tokens and components, keep every behaviour, ignore mock chrome.
Check: no two screens define their own button.
Compare screenshots against artboards, per screen, at 390 px. Then run every browser flow: rebuilding a screen is the easiest way to lose behaviour nobody wrote a test for. Check: each screen matches its artboard (or the difference is a written, deliberate deviation), and all flows pass.
| Symptom | Cause | Fix |
|---|---|---|
| Design shows features the app doesn't have | the brief left gaps and the tool filled them | real feature list + real screenshots + an explicit "invent nothing" rule |
| Three directions look like one layout in three colours | the brief asked for "options" | ask for directions, each with a named idea and what it bets on |
| Everything stops mid-afternoon with a usage-limit message | parallel generations on the expensive model + agents share one plan limit | one generation at a time; state the cost before running several |
| Uploads stall at "Uploading…" when the tool is driven by automation | the browser tab is hidden; some upload code waits for visibility | bring the tab to the front before attaching |
| Switching conversation in the same tab kills a running generation | generation runs inside the page | one generation per tab |
| Builder recreates the fake status bar or a decorative number that reads as data | mock chrome treated as spec | list decoration explicitly in the build brief |
| New screens look half-converted, no error | old unlayered CSS beats Tailwind v4's layered CSS regardless of specificity | put the legacy stylesheet in the lowest cascade layer during the move (see reference/stack.md) |
| Client says "we never asked for this" | a requirement was invented for them | present what they asked for; let them decide the requirements |
DESIGN.md + tokens are in the repo and shared primitives exist