# Frontend Design Workflow

> 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.

- Skill: `kirodotdev/frontend-design-workflow` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kirodotdev/frontend-design-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kirodotdev/frontend-design-workflow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- Author: kirodotdev (https://skillmd.com/u/kirodotdev)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kirodotdev/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`, 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.