| name | frontend-design-workflow |
| description | Workflow for frontend features, visual changes, and product design changes. Present mockup options before writing code, build against the project's design system, capture the right evidence type (screenshots vs video), and run a new-user usability review before finalizing. Use when building or changing UI, styling, layouts, animations, or any user-facing visual surface. |
| triggers | mockup, mockups, frontend, redesign, restyle, visual change, UI change, design change, landing page, new page, new component |
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.
- 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.
- Make each option genuinely different (layout, density, interaction
model) — not three shades of the same idea.
- Build mockups with the target project's real design tokens / theme
variables when they exist, so the options preview accurately.
- Recommend one option with reasoning, but let the user decide.
- 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.
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
when available, 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.
