Frontend Design Workflow

Frontend & Design Workflow

A disciplined workflow for frontend features, visual changes, and product design changes. The core idea: design decisions happen in cheap mockups before expensive code, and evidence matches the nature of the change.

Phase 1 — Mockups before code

Never jump straight to implementation when a change involves design decisions, even when one design seems obvious.

Skip mockups only when there is nothing to design: the change is mechanical and fully specified — fixing a typo, changing a value the user prescribed exactly ("make this #FF0000", "bump the font to 14px"), or deleting something. If the request leaves any visual choice open (layout, spacing, color selection, interaction), mockups are required.

1. Render 2–3 distinct design options as mockups for the user to choose from. For small components, inline widgets work well when the chat surface renders them; otherwise — and for full pages or complex layouts — write a self-contained HTML file and share the path.
2. Make each option genuinely different (layout, density, interaction model) — not three shades of the same idea.
3. Build mockups with the target project's real design tokens / theme variables when they exist, so the options preview accurately.
4. Recommend one option with reasoning, but let the user decide.
5. The chosen mockup IS the visual spec. Record which option was picked.

Phase 2 — Implementation

• Match the chosen mockup exactly: colors, shape, spacing, typography, and presentation details (e.g. a styled tooltip bubble, not a native title= attribute). Verify the built UI against the mockup side by side.
• Use the project's existing theme system / design tokens — never hardcode colors that break on theme switch. If the project has CSS custom properties, check whether utility-class opacity modifiers actually work with them before relying on them; verify computed styles, not class presence.
• Follow the project's established component library and conventions. When migrating to a standard library component (Radix, shadcn, etc.), adopt the stock look and drop hand-rolled behavior the library covers natively.
• Prefer proper icon libraries over emojis in UI surfaces.

Phase 3 — Evidence capture

Match the evidence type to the change:

A still frame cannot prove motion or sequence correctness — never submit a screenshot as evidence for an animated or multi-step change. Share the evidence where the change is reviewed: in the pull-request description (following the repository's convention) when a PR workflow exists, otherwise directly in the conversation.

Capture the evidence with the shipped skills rather than improvising: web-verify for screenshots of a surface you changed on a local dev server, and browser-recording for a video or GIF of motion or a multi-step flow. A narrated demo needs feature-demo-recording, which ships with the Dev Fleet app rather than as a built-in skill, so it is only available where that app is installed.

Phase 4 — New-user usability review

Before declaring the change ready, run a dedicated review from a brand-new, non-technical user's perspective — as a separate sub-agent via spawn_run, with include_project=true so it can open the UI but include_memory=false so the reviewer has no builder's context. The reviewer answers:

• Discoverability: can a first-time user find this feature without being told where it is?
• Plain language: do labels, empty states, and messages make sense without developer jargon?
• Zero-context comprehension: does the screen explain itself to someone who never read the PR, the docs, or this conversation?

Automated code reviewers cover correctness and consistency; this review covers first-run usability. Fold its findings into the change before requesting human review.

Phase 5 — Verify, then present

• Run the project's typecheck, lint, and test suites before presenting.
• Verify the actual rendered result, not just the code — use whatever the project provides for running the UI locally (a dev server, a preview build, a static file opened in a browser, an emulator).
• When reporting done: state what was verified, link the evidence, and compare the result to the chosen mockup.

Iteration

When the user gives feedback on a built UI, treat it like a mockup revision: apply targeted edits against the agreed spec, re-capture the affected evidence, and re-verify. Do not redesign from scratch unless the user rejects the chosen direction.