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: | Change type | Evidence | |---|---| | Static layout, styling, new component at rest | Screenshots | | Animations, transitions, hover/focus states | Screen recording (video or GIF) | | Multi-step flows: wizards, modals opening, drag interactions | Screen recording walking the full sequence | | Responsive behavior | Screenshots at each breakpoint, or a recording of the resize | 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` (the review is wrong if the reviewer can see the builder's context), `include_project=true` so it can open the UI but `include_memory=false` so the reviewer has no builder's context. The task text is the one channel your context still reaches it through: give only how to open the UI and the user goal to attempt, never the design rationale, the PR text, or where the new control lives. 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.