Workflow for frontend features and visual/product design changes — present mockup options before code, build on the project's design system, capture the right evidence (screenshots vs video), run a new-user usability review. Use when building or changing UI, styling, layout or animation.
Install
npx skillscat add kirodotdev/kirocrew/frontend-design-workflow Install via the SkillsCat registry.
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 nativetitle=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.
- For an animated figure inside product UI, such as a gauge or a diagram, see
also theliving-uiskill.
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, andbrowser-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 viaspawn_run (the review is wrong if the reviewer can see the builder's
context), include_project=true so it can open the UI butinclude_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.