For founders, solo designers & small teams
AI Workflows for
Digital Product Design
A playbook for the design-leaning founder, solo product designer, or a small design team scaling to 4–5 designers who needs to ship production-quality screens fast and build a foundation that scales when the team grows.
Created by Kyle Cooney, Head of Product Design · 2026 · The 13-slide executive brief · New to this? Start with the tutorial
Overview
Why this approach
The short version of why this workflow exists and what it's better at than the traditional Figma-based process.
Traditional Figma approach
This approach
Design in Figma → spec for engineering → engineer rebuilds from scratch → mismatches, revisions, delays
Design in code → working screens from day one → engineering reviews and ships → no translation layer
Figma is a mockup
Looks like the product. Doesn't behave like it. Every interaction, state, and edge case has to be re-solved when engineering builds it for real.
This is the product
The screens you build run in a browser. Interactions work. States are real. What you share with testers is what gets shipped.
Two sources of truth
Figma file and codebase constantly drift apart. Design decisions made in Figma get lost, reinterpreted, or simply not implemented.
One source of truth
The codebase is the design. Tokens, components, decisions, and screens all live in git. Nothing drifts because there's nothing to drift from.
Handoff is a moment
Design hands off to engineering at a fixed point. The designer's involvement drops off. Decisions get made without them.
Handoff is continuous
Design submits PRs. Engineering reviews and merges. The designer stays involved throughout, not as a gatekeeper but as a collaborator with real output.
Design system lives in Figma
Component libraries, styles, and tokens maintained in a design tool that engineering can't directly use. Always one step removed from production.
Design system is the code
tokens.css, shadcn components, and skill files are the design system. Engineering imports directly. No export, no translation, no lag.
The deeper shift underneath all of this: AI made producing competent screens cheap, so the designer's value moved from production to selection. Generating five directions costs minutes; knowing which one is right, and why, is the craft. This playbook is built around that split: the agent handles divergence, you own convergence. The real bottleneck is no longer how fast you can build; it's how fast you can evaluate what got built. Every audit, critique loop, and decision log in this playbook exists to keep your judgment, not your production speed, as the limiting factor.
Overview
What you get
What this workflow is, who it's for, and what it costs.
→
Solo and growing. Design-leaning founder, solo product designer, or 1–2 designers building toward a bigger team. You're doing the work now and setting up the system for when you're not alone.
→
Minimum bar: comfortable in a terminal, a Vercel account, a code editor. No HTML/CSS experience required; you'll pick up what you need as you go.
→
Idea to live URL in an hour. A complete flow in a day. No Figma file to maintain in parallel, and nothing you make is throwaway: the "prototype" is the product, one merged PR from shipping.
→
All states, designed at build time. Hover, loading, error, empty. None of it discovered during QA.
→
The code is the spec. Engineering reads the implementation. The PR replaces the handoff doc.
→
Front-loaded, then fast. The first week is slower: scaffold, brand.md, CLAUDE.md. After that, every sprint compounds: components, skill files, and decisions accumulate.
→
Scales when you grow. Your CLAUDE.md becomes the onboarding doc for designer #2. The workflow documents itself as you use it.
First time doing any of this? Don't start here. The step-by-step tutorial takes you from a blank folder to a live URL and a merged pull request in twelve steps, with the exact prompts to type and a checkpoint after each one. Come back to this playbook when the basics work.
Overview
Tools overview
Four tools. Three daily drivers. One fills a specific gap.
Agent harness
Claude Code · Codex · Hermes · Cursor
Daily Driver
terminal
Your primary environment is an agent harness: the tool that holds your project context, runs your prompts, edits files, and executes terminal tasks. This playbook drives Claude Code and its examples are written for it, but the workflow is harness-portable by design: the context lives in AGENTS.md, skill files, and tokens that any harness reads. Pick one as your daily driver; keep a second installed for second opinions. The preference here is terminal CLIs (scriptable, composable, living exactly where your repo lives), but the desktop apps (Codex's especially) are improving fast, and they're a legitimate on-ramp if the terminal isn't home yet.
→
What the harness does all day: design system generation, component building, flow construction, consistency audits, token export, canvas and prototype generation, git operations, Vercel deploys, any terminal task
→
Claude Code: this playbook's pick. The richest first-party workflow infrastructure: native Agent Skills, subagents, hooks, and per-project memory, all of which this playbook builds on
→
Codex CLI: the strongest second opinion. Reads the same AGENTS.md natively; strong on implementation correctness, which makes it the natural reviewer of your daily driver's output
→
Hermes: the open harness. Bring your own model, self-host if you need to; the right choice when model flexibility or data control outranks first-party polish
→
Cursor: the editor-shaped harness. Same agents, wrapped in an IDE: best for inspecting and navigating generated code, quick visual tweaks without a prompt cycle, and switching models mid-task. Not the main loop; a terminal harness reading your skill files directly is faster for primary building
→
MCP connections to your other tools (Figma, shadcn registries, a headless browser, analytics) work identically from any of them
The harness is the most replaceable layer of this entire stack. That's the point. Your design system, skills, decisions, and instructions are files in git that every harness reads. Committing to the workflow is not committing to a vendor, and at team scale it cuts the other way too: different designers on different harnesses, same constraints, consistent output (see Keep it portable).
Vercel
vercel.app
Daily Driver
Hosting
Where everything gets published. Every branch push auto-deploys a preview URL your shareable artifact for testing, review, and handoff.
→
Preview deploys for every branch instant shareable URL without manual steps
→
Hosting the living style guide, canvas view, and prototype views
→
Password protection when needed ask Claude Code to build basic auth or use Vercel's built-in password protection for sensitive previews
→
Production deploys from main once engineering has reviewed and merged
GitHub
github.com
Daily Driver
Version control
Where design and engineering meet. Every artifact lives here skill files, tokens, components. PRs are the handoff mechanism; CODEOWNERS is the review gate.
→
Version control for the design system, skill files, decision log, and all generated code the single source of truth for both design and engineering
→
Feature branches for daily work, system branches for weekly consolidation, main as the stable production baseline
→
Pull requests as the formal handoff mechanism design PRs include visual rationale, implementation notes, and a review checklist for engineering
→
CODEOWNERS to enforce who must approve changes to /components/ui, /styles, /skills, and /decisions prevents unreviewed changes to system-level files
→
Read-only access to the engineering repo lets Claude Code read real component structure and data types without risking accidental writes to production code
→
Git tags for milestone versioning design-system/week-of-[date] tags create recoverable snapshots that align with token export versions
GitHub Desktop is a useful companion for designers not fully comfortable with CLI git all the branching, committing, and PR workflows in a visual interface, with Claude Code handling the terminal operations that need it.
v0
v0.app
Occasional
Quick exploration outside your design system: use it to explore a rough idea, then bring the result into Claude Code if it's worth building properly. v0 is full-stack capable now, but treat what you make here as disposable unless you fold it back into the system. The prompt-to-app category has settled into lanes: v0 for React code an engineer would actually integrate, Lovable for full-stack apps with backend and deploy included, Figma Make for prototyping inside the Figma ecosystem. Same rule applies to all three: explore there, build here.
The 2026 landscape, honestly. Figma hasn't stood still: Figma Make generates working prototypes from prompts, the Figma MCP server lets agents read and write the canvas, and since Config 2026 the canvas itself accepts code. Code Layers bring working code in as a layer type (early access), and the Figma Agent now has its own skills system, which makes Figma an agent harness in its own right, not just a source agents read from. Anthropic's Claude Design (research preview) offers canvas-style exploration that packages "handoff bundles" for Claude Code. If your team lives in Figma, these are real options. This playbook still bets on code-first because the argument was never about tools; it's about sources of truth. Every canvas tool, however agentic, reintroduces a second artifact that must be kept in sync with production. Working directly in the codebase means there is nothing to sync.
Overview
The full progression
Three temporal modes not a single linear sequence. Setup happens once. Designing & building is a repeating loop. Maintenance runs in the background every week.
The middle column is the one you're always in. Setup is behind you after week one. Maintenance runs automatically in the background. Most of your time and creative energy lives in the Design & Build loop.
Foundation
Skills & instruction files
Give your agent persistent, reusable context so you stop re-explaining the same things every session. These files are the foundation everything else builds on, and they're plain markdown, so they work with any harness. One reading note: this playbook says "CLAUDE.md" throughout because Claude Code is the daily driver. Read it as shorthand for your instruction file; the same content lives in AGENTS.md for Codex, Hermes, and everything else (see Keep it portable).
1
Skills: modular context files your agent reads on demand
Skills started as a Claude Code feature and became the industry's packaging unit for agent expertise; the same markdown runs across harnesses. Two kinds matter for designers: reference skills (what correct looks like) and capability skills (how a workflow runs).
→
Create a
/skills folder in your project root. One .md file per domain: brand.md, a11y.md, copy.md, performance.md, decisions.md, components.md. These are your reference skills: the rules, the exceptions, and what good output looks like, with concrete examples. Plain markdown, readable by any agent, versioned in git.→
In Claude Code, register each one as a native skill: a thin wrapper at
.claude/skills/[name]/SKILL.md whose frontmatter description tells the agent when the skill applies, so it loads automatically whenever the task is relevant. Other harnesses have equivalents (Codex and Cursor read the same skill format or rules files), and the universal fallback works everywhere: "Read /skills/brand.md before we begin."→
Capability skills come later: repeatable workflows like
/new-screen or a weekly audit, packaged the same way. Build them after your reference skills stabilize; see the custom slash commands & skills appendix.→
A skill is ready to write when you find yourself explaining the same thing to your agent more than twice. That repetition is a skill waiting to be written.
# .claude/skills/brand/SKILL.md
---
name: brand
description: Brand and visual standards for this product.
Use when designing, building, or reviewing any screen,
component, or visual asset.
---
Read /skills/brand.md and follow it exactly. It defines
the color system, typography, iconography, illustration
style, and motion principles. Never deviate without
logging a decision.
Keep the knowledge in
/skills/*.md and the auto-invocation wrapper in .claude/skills/. The knowledge files are vendor-neutral: they work pasted into any model, referenced from Cursor rules, or read by another agent CLI. The wrapper is the only Claude-specific part, and it's three lines.Claude CodeAgent Skills
2
Complete instruction file example
Claude Code reads CLAUDE.md at every session start; Codex and Hermes read the same content as AGENTS.md. Write it once; everything in this example is harness-neutral. This is a starting point a real one will need to be created for your project.
# CLAUDE.md
## What this project is
[Product name] [one sentence description].
Primary platform: mobile web (iOS Safari + Android Chrome).
Target users: [brief description].
## Tech stack
Framework: Next.js (App Router) latest stable at project start
Components: shadcn/ui use only these. No custom components
if a shadcn equivalent exists.
Styling: Tailwind CSS v4 (CSS-first config via @theme)
+ CSS custom properties in /styles/tokens.css
Language: TypeScript throughout. No plain JS files.
Package manager: pnpm
## Folder structure
/app Next.js routes and pages
/components
/ui shadcn components (themed, do not modify structure)
/[feature] product-specific components
/styles
tokens.css single source of truth for all design tokens
globals.css base styles and dark mode assignments
/skills context files (read before relevant tasks)
/assets
/icons SVG icons
/illustrations illustration assets
/tokens generated JSON exports for engineering
/decisions decision log and changelog
## Skill files read before relevant tasks
Brand + visual standards → /skills/brand.md
Accessibility rules → /skills/a11y.md
Voice and copy → /skills/copy.md
Performance budget → /skills/performance.md
Component library → /skills/components.md
Decision logging → /skills/decisions.md
## Absolute rules never break these
1. Never hardcode color or spacing values. Use CSS variables only.
2. Never install a new npm package without asking first.
3. Never modify files in /components/ui directly theme through tokens.
4. Never push directly to main. All work goes on feature branches.
5. Never ship the /canvas or /prototype routes design tools only.
6. Always add prefers-reduced-motion to any animation.
7. All touch targets minimum 44x44px.
## Deploy
Platform: Vercel
Preview: auto-deploy on every branch push
Production: merge to main via PR only engineering reviews first
Password-protected previews: ask Claude Code to add basic auth
or use Vercel's built-in password feature.
## Current status
[Update this section weekly what's in progress, what's next,
what decisions are currently open.]
Active branch: design-system/week-of-[date]
In progress: [flow or component name]
Open decisions: [list or "none"]
## Designer preferences
Prefers high-contrast, low-density layouts.
When in doubt, remove rather than add.
Favour conversational, warm UI over structured, form-like UI.
Never use placeholder copy generate real copy for every screen.
The "Current status" section is the most important one to keep updated. It's the first thing your agent reads at the start of a session and the fastest way to re-orient after a break. Treat it like a daily standup note to your future self.
Claude CodeCLAUDE.md
Foundation
Keep it portable
This playbook runs on Claude Code, but nothing in it should depend on Claude Code. Models leapfrog each other, tools get sunset, and pricing changes. The workflow survives all of that if you build it on the four layers that are now vendor-neutral standards. And portability is not just insurance; it's the operating model. Done right, a designer works from whichever harness fits the problem in front of them and picks the work back up in another without losing the thread, because the thread was never in the tool.
1
AGENTS.md the shared instruction file
An open standard (now stewarded by the Linux Foundation's Agentic AI Foundation, used in tens of thousands of repos) read natively by Codex CLI, Cursor, Copilot, Zed, and most agent tools. Put your project instructions there; make CLAUDE.md a thin importer.
→
Move the content of your CLAUDE.md into
AGENTS.md; the stack rules, folder structure, absolute rules, and skill file map are tool-agnostic anyway.→
Claude Code doesn't read AGENTS.md natively, so bridge it with a one-line CLAUDE.md that imports it, or a symlink. Anything genuinely Claude-specific (skill wrappers, hooks) stays in the CLAUDE.md layer.
→
Now an engineer using Cursor, a contractor on Codex CLI, and you on Claude Code all get the same project rules from the same file. One source of truth for agent instructions, same as everything else in this workflow.
# CLAUDE.md the thin shim
@AGENTS.md
# Claude-specific additions only, e.g.:
Skill wrappers live in .claude/skills/ read them
automatically when relevant.
# or skip the file entirely and symlink:
ln -s AGENTS.md CLAUDE.md
AGENTS.mdClaude Code
2
MCP the vendor-neutral tool layer
The Model Context Protocol is how agents connect to external tools, and it's supported across Claude, OpenAI, and Google; it now sits alongside AGENTS.md under the Linux Foundation's Agentic AI Foundation, owned by no single vendor. Every connection you configure via MCP travels with you if you switch agents.
→
The design ecosystem converged on MCP fast: Figma's MCP server gives agents read/write canvas access, shadcn's MCP server lets agents search and install registry components, and Storybook, Knapsack, and Supernova all ship MCP servers that expose your design system to any agent.
→
Prefer an MCP server over a bespoke integration whenever one exists; the browser tooling, analytics access, and design system connections in this playbook all have MCP options.
→
Keep your MCP config in the repo (
.mcp.json) so the whole team, and every agent, gets the same connections.MCPtooling
3
Vendor-neutral artifacts everything important is a file in git
The workflow's accumulated value (tokens, skills, decisions, copy) lives in formats no vendor owns.
→
Design tokens: DTCG-format JSON (the W3C community spec, stable since 2025.10), consumed by Style Dictionary, Tokens Studio, Figma variables, and readable by any agent.
→
Skills: plain markdown. The same brand.md works in Claude Code, pasted into a chat model, or referenced from another CLI's rules file. Skill formats have proven portable across agent CLIs in practice.
→
Decisions and copy: JSON and markdown in the repo. No tool lock-in, no export step, greppable by anything.
→
The test: if Claude Code disappeared tomorrow, you'd lose your favourite driver, not your design system, your decisions, or your instructions. That's the bar. (It's not hypothetical: Google sunset its consumer Gemini CLI in mid-2026.)
Model routing is the mature version of "second opinions." Teams increasingly route per task (one model for design and refactors, another for mechanical execution, another for research) rather than pledging allegiance to one. You don't need a router on day one, but building on the layers above means you could route tomorrow without rewriting anything.
DTCGgit
4
The payoff: work from any harness, resume in any harness
As the team grows, harness choice becomes per-task and per-designer. The system holds because the session state lives in the repo, not in the tool.
→
Pick the harness for the problem in front of you: Claude Code for skills-driven design and building, Codex for an implementation-correctness pass, Cursor for inspecting and hand-tweaking generated code, Hermes when model control matters. Switching is a decision about the task, not a migration.
→
The repo is the session state. The branch holds the work in progress, the "Current status" section holds the narrative, the decision log holds the why, and the skill files hold the rules. Any harness, and any teammate, rehydrates from those four artifacts. Nothing that matters lives in a chat history.
→
Make the handoff ritual explicit: end every working session by updating "Current status" and pushing the branch (a draft PR if unfinished). This is what makes "pick it back up anywhere" true in practice rather than in theory, and it's the same ritual whether the next session is yours, a teammate's, or a different harness entirely.
→
Consistency does not come from everyone using the same tool. It comes from the system: tokens constrain values, skills constrain approach, hooks and audits constrain violations, and PR review catches the rest. Two designers on two different harnesses produce consistent output because the constraints are identical.
The test for team-scale portability: a designer starts a flow in Claude Code on Monday, a teammate continues it in Codex on Tuesday, and the diff shows no seam. If you can't do that yet, the missing piece is almost always state living in a chat session instead of the repo.
AGENTS.mdgitSolo → Team
Foundation
Prompt like a Designer
Claude Code responds well to designer language visual, spatial, felt. You don't need to translate your instincts into technical instructions. Describe what you see and what you want, the way you'd talk to another designer. One framing before the techniques: the industry now calls this discipline context engineering rather than prompt engineering, because what the agent has loaded (your tokens, skill files, real components) shapes the output more than how you phrase any single request. The skills and CLAUDE.md setup from the previous sections is the heavy lifting; the language below is how you steer once the context is right.
1
Structure how to frame a prompt
→
Role + constraint + output: "Build a form component. Use only shadcn inputs. Output a single .tsx file, no new dependencies."
→
Feed it the real file: Point at actual files "Read src/components/Card.tsx and extend it to support a loading state." Don't describe code you can just show.
→
Critique before generate: Ask Claude to identify problems with existing work first, then fix them. Better output than jumping straight to generation.
→
One task at a time: Long multi-part prompts degrade quality. Break complex work into sequential tasks in the same session.
→
Restate goals when stuck: If a direction isn't working after 2–3 tries, step back and restate the intent rather than the fix: "This screen should feel like a moment of reassurance, not a form."
Claude CodeCodexHermesCursor
2
Designer language contrast & visual weight
Describe what you see. Claude understands visual feedback the way a designer gives it.
→
"There's too much contrast between the card and the background it feels harsh. Soften the surface color so it feels like they're in the same family."
→
"There's not enough contrast on the secondary label it's disappearing into the background. Darken it two stops."
→
"The CTA isn't standing out enough it looks like a secondary action. Make it feel like the only obvious next step on the screen."
→
"The icon and the label are fighting for attention. The icon should be supporting the label, not competing with it reduce the icon weight."
→
"Everything on this screen feels equally important. I need a clear hierarchy one thing should read first, one thing second, everything else should recede."
Claude CodeCodexHermesCursor
3
Designer language space & density
→
"This feels too dense the content is suffocating. Give everything more room to breathe, especially between sections."
→
"There's too much whitespace at the top the content doesn't start until halfway down the screen. Pull it up."
→
"The spacing between items in this list is inconsistent some gaps feel tighter than others. Make it uniform."
→
"This card feels too padded the content is floating in the middle with too much empty space around it. Tighten the padding."
→
"The form fields are too far apart it doesn't feel like a cohesive form, it feels like a list of separate inputs. Close the gap."
Claude CodeCodexHermesCursor
4
Designer language type & emphasis
→
"This needs to be emphasized more it's the most important piece of information on the screen and it reads like body text. Make it stand out."
→
"The heading is too big relative to the body text the jump in size feels jarring. Bring the heading down a step."
→
"The label is too bold it's drawing more attention than the value it's labelling. Make it lighter."
→
"The body text is too small to read comfortably on mobile bump it up one step in the type scale."
→
"The line length is too wide it's hard to track from the end of one line to the start of the next. Constrain the text column."
→
"All the text weights feel the same. I need more differentiation there's no clear primary, secondary, tertiary hierarchy in this layout."
Claude CodeCodexHermesCursor
5
Designer language feel & tone
Describe the emotional quality you're after. Claude can translate feeling into visual decisions.
→
"This feels too clinical like a hospital form. It should feel warm and approachable, like a conversation."
→
"This success state feels flat. This is a moment the user should feel good about make it feel like a small celebration without being over the top."
→
"This error screen feels aggressive. The user made a mistake the screen should feel calm and helpful, not alarming."
→
"The onboarding feels like a checklist, not a welcome. Make it feel like we're guiding someone, not processing them."
→
"This screen feels cheap the spacing and weight choices feel inconsistent with the rest of the product. Make it feel like it belongs."
→
"The overall product feels too playful for a financial product. Pull back the color and loosen the constraints we want friendly but not childish."
Claude CodeCodexHermesCursor
6
Designer language layout & composition
→
"The layout feels unanchored there's no clear structure. Group related elements together so it's obvious what belongs to what."
→
"The primary action is buried at the bottom and the user has to scroll to find it. Move it above the fold."
→
"This feels like two screens trying to be one. Split the content first screen for context, second screen for the action."
→
"The image and the text are competing for the same space. One of them needs to lead either make the image a background or make the text the hero."
→
"The bottom of the screen feels unfinished there's a lot of empty space below the last element. Either fill it intentionally or bring the content up."
Claude CodeCodexHermesCursor
7
Interaction design language
Name the pattern, describe the behaviour, specify the trigger. Claude knows interaction design vocabulary use it directly.
→
Progressive disclosure: "Apply progressive disclosure to this form show only the essential fields first. Reveal the advanced options behind a 'Show more' toggle. The expanded state should animate open, not just appear."
→
Progressive disclosure on a flow: "This onboarding flow is asking too much too soon. Apply progressive disclosure collect only what's needed to get the user to their first value moment, then ask for the rest in context later."
→
Empty states: "This table has no empty state. When there's no data, show a contextual empty state that explains why it's empty and gives the user a clear action to fix it not a generic 'No results found'."
→
Loading states: "Add a skeleton loading state to this card. It should match the shape of the loaded content exactly same number of lines, same approximate widths. Use a shimmer animation."
→
Optimistic UI: "Make this action feel instant. Update the UI immediately on click and roll it back if the API call fails don't make the user wait for a server response to see the result."
→
Inline validation: "Move the validation on this form from on-submit to inline. Validate each field on blur, show the error immediately below the field, and clear it as soon as the user starts correcting."
→
Reducing cognitive load: "This screen is trying to do too much. Apply the one primary action rule identify the single most important action and demote everything else to secondary or remove it."
→
Micro-interactions: "Add a micro-interaction to this button on success, briefly morph it to a checkmark state before returning to default. It should feel satisfying, not showy. 300ms total."
→
Transitions: "The transition between these two views feels abrupt. Add a shared element transition on the card it should expand from where it was in the list to fill the detail view, not just cut."
Interaction patterns are a design vocabulary Claude understands natively. You don't need to describe the implementation name the pattern and describe the desired behaviour. "Apply progressive disclosure" is a complete instruction.
Claude CodeCodexHermesCursor
Foundation
Tips & tricks
Prompting techniques, workflow shortcuts, and ways to get more out of Claude Code that aren't obvious from the main process.
1
Generate multiple options before committing
For any design decision you're uncertain about, always ask for 3–5 variations before choosing.
→
"Show me 3 different ways to integrate Apple Pay into the checkout flow vary the placement and the moment of entry. Label each approach and note the tradeoff."
→
"Give me 5 options for how the empty state on the transactions screen could work. Range from minimal to more expressive."
→
"Generate 3 versions of this error message one very brief, one with more context, one that includes a suggested action. I'll pick the best one."
→
After choosing, tell Claude which one and why this feeds into the decision log and helps Claude understand your taste over time within the session.
Three options is the minimum. Five is better for anything visual. One option is never enough you're not evaluating, you're just accepting.
Claude Code
2
Scheduled design critiques from Claude
Build a regular critique session into your weekly rhythm not just consistency audits, but honest design feedback.
Read /skills/brand.md, /skills/a11y.md, and /skills/copy.md.
Read all files in /app.
Act as a senior product designer doing a design critique.
Be honest and specific not encouraging.
Review the current state of the product against:
1. Brand alignment does it feel like the brand or generic?
2. Hierarchy is it clear what the most important action
is on each screen?
3. Consistency where does the experience feel uneven?
4. Friction where might a user hesitate or get confused?
5. Copy anything that sounds off, vague, or un-human?
6. Missed opportunities what's a better version of this
that we haven't tried yet?
Be specific. Cite screens and components. Don't summarize
what's there evaluate it.
→
Run this weekly, not just when something feels wrong. The best time to get critique is before you're too attached to the current state.
→
Push back on the critique "I disagree with point 3 because the hierarchy is intentional here." Claude will reconsider or hold its position with reasoning.
Claude Codeweekly
3
Second opinions from a different model
When you're stuck or want a fresh perspective, run the same prompt through a different model. Divergent outputs surface assumptions.
→
The cleanest way is another terminal agent: Codex CLI (or an open harness like OpenCode) runs in the same repo, reads the same AGENTS.md, and gives a genuinely independent take. Cursor works too if you prefer switching models inside an editor.
→
For code quality and performance: Codex is strong on implementation correctness. Useful for reviewing Claude Code's output on anything that will go to production.
→
The comparison prompt: "Here is a component Claude Code generated. Review it for: correctness, performance, accessibility, and anything that would concern a senior engineer. Don't rewrite it just critique it."
→
Treat divergences between models as a signal to investigate if two models give fundamentally different answers on the same question, there's genuine ambiguity worth resolving before building.
→
This habit matures into per-task model routing; the Keep it portable section covers why that costs nothing once your context lives on the portable layers.
Codex CLICursorClaude Code
4
Reframe before you refine
When a screen isn't working after 2–3 iterations, stop iterating and reframe the problem entirely.
→
"Forget everything we've built for this screen. What's the simplest possible version of this that achieves the goal? Start from zero."
→
"What would this screen look like if we removed half the elements? Which half would you remove and why?"
→
"What's the version of this that a competitor known for great UX would build? What would they do differently?"
→
Iteration without reframing produces local optima small improvements to a fundamentally flawed approach. The reframe question breaks you out of the local minimum.
Claude Code
5
Ask Claude to pressure-test your own decisions
Before committing to a direction, have Claude argue against it.
→
"We've decided to use a bottom nav with 4 items. What are the strongest arguments against this decision? What would break it?"
→
"A user researcher would look at this onboarding flow and find 3 things that would cause drop-off. What are they?"
→
"What would a accessibility auditor flag as the most serious issue on this screen?"
→
This is faster than waiting for user testing to surface obvious problems. Use it before prototype sharing to pre-empt the most predictable feedback.
Claude Code
6
Use Claude to explain your work to non-designers
Turn design rationale into stakeholder-ready language without writing it yourself.
→
"Read the screens in /app/checkout. Write a 5-sentence explanation of the design decisions for a product manager who wants to understand why the flow works the way it does."
→
"We're presenting the design system to a CEO. Write a one-paragraph summary of what we built, why it matters for the product, and what it enables going forward."
→
"Generate a slide outline for a design review of this sprint's work what we changed, why, and what we'll work on next."
Claude Codestakeholders
7
Teach Claude your taste over time
Within a session, be explicit about what you like and dislike. It compounds.
→
When something hits right: "This is exactly the right density. Remember this and match it on all subsequent screens."
→
When something misses: "This feels too structured I prefer when things feel a bit more conversational and less form-like. Adjust your approach going forward."
→
Add the most important taste preferences to CLAUDE.md so they persist across sessions: "The designer prefers high-contrast, low-density screens. When in doubt, remove rather than add."
→
Claude Code now keeps an automatic per-project memory across sessions: useful ambient recall, but don't rely on it for anything load-bearing. CLAUDE.md and skill files are the curated memory: deliberate, versioned, reviewable, and portable. Auto-memory (on by default now, and worth auditing with
/memory) is what Claude happened to note; CLAUDE.md is what you decided matters.CLAUDE.md is your persistent design voice. Treat it like a living style brief that captures not just rules but preferences how you like things to feel, not just how they should be built.
Claude CodeCLAUDE.md
8
Spot-check with real device previews
Browser DevTools is not a phone. Always check Vercel preview URLs on a real device before sharing externally.
→
After every significant session, push your branch and open the Vercel preview on your actual phone. Things that look fine at 390px in DevTools often feel wrong on a real screen.
→
Common real-device issues: touch targets that feel too small even if they pass the 44px rule, font sizes that feel right at desktop but strain on mobile, scroll behavior that works in Chrome but misbehaves in Safari.
→
When something feels off on device: describe it to Claude in physical terms "The button feels hard to reach with my thumb in the bottom-right corner" not in pixels.
Vercelmobile
9
Upload screenshots to show Claude exactly what you mean
A screenshot communicates what a paragraph of description can't. Use them liberally both targeted crops and full-screen context shots.
→
Full-screen screenshots: Upload the whole screen when you want Claude to understand layout, hierarchy, and how elements relate to each other. Useful for "this doesn't feel right" feedback where the problem is compositional, not isolated to one element.
→
Targeted crops: Crop tightly to the specific element or region you're talking about when the issue is precise a misaligned button, an icon that's the wrong weight, a border that looks off. Removes ambiguity about what you're referring to.
→
Before and after pairs: Screenshot the current state, make a quick annotation or sketch of what you want, upload both. Claude responds to the contrast between them more accurately than to a written description of the change.
→
Reference screenshots: If you've seen something you like somewhere else a layout, a button treatment, a spacing rhythm screenshot it and upload it alongside your prompt. "I want the card spacing to feel like this."
→
Side-by-side comparisons: Screenshot two versions of the same screen and ask Claude to identify which is better and why useful for breaking decision paralysis or getting a second opinion on a direction.
→
Let Claude take its own screenshots: With browser tooling connected (Claude Code's built-in preview, or the Playwright MCP server), Claude can screenshot the running app itself, compare against what you asked for, and iterate until it matches, without you in the loop for every round. Your uploads are for taste and intent; the agent's own screenshots are for verification.
The most efficient debug loop: screenshot the problem, upload it, say one sentence about what's wrong. Claude will identify the issue and fix it faster than if you describe the same thing in three sentences without a visual. And for anything mechanical, like "make it match", hand the camera to Claude and let it verify its own work.
Claude Codescreenshots
10
Build your HTML/CSS literacy to improve your prompting
You don't need to write the code. You need to understand it well enough to direct it precisely.
→
The more you understand how HTML/CSS works, the more specific your prompts become and specificity is what separates a prompt that needs 4 correction rounds from one that lands first time. You're not learning to code; you're learning the vocabulary of the medium you're designing in.
→
Flexbox and grid are the two layout models behind almost every screen. Knowing the difference and when to use each means you can say "use a flex row with space-between for the header" instead of "make the title on the left and the button on the right." The first prompt produces exactly what you want; the second invites interpretation.
→
The box model margin, padding, border, width explains most spacing problems. When something feels too cramped or too loose, knowing whether it's a padding or a margin issue lets you say "reduce the padding inside the card" vs "reduce the gap between cards." These are different fixes.
→
CSS custom properties (variables) are how your token system works. Understanding that
var(--color-action-primary) references a value defined in tokens.css lets you catch when Claude hardcodes a hex instead of using a variable and correct it immediately.→
Specificity and inheritance explain why a style isn't applying knowing that a class overrides an element selector, or that color inherits but border doesn't, means you can diagnose "this isn't working" faster and prompt the fix correctly.
→
Responsive units px vs rem vs % vs vw matter for mobile-first design. Knowing that rem scales with the root font size lets you say "use rem for font sizes so they respect user preferences" rather than accepting whatever Claude defaults to.
→
Transitions and transforms are the vocabulary of motion. "Translate Y by 4px on hover with a 150ms ease-out" is a precise prompt. "Make it feel interactive on hover" is not. A basic understanding of transition syntax turns motion feedback from vague to exact.
The fastest way to build this literacy: when Claude generates something that looks right, read the CSS it produced. Ask it to explain any property you don't recognize. After a few weeks of this the vocabulary sticks not because you studied it, but because you saw it solve real problems in your own screens.
Claude CodeHTML/CSS
11
Responsive web presentations from your design system
Use the same stack you design in to build presentation decks. Your tokens, components, and real screenshots in a shareable URL anyone can open.
→
One prompt to scaffold: Ask Claude Code to generate a presentation view using your existing design tokens and components. "Create a slide deck view at /present that uses our token system. I'll fill in the slides, but it should match our visual language and be responsive down to tablet."
→
Real screenshots, not mockups: Because your flows are live code, you can screenshot actual screens into presentation slides. No re-creating anything in Keynote what stakeholders see in the deck is exactly what ships.
→
One URL to share: Deploy to a Vercel Preview and send a single link. Stakeholders can open it on their phone, tablet, or laptop without needing Figma access, a specific app, or a file download.
→
Keyboard-navigable: Ask Claude Code to add arrow key and swipe navigation so the deck feels like a proper presentation while still being a webpage. You can present directly from a browser with no extra tools.
Keep the presentation route in the same repo as the design system. When tokens update, the deck updates automatically no hunting down outdated brand colors in an old Keynote file.
Claude CodeVercelpresentation
12
Use the harness: plan mode, checkpoints, hooks
Three built-in Claude Code features that replace habits this workflow used to require willpower for.
→
Plan mode (shift+tab): for any multi-screen task, let Claude propose the plan before it touches a file. You review the approach the way you'd review a design brief; it's cheaper to correct a plan than a build.
→
Checkpoints (/rewind): every prompt is automatically checkpointed. When an iteration goes sideways, rewind to the last good state instead of prompting your way back. This makes bold exploration free: you can always get back.
→
Hooks are enforcement, not suggestion: a hook that scans edits for hardcoded hex values and rejects them is stronger than any "never hardcode colors" line in CLAUDE.md. Move your most-violated absolute rules from instructions into hooks. Instructions can be forgotten; hooks fire every time.
The rule of thumb: preferences belong in CLAUDE.md, invariants belong in hooks. If breaking a rule would corrupt the design system (hardcoded values, pushes to main, edits to /components/ui), it's an invariant.
Claude Codehooks
13
Design the loop, not just the prompt
The discipline now has a name: loop engineering. Instead of prompting the agent yourself, you design the system that prompts, verifies, and stops it. You already run loops throughout this playbook; naming the parts lets you tune them.
→
A loop has four parts: a trigger (what starts the work), a topology (one agent or several, and how they relate), a verifier (how the loop knows the output is right), and stop rules (when it must halt or escalate to you).
→
The verifier is the designer's seat of power. Separate the builder from the verifier: a fresh agent (or a different model) checks the work against your skill files and the rendered browser, rather than the builder grading its own output. Self-review passes things independent review catches.
→
Stop rules are your failure-mode defenses made explicit: cap iterations at two before reframing, require agent-verified screenshots before "done", and force escalation when a change touches brand tokens or a11y rules.
→
The pieces you have already built map straight onto this: hooks are triggers and gates, the a11y and consistency audits are verifiers, the ESCALATE classification in the weekly sync is a stop rule. Loop engineering is the frame that ties them into one system.
The shift in one sentence: stop prompting your agents and start designing the loops that prompt them. Your quality gates are not overhead on the loop; they are the loop.
Claude Codeloop engineering
Foundation
When things go wrong
The most common failure modes in this workflow what causes them, what the symptoms look like, and how to recover. Each failure has a pattern: read it once so you recognize it fast when it happens.
1
Wrong style from the start
brand.md wasn't loaded before the session, or CLAUDE.md doesn't link to it explicitly. Auto-memory might recall fragments, but nothing guarantees brand context is loaded unless you've wired it in.
→
Symptom: Generated screens look like generic shadcn. Correct structure, wrong feel. Primary color is blue. Fonts are system defaults.
→
Fix: "Read /skills/brand.md and /styles/tokens.css before doing anything." Re-run the last task. Add this as the first line of CLAUDE.md so it's automatic.
→
Prevention: The "Current status" section in CLAUDE.md should include: "Always read /skills/brand.md at the start of any design task."
2
Design system drift
tokens.css was updated but not reflected in components. Hardcoded values were introduced during a quick fix.
→
Symptom: Specific components show wrong colors or spacing after a merge. Some screens look fine, others don't. The breakage is inconsistent.
→
Fix: "Scan all files in /app and /components for any hardcoded color or spacing value that should be a CSS variable from tokens.css. List every occurrence with the file and line number."
→
Prevention: Never rename a token without asking Claude to find all usages first. Treat token renames as breaking changes, log them in the decision log and flag engineering.
3
Stuck in an iteration loop
Claude is optimizing the thing you have rather than reconsidering the approach.
→
Symptom: After 3–4 iterations, the screen is still fundamentally wrong even though individual changes are technically correct.
→
Fix: Stop iterating. Reframe: "Forget the current version. What's the simplest screen that achieves [the goal]? Start from scratch." Or: "What's wrong with the current approach, not the execution, the approach itself?"
→
Prevention: Set a personal limit of 2 iterations before reframing. See Tips & tricks for the full reframing technique.
4
Visual problems need screenshots, not descriptions
Screenshots are not optional when something looks wrong.
→
Cause: You're describing a visual issue in words "the spacing looks off," "the colors don't feel right" without showing Claude what you're looking at. Claude is making edits against its mental model of the screen, not the real thing.
→
Symptom: Claude makes a change that's technically responsive to your words but misses the actual visual problem. Multiple rounds of corrections that each partially fix something but introduce something else.
→
Fix full screenshot: Take a screenshot of the whole screen and upload it with your prompt. Use it when the problem is about layout, hierarchy, or how elements relate to each other. "[screenshot] The spacing between sections feels inconsistent fix it."
→
Fix targeted crop: Crop tightly to the specific element when the issue is precise. "[cropped screenshot of button] This feels too heavy relative to the label next to it. Reduce the visual weight." Targeted crops remove ambiguity about which element you mean.
→
Fix annotated screenshot: Draw a circle or arrow on the screenshot to point at exactly what's wrong before uploading. Takes 10 seconds and eliminates the most common source of misunderstanding in visual feedback.
→
Prevention: Default to uploading a screenshot for any visual feedback. Words-only prompts for visual problems are slow and imprecise. The screenshot is not extra work it's the fastest path to a correct fix.
→
Prevention, automated: With browser tooling connected (the same setup as "Let Claude take its own screenshots" in Tips & tricks), Claude sees the rendered screen itself before declaring a task done and catches "technically responsive, visually wrong" before you do.
The rule of thumb: if you're describing what something looks like in order to explain what's wrong, stop and take a screenshot instead. Show, don't describe.
Claude Codescreenshots
Design system Step 1
Prepare your brand input
Claude Code needs everything in text or pasteable form. Convert assets before you open the terminal.
1
What to gather before opening Claude Code
→
Logo: SVG source file path + usage rules (min size, clear space, approved lockups, what not to do).
→
Typography: Font names, weights in use, size scale, line-height rules, when to use each typeface.
→
Colors: All hex values labeled primary, secondary, neutrals. Include proportion rules (e.g. "primary at 10%, neutral at 80%, accent at 10%"). If the values aren't handy, a screenshot works paste a brand swatch, style tile, or color panel directly into the terminal and Claude will extract the values.
→
Accessibility colorways: Which combinations pass WCAG AA/AAA, and which are explicitly off-limits.
→
Illustration + iconography: Style description (stroke weight, corner radius, fill vs outline), source folder path, naming conventions. You can drag a folder of SVGs directly into the terminal window, or point Claude Code at an open-source library e.g. "Use Phosphor Icons from node_modules/phosphor-react" and it will reference them by name throughout the build.
→
Photography: Art direction notes mood, subjects, what to avoid.
→
If your brand already lives in Figma: connect the Figma MCP server and Claude can read your variables, text styles, and components directly no manual transcription. Ask it to generate the first draft of brand.md from the Figma library, then edit for accuracy.
Whatever the source PDF, Figma, or screenshots the destination is the same: a plain-text brand.md. Claude can extract values from images and Figma files, but text in the repo is what every future session, audit, and agent reads reliably.
2
Complete brand.md example
The single file everything downstream derives from. Fully worked, replace values with your own brand.
# /skills/brand.md
## Identity
Product: [Name] [one-line description of what it does and for whom].
Positioning: [e.g. "the approachable alternative to X"].
Tone: [3 words e.g. warm, direct, human].
Never: formal, legalistic, passive voice, jargon, corporate-speak.
## Logo
Primary file: /assets/logo/logo.svg
Wordmark only: /assets/logo/logo-wordmark.svg
Clear space: 16px minimum all sides.
Minimum size: 24px height on screen.
Approved on: white, [primary bg color], dark backgrounds.
Never: stretch, rotate, recolor, place on busy backgrounds,
use the icon without the wordmark in UI contexts.
## Typography
Primary typeface: [Font name]
Use for: all UI headings, labels, buttons, body.
Weights in use: 400 (regular), 500 (medium), 600 (semibold).
Never use 700+ weight too heavy at mobile sizes.
Secondary typeface: [Font name or "none"]
Use for: editorial moments only (marketing, splash screens).
Never in: forms, navigation, data displays.
Type scale (px):
xs: 12 captions, legal, metadata
sm: 14 secondary body, form hints
md: 16 primary body text (base)
lg: 20 section leads, card titles
xl: 24 screen titles
2xl: 32 hero headings
3xl: 40 marketing only
Line height: 1.5 body / 1.2 headings / 1.0 buttons and labels.
Letter spacing: -0.01em headings / normal body.
## Color system
# Primitives raw values, never used directly in UI
brand-50: [lightest tint]
brand-100: [light tint]
brand-500: [main brand color] ← primary identity color
brand-900: [darkest shade]
neutral-0: #FFFFFF
neutral-50: [off-white main surface]
neutral-100: [light gray]
neutral-500: [mid gray]
neutral-900: [near-black primary text]
# Semantic use these in components, never primitives
action-primary: brand-500 ← CTAs, links, active states
action-on-primary: neutral-0 ← text on action-primary bg
surface-default: neutral-50 ← page and card backgrounds
surface-raised: neutral-0 ← elevated surfaces
text-primary: neutral-900 ← body text
text-secondary: neutral-500 ← supporting text
text-disabled: neutral-300
border-default: neutral-100
danger: [red hex] ← errors, destructive actions
warning: [amber hex] ← caution states
success: [green hex] ← confirmations
## Color proportions (per screen)
Neutral surfaces: ~80% backgrounds, cards, inputs.
Brand primary: ~10% CTAs, key highlights, active states only.
Accent/warm: ~10% empty states, illustrations, celebrations.
Rule: if a screen feels colorful, there's too much brand color.
## Accessibility
Standard: WCAG 2.2 AA minimum on all text. AAA preferred for body.
Approved pairs (tested):
[neutral-900] on [neutral-50] ✓ AAA
[neutral-0] on [brand-500] ✓ AA
[neutral-900] on [neutral-0] ✓ AAA
Failing pairs (never use):
[brand-500] on [neutral-50] ✗ fails AA
[neutral-500] on [neutral-0] ✗ fails AA for small text
## Iconography
Library: Lucide React
Stroke weight: 1.5px never change this.
Sizes: 16px (inline/compact) or 24px (standalone) only.
Style: always outline never filled.
Custom icons: /assets/icons/ must match Lucide stroke style.
When no Lucide equivalent: use a simple geometric SVG from Claude,
not an image or emoji.
## Illustration
Style: flat, minimal, warm think editorial not technical.
Palette: brand palette only no additional colors in illustrations.
Detail level: low clarity over complexity at small sizes.
Subjects: objects and abstract shapes avoid depicting people.
Files: /assets/illustrations/ WebP + SVG where possible.
Usage: empty states, onboarding, error screens, celebrations.
## Photography
Mood: natural light, real environments, candid not posed.
Subjects: [relevant to your product context].
Avoid: stock photo aesthetics, artificial staging, excessive filters.
Format: WebP, max 200kb, explicit width/height attributes always.
## Motion principles
Default: no animation unless it communicates state or transition.
Duration: 150–250ms for micro-interactions, 300ms for transitions.
Easing: ease-out for entrances, ease-in for exits.
Always add: prefers-reduced-motion override (see /skills/a11y.md).
Claude Codeskills/brand.md
Design system Step 2
Scaffold the design system
One prompt to go from brand file to a working, themed shadcn scaffold.
1
The initial Claude Code prompt
Read /skills/brand.md carefully before starting.
Scaffold a modern design system using shadcn/ui and
Tailwind CSS v4 (CSS-first config no tailwind.config file)
based on the brand defined in brand.md. Generate:
1. /styles/tokens.css
CSS custom properties for all colors, type scale,
spacing scale (4px base unit), border-radius, shadows.
Define values in :root and .dark.
2. /styles/globals.css
@import "tailwindcss";
@theme inline block mapping Tailwind + shadcn tokens
(--color-primary, --color-secondary, etc.)
to our CSS variables from tokens.css.
Base typography rules.
3. /components/ui/ themed shadcn components:
Button, Input, Card, Badge, Alert, Select, Dialog.
Install via the shadcn CLI do not hand-write them.
4. /app/design-system/page.tsx
Living style guide showing every token and component
in context. Renders at /design-system route.
Follow color proportions in brand.md.
Flag any accessibility conflicts you find.
Tailwind v4 moved configuration into CSS; the old
tailwind.config.ts is legacy. This is good news for this workflow: the entire theme now lives in the same tokens.css + globals.css pair that is already your source of truth. One less file for values to drift into.Claude CodeshadcnTailwind v4
2
What to review after generation
→
tokens.css: Check every hex value matches brand.md exactly. Errors here cascade everywhere.
→
The @theme mapping in globals.css: Confirm shadcn color variable mappings are correct
--color-primary should map to your brand color, not shadcn's default. This mapping is where "generic shadcn" sneaks in.→
Visual pass: Open
/design-system in browser. Does it feel like your brand, or generic shadcn?→
A11y flags: Resolve all color contrast issues before using the system don't defer accessibility to later.
→
Dark mode: Check globals.css
.dark block shadcn's default mappings need manual verification against your brand's dark colorway.The living style guide at
/design-system is your Figma replacement for system-level review. Share the Vercel preview URL stakeholders see the real thing, not a mockup of it.3
The system you're building is agent context
Every artifact from this step does double duty: it renders the product, and it's what the agent reads before generating anything new. A design system that agents can consume is the difference between on-brand output and generic output.
→
Without design context loaded, every agent produces the same generic UI. That's not a model limitation; it's a context problem. Your tokens, component library, and skill files are the fix. The industry term for a system structured this way is an agentic design system.
→
Connect the shadcn MCP server so Claude can search registries and install components directly instead of hand-writing approximations. Registries are namespaced, so your own private registry can sit alongside the public one as the team grows.
→
The payoff compounds beyond generation: teams that made their design systems agent-readable report the system starts answering its own support questions; a Miro design engineer reported a 70–80% drop in design-system Slack questions after wiring theirs up to agents.
shadcn MCPMCPClaude Code
Design system Step 3
Export design tokens for dev
Generate design-tokens.json before building any screens. This gives engineering the token contract early so both sides work from the same source of truth from day one.
1
Generate the token file
Read /styles/tokens.css and /styles/globals.css.
Generate /tokens/design-tokens.json in W3C Design Tokens
format (DTCG, stable spec 2025.10). Include:
color: all values grouped by role
(primitive → semantic → component-level)
typography: families, size scale, weights,
line heights, letter spacing
spacing: full scale from 4px base unit
border-radius: all radius values
shadow: elevation tokens
motion: duration and easing if defined
For each token include: value, type, description,
and the CSS variable name it maps to.
Also generate:
/tokens/design-tokens.ios.json (pt units for iOS)
/tokens/design-tokens.android.json (sp/dp for Android)
Claude Codetokens/
2
Token structure primitive → semantic → component
Three layers. Each builds on the one before.
// design-tokens.json (DTCG format)
{
"color": {
"primitive": {
"brand-500": {
"value": "#______",
"type": "color",
"description": "Base primary brand color"
}
},
"semantic": {
"action-primary": {
"value": "{color.primitive.brand-500}",
"type": "color",
"description": "CTAs, links, active states",
"css-variable": "--color-action-primary"
}
}
}
}
Primitives are raw values. Semantics describe intent. Component tokens (e.g.
button-bg-primary) are optional but valuable for native platforms. The three-layer structure is what makes the JSON useful to engineering not just a color dump.3
Keep tokens in sync as the system evolves
→
Treat
design-tokens.json as a build artifact regenerate it whenever tokens.css changes, not manually.→
When tokens.css changes, ask Claude: "Regenerate design-tokens.json and flag any tokens that were renamed or removed." Surfaces breaking changes before they hit a PR.
→
Version the token file with the same git tags you use for design milestones.
→
Re-run the export after pattern consolidation new component-level tokens will have emerged from the flow-building phase.
→
Engineering uses Style Dictionary to transform the JSON into CSS variables, SCSS maps, Swift UI color assets, or Android XML resources they pick the format their stack needs.
→
The DTCG format reached its first stable version in late 2025 and the ecosystem consolidated around it: Style Dictionary, Tokens Studio, and Figma variables all speak it. It's also the most agent-legible format your tokens can be in: a structured JSON file any model can read, reason over, and audit against. Tokens stopped being just build input; they're agent input now.
Claude CodeterminalStyle DictionaryDTCG
Design system Step 4
Accessibility audit
Accessibility is built in from the token level up not checked at the end. Run a proactive audit immediately after scaffolding, then again after every major build phase. The modern pattern is two layers: deterministic scanners (axe-core, Lighthouse) catch the mechanical violations in CI, and the agent sits on top doing what scanners can't: judging whether alt text is actually descriptive, whether focus order is logical, whether a screen is technically compliant but practically unusable. The prompts below are that judgment layer.
1
Token-level audit before any screens are built
The cheapest place to catch a11y issues is in tokens.css, before a single component uses a failing value.
Read /styles/tokens.css and /skills/brand.md.
Run a full accessibility audit on the color token system:
1. Test every foreground/background color pair defined
in the semantic layer against WCAG 2.2 contrast ratios.
Flag: AA fail (<4.5:1 normal, <3:1 large text),
AAA fail (<7:1 normal) note both thresholds.
2. Identify any semantic token combinations that are
used together in components but have no contrast check.
3. Check that every interactive state (hover, focus,
active, disabled) has sufficient contrast in both
light and dark mode.
4. Output a report: passing pairs ✓, failing pairs ✗,
and a suggested fix for each failure (adjusted hex
value that passes AA while staying close to the brand).
Fix contrast failures at the token level one change in tokens.css fixes every component that uses that pair. Fixing it per-component is 10x the work and always incomplete.
Claude Codea11y
2
Component-level audit after scaffold, before flows
Each generated shadcn component checked for focus behavior, ARIA, and touch targets before it ships to any screen.
Read all files in /components/ui.
For each component, audit:
FOCUS
Does every interactive element have a visible focus ring?
Is focus order logical within the component?
Can the component be fully operated by keyboard alone?
ARIA
Are roles, labels, and descriptions correctly applied?
Do icon-only buttons have aria-label?
Are error states announced to screen readers?
TOUCH TARGETS
Are all tap targets at least 44x44px on mobile?
Is there sufficient spacing between adjacent targets?
MOTION
Does any animation respect prefers-reduced-motion?
Output per component: pass ✓ | fail ✗ | needs review ⚠
For each failure, cite the line and suggest the fix.
Claude Codea11y
3
The a11y skill file
Encode your accessibility standards so every future component Claude generates is built to them from the start.
# /skills/a11y.md
## Standards
Target: WCAG 2.2 AA minimum. AAA where feasible.
Platform: mobile-first. All touch targets 44x44px minimum.
## Color
Never communicate meaning through color alone.
Always pair color with a label, icon, or pattern.
Approved contrast pairs: [generated from token audit]
Failing pairs never to use: [generated from token audit]
## Focus
Every interactive element must have a visible focus ring.
Use: outline: 2px solid var(--color-action-primary); outline-offset: 2px
Never remove outline without providing an alternative.
## ARIA
Icon-only buttons always need aria-label.
Form inputs always need associated label elements (not placeholder only).
Error messages use role="alert" so they're announced immediately.
Loading states use aria-live="polite".
## Motion
All animations must respect:
@media (prefers-reduced-motion: reduce) { animation: none; }
## Audit cadence
Run token audit: after any token change.
Run component audit: after any component update.
Run full screen audit: weekly, on the system branch.
Claude Codeskills/a11y.md
4
Ongoing screen-level audit on the weekly branch
Run a full screen audit as part of the weekly system branch before merging catches issues that only appear when components are combined on real screens.
Read /skills/a11y.md. Read all files in /app.
Run a full accessibility audit across all screens:
1. Re-check all color pairs in context (components
on real backgrounds, not just isolated tokens).
2. Verify heading hierarchy per screen no skipped levels.
3. Check that all images have meaningful alt text or
are marked decorative with aria-hidden="true".
4. Verify every form has proper label associations,
error handling, and success confirmation.
5. Check reading order matches visual order on mobile.
Output: screen-by-screen report with pass/fail/warn.
Group failures by severity: critical | moderate | minor.
Critical issues block the weekly merge.
Critical a11y failures block the weekly merge treat them the same as a broken build. Moderate and minor issues get logged to the decision log with a resolution deadline.
Claude Codea11yweekly branch
Design system Step 5
Publish your design system site
A living public site generated from your codebase, auto-updated on every merge. Engineering has a single URL to bookmark. The changelog writes itself. The system is never more than a week out of date.
1
Generate the minisite route
One prompt to go from codebase to a live, branded design system reference.
Read /skills/brand.md, /styles/tokens.css, and all files
in /components/ui.
Generate a design system documentation site at /app/design-system.
Include:
1. Token reference: every color, spacing, radius, shadow,
and typography token displayed in context with its CSS
variable name and current value.
2. Component gallery: every shadcn component in use,
rendered in our brand theme, with a code snippet showing
how to use it.
3. Pattern library: any composite patterns in /components
that combine multiple primitives (e.g. form layouts, card
variants, empty states).
4. Changelog: pull from /decisions/changelog.md and render
as a versioned list with dates and descriptions.
The site should use our existing tokens and components.
Deploy to /design-system route, accessible at the Vercel
preview URL without authentication.
→
Every element on the page is live code, not screenshots. Engineering sees the real component, not an image of it.
→
The token reference auto-reflects the current values of tokens.css: if you update a color, the minisite shows the new value after the next merge.
→
Deploy as its own Vercel project if you want a stable permanent URL separate from your app previews. Link from README and share with engineering on day one.
Claude CodeshadcnVercel
2
Auto-generate the changelog
After every weekly merge, Claude reads the diff and writes the entry. No manual changelog maintenance.
Read the git diff between design-system/week-of-[date]
and main.
Write a changelog entry for /decisions/changelog.md.
Format:
## [date] - Week of [date]
### Added
- [new tokens, components, or patterns introduced]
### Changed
- [tokens or components with updated values or behaviour]
### Deprecated
- [anything scheduled for removal, with replacement]
### Fixed
- [a11y issues, visual regressions, or token drift resolved]
Be specific: name the token or component, describe the
change, and explain why if the decision log has context.
Skip sections with no changes. Keep entries brief.
→
Commit the changelog entry as part of the weekly merge PR; it becomes the PR description and the changelog simultaneously.
→
The changelog on the public minisite is the authoritative record of system evolution. Engineering can see exactly when a token changed and why, without asking.
→
Over time, the changelog becomes a design history that new team members can read to understand why the system is the way it is.
Claude Codegitchangelog
3
Weekly merge discipline keeps the site current
The minisite is only as fresh as the last merge. The weekly branch cadence is what makes it a live reference, not a stale archive.
→
Set a recurring calendar reminder every Friday to open a PR for the week's design-system branch. Treat it the same as a sprint close: it's not done until it's merged.
→
If a week's branch has nothing to merge, the reminder is still useful: it confirms the system is stable and nothing drifted. Log "no changes this week" in the changelog.
→
Add a CLAUDE.md reminder: "Each Friday, remind me to open a PR for the current design-system branch and generate the changelog entry." Claude will surface this at the start of Friday sessions.
→
The merge is also the signal to regenerate
design-tokens.json and notify engineering that a new token version is available for the next sprint.A design system site that's weeks out of date stops being a reference and starts being a source of confusion. The weekly merge discipline is the system's maintenance schedule.
gitprocess
4
Share it and replace Figma as the reference
The minisite is the source of truth. Engineering bookmarks it. Stakeholders check it. The Figma library becomes optional.
→
On day one of a new project, share the design system URL with engineering leads. Frame it explicitly: "This is the component reference. If you're unsure how a component behaves, check this first."
→
Add the URL to the project README and the engineering onboarding doc. New developers should encounter it before they encounter Figma.
→
For pre-release or confidential work: Vercel's password protection feature locks the minisite behind a single shared password. Remove it when the product launches publicly.
→
The minisite also serves as a design portfolio artifact: stakeholders can see the maturity and consistency of the system without needing a Figma account or a design walkthrough.
→
The minisite is the human-readable surface of the system. Agents consume the same system through its machine-readable surfaces: tokens.css, the DTCG export, skill files, and MCP servers. Keep both surfaces generated from the same source and neither can drift from the other.
Vercelprocess
Building Step 6
Build major flows
Start with one flow end-to-end. Build it completely before moving to the next. Let inconsistencies surface naturally you'll extract them into patterns later.
1
Build one flow completely before starting the next
→
Pick the most critical user journey onboarding, core action, checkout and name all the screens it needs before generating anything.
→
Ask for all screens in one pass first rough but complete. You want the full shape before refining anything.
→
Review in the browser, not the code. Note observations in plain language: "the form feels too dense," "the success state doesn't feel warm enough."
→
Feed those observations back directly and specifically: "Increase vertical spacing between fields and reduce visible fields to 3 at a time."
Be specific about what you like too not just what to fix. "The progress indicator on step 3 is exactly right" gives Claude a reference point to match elsewhere.
Claude Codeterminal
2
Tweak in conversation, not in code
→
Use plain design language: "The button feels too heavy here make it a ghost variant," or "This card needs more breathing room."
→
Reference other screens when something works: "Match the empty state treatment from the dashboard screen."
→
If a direction isn't working after 2–3 tries, restate the goal rather than the fix: "This screen should feel like a moment of reassurance, not a form."
Claude Code
3
Build the next flow, then compare
→
Build your second major flow the same way. Don't try to enforce consistency yet just build.
→
Once two or three flows exist, divergences will appear different card treatments, inconsistent spacing, slightly different button behavior. That's expected and useful data.
→
The divergences are your signal to move to pattern extraction. Don't fix them inline extract them.
4
Definition of done for a flow
A flow is complete when it covers these bases, not before.
→
Happy path: Every screen from entry to completion exists and renders correctly in the browser.
→
Empty states: What does each screen look like before the user has done anything? No placeholder text, no lorem ipsum.
→
Error states: What happens when something fails? Form validation, network error, not-found. These are design decisions, not engineering ones.
→
Loading states: Skeleton screens, spinners, or optimistic UI: decided and implemented, not deferred.
→
Mobile: Checked in the browser at 375px. Layout holds, tap targets are reachable, text doesn't overflow.
→
Agent-verified: Claude has walked the flow itself with browser tooling: clicked through every screen, exercised every state, screenshotted each one, and flagged anything broken, overflowing, or off-system. Not a substitute for your own review; the floor beneath it.
→
Deployed: Live on a Vercel preview URL. Shareable with a link, not a screenshot.
If you skip error and loading states, engineering will either invent them or skip them. Either way, the design decision was made without you.
Building Step 7
Canvas & prototype views
Do this after your first flow is complete, not before. The canvas is how you spot structural problems: missing states, awkward transitions, flows that seem fine screen-by-screen but break down when seen as a sequence. It's a review step, not a build step: build first, then zoom out here before starting the next flow.
Canvas view
For you
All screens on a zoomable canvas, grouped by flow. Evaluate structure, spot gaps, direct changes at a macro level.
Prototype view
For sharing
Single flow, mobile-framed, click-through. Shareable URL for user testing and stakeholder review.
1
flows.config.ts the register both tools read from
→
Build both tools to read from a central
flows.config.ts. Adding a new screen = one line in the config. Both views update automatically.→
Ask Claude to generate the initial config: "Scan /app and generate flows.config.ts mapping each flow to its ordered screen components."
// flows.config.ts
export const flows = [
{
name: "[Flow 1 name]",
screens: [Screen1, Screen2, Screen3, Screen4]
},
{
name: "[Flow 2 name]",
screens: [EntryScreen, FormScreen, ReviewScreen,
PendingScreen, SuccessScreen, ErrorScreen]
}
]
Claude Code
2
Build the canvas view at /canvas
Build a canvas view at /app/canvas/page.tsx
that reads from flows.config.ts.
Requirements:
Infinite canvas: pannable with click-drag, zoomable
with scroll or pinch (CSS transform, no libraries).
Each screen rendered at ~25% scale inside a labeled
phone frame. Screen name shown below.
Click any screen to expand full size in an overlay.
Screens grouped by flow with flow label above each group.
Arrange groups left to right.
Mini-map in bottom-right showing canvas position.
Toolbar: zoom in/out, fit-to-screen, flow-jump dropdown.
Add /canvas to CLAUDE.md as a protected design-only route
never ships to production.
→
Use fit-to-screen to get the macro view first look at flow length, visual weight, whether the progression feels right end-to-end.
→
Compare equivalent screens across flows e.g. the success state in Flow 1 vs. the success state in Flow 2. Inconsistencies are obvious at this scale.
Claude Codeterminal
3
Build the prototype view at /prototype/[flow]
Build a prototype viewer at /app/prototype/[flow]/page.tsx
that reads from flows.config.ts.
Requirements:
Centered 390px mobile frame on a neutral dark background.
Tap/click advances to next screen. Back arrow goes back.
Step counter at top of frame showing position in flow.
Flow selector dropdown outside the frame.
"Copy link" button copies URL with flow + step as query
params shared link opens at the exact screen.
Left/right arrow key navigation.
No UI chrome inside the phone frame.
Deploy at /prototype/[flow-1-name], /prototype/[flow-2-name].
→
Push branch → Vercel preview URL → share with testers. Opens in mobile browser, looks like a real app.
→
Use deep links to send stakeholders directly to the specific screen you want feedback on.
→
Ask Claude Code to generate a user testing script: "Write a 5-task testing brief for the [flow name] flow based on flows.config.ts."
Tag before every review session
git tag v0.3-user-test. You can always share the exact version a stakeholder or tester saw, even after screens have changed.Claude CodeVerceluser testing
Building Step 8
Localization
Treat copy the same way you treat color as a token, not hardcoded text. Structure it from the start and localization becomes a content swap, not a rebuild.
1
Content tokens the same pattern as design tokens
Separate copy from layout the same way you separate color from structure. One source file per locale, one token per string.
→
Store all UI copy in locale files
/locales/en.json, /locales/es.json, /locales/fr.json structured the same way design tokens live in tokens.css. Keys are semantic, not descriptive: onboarding.cta.primary, not get-started-button-text.→
Never hardcode strings in components. Every piece of visible copy labels, errors, empty states, tooltips references a content token. Claude Code will enforce this if you add it to CLAUDE.md: "All visible copy must reference a key in /locales/en.json. No hardcoded strings in components."
→
Ask Claude to audit for hardcoded strings before the first locale is added: "Scan all components in /app and /components for hardcoded UI strings. Generate a /locales/en.json with every string extracted and keyed semantically."
→
Use i18next or next-intl both integrate cleanly with Next.js and are easy for Claude to scaffold. The choice determines how locale files are loaded; the token structure is the same either way.
# /locales/en.json content tokens
{
"onboarding": {
"hero": {
"headline": "Get started in minutes",
"subtext": "No setup required. Connect your account and go.",
"cta": "Create your account"
},
"steps": {
"connect": "Connect your tools",
"configure": "Set your preferences",
"launch": "You're ready"
}
},
"errors": {
"auth.expired": "Your session expired. Please sign in again.",
"form.required": "This field is required."
}
}
Claude Codei18n
2
Language switcher in the canvas and prototype views
Evaluate copy across every market without leaving the browser. The switcher is a design tool, not a user-facing feature.
→
Extend the canvas view at
/canvas with a locale selector in the toolbar. Switching locale re-renders all screens with the selected language you see layout impact immediately: German strings that break a button, Arabic RTL that reflows a card.→
Do the same for the prototype view a locale toggle in the header so stakeholder reviews can be run in the target market's language, not just English.
→
This is the fastest way to catch layout issues early: string length varies dramatically by language. English is short. German is long. Arabic is RTL. These all need to be visible before a screen is considered done.
# prompt to add locale switcher to canvas view
Add a locale switcher to /app/canvas/page.tsx.
- Render a dropdown in the top toolbar with all locales from /locales/
- Switching locale passes the selected language to all child screen components via context
- The switcher state persists in localStorage so it survives page reloads
- Default to 'en' if no preference is stored
Claude Codecanvasi18n
3
Voice and tone per market
Translation is not localisation. Each market has its own register, formality level, and emotional expectations.
→
Add a voice and tone section to each locale's skill file not just the words, but the register. US English might be direct and casual. UK English more measured. German more formal. Japanese deferential. These are not style preferences they affect which word choices Claude makes when generating copy.
→
Store this in
/skills/copy-[locale].md alongside your existing copy.md: "For es-MX: warm and conversational, avoid formal usted constructions in UI copy, contractions are fine, error messages should feel reassuring not clinical."→
When generating or reviewing copy for a specific market, reference both the content token file and the locale skill file: "Read /locales/fr.json and /skills/copy-fr.md. Review all onboarding copy for voice consistency. Flag anything that reads like a literal translation rather than native French."
→
Use the prototype's locale switcher as a review tool with native speakers share the prototype URL with the locale pre-set, collect feedback directly against live screens rather than static copy docs.
Machine translation is a starting point, not a finish line. Generate the initial locale file with Claude, then have a native speaker review it against the voice and tone brief the combination is faster than either alone.
Claude Codei18ncopy
4
Localize continuously, not as a phase
The old model (build in English, localize at the end) is gone. With locale files structured as content tokens, localization runs alongside building, not after it.
→
Add the standing instruction to CLAUDE.md: "Whenever a new key is added to /locales/en.json, generate the corresponding entries in every other locale file using that locale's voice and tone skill file. Flag them as machine-drafted pending native review." New strings ship in every language by default.
→
For the initial backfill of a new market, run locales in parallel: one subagent per locale, each reading the English source and its own voice brief. Three markets land in the time of one (see the multi-agent appendix).
→
Native-speaker review becomes a rolling queue instead of a launch blocker: reviewers work through the machine-drafted flags in the prototype view, at their own pace, against live screens.
Claude Codei18nagents
Building Step 9
Extract & enforce patterns
Do this after your second major flow, not your first. Patterns only become visible through repetition; extracting from a single flow produces components that are too specific to generalize. Wait until you have enough surface area to see what actually repeats, then consolidate once rather than incrementally.
1
Ask Claude to find inconsistencies across all flows
Read all files in /app and /components.
Identify inconsistencies across these dimensions:
Spacing: are margins and padding consistent across
similar components?
Typography: are heading levels used consistently?
Buttons: are primary/secondary/ghost variants
used correctly and consistently?
Cards: how many different card treatments exist?
Should any be consolidated?
Empty states: consistent handling?
Error and loading states: same approach per flow?
Output a report grouped by dimension.
For each issue, cite the specific files and suggest
the canonical pattern to adopt.
Claude Code
2
Consolidate into named canonical components
→
Take the audit report and decide which pattern wins for each inconsistency. You make the call Claude surfaces the options.
→
Prompt Claude to consolidate: "The audit found 3 card treatments. The one in /app/dashboard/page.tsx is canonical. Refactor all others to match it and extract to /components/ui/ContentCard.tsx."
→
Name components for what they do in your app, not how they look:
StatusCard, TransactionRow, StepIndicator not BigCard or ListItemDark.→
After each consolidation, reload all flows in browser and verify nothing broke visually.
3
Ask the system to enforce canonical components everywhere
These are now the canonical components:
ContentCard → /components/ui/ContentCard.tsx
StatusBadge → /components/ui/StatusBadge.tsx
FormStep → /components/ui/FormStep.tsx
EmptyState → /components/ui/EmptyState.tsx
Scan all files in /app. Replace any inline implementations
of these patterns with imports of the canonical component.
Do not change visual output only refactor structure.
List every file you changed.
Run this after every major build phase not just once. Patterns drift as you add screens. A monthly consistency sweep keeps the system honest.
Claude Code
Building Step 10
Decision log & changelog
Set this up before your second flow, not after you've shipped. Decisions made in the first flow are still fresh; once you're in the third or fourth flow, the context for why you built the system a particular way is already gone. The log is worthless if it's written retrospectively.
1
The decisions skill file
Instruct Claude to log every significant design decision in a structured format as work happens not retrospectively.
# /skills/decisions.md
## Purpose
Log every significant design decision made during this project.
A decision is significant if it: changes a token value, introduces
or retires a component, establishes a new pattern, overrides a
brand rule, or resolves a conflict between design and engineering.
## Format one entry per decision
Each entry must include:
Date (YYYY-MM-DD)
Area: token | component | pattern | flow | brand | a11y
Decision: what was decided, in one clear sentence
Rationale: why the constraint, tradeoff, or insight
Affected: which files, components, or screens this touches
Status: active | superseded | under review
Decided by: designer name or "Claude (auto)"
## When to log
Log immediately when: a pattern is consolidated, a token is
changed, a component is retired, an escalation is resolved,
or a new canonical component is established.
## File location
All entries live in /decisions/log.json (structured)
and /decisions/CHANGELOG.md (human-readable summary).
Claude Codeskills/decisions.md
2
Logging decisions as you work
Add a standing instruction to CLAUDE.md so logging happens automatically, not as a separate step.
# add to CLAUDE.md:
After completing any task that involves a design decision
(token change, component update, pattern consolidation,
escalation resolution), append an entry to
/decisions/log.json following the format in
/skills/decisions.md. Do this automatically do not
ask for confirmation unless the decision area is "brand"
or "a11y", which require designer sign-off.
→
Because it's in CLAUDE.md, logging is passive it happens at the end of every task without you needing to prompt it.
→
Brand and a11y decisions are flagged for sign-off rather than auto-logged these are the choices with the most downstream risk.
→
You can also log manually mid-session: "Log a decision: we're using ghost buttons for all secondary actions in modal contexts. Rationale: reduces visual competition with the primary CTA."
Claude CodeCLAUDE.md
3
Generating the changelog
A human-readable summary derived from log.json regenerated weekly and versioned with each system merge.
Read /decisions/log.json.
Generate /decisions/CHANGELOG.md structured as follows:
## [Version / week tag] [date]
### Tokens
[list token changes with rationale summary]
### Components
[new, updated, or retired components with rationale]
### Patterns
[pattern consolidations or new patterns established]
### Escalations resolved
[decisions that required designer sign-off]
### Open / under review
[anything logged as "under review" status]
Keep each entry to one line. Link to the affected file
where relevant. Mark designer-approved items with ✓.
→
Regenerate the changelog at the end of every weekly system branch before merging it becomes the PR description and the permanent record.
→
Version the changelog alongside the token export: both get the same week tag so engineering can trace which decisions informed which token set.
Claude Codegit
4
Version history in the canvas view
Extend the canvas at /canvas to surface decision history and version snapshots alongside the live screens.
Extend /app/canvas/page.tsx to add a version history panel.
Requirements:
Version panel (right sidebar, collapsible):
Reads from /decisions/log.json
Lists entries grouped by week/version tag, newest first
Each entry shows: date, area badge, decision (one line),
decided-by label
Clicking an entry highlights the affected screens
on the canvas with a colored overlay
Filter by area: token | component | pattern | flow | all
Version switcher (toolbar):
Dropdown of all git tags with "design-system/" prefix
Selecting a tag checks out that version and reloads
the canvas so you can see exactly what the system
looked like at any past milestone
"Current" option always returns to HEAD
Changelog tab (bottom drawer):
Renders /decisions/CHANGELOG.md as formatted HTML
Searchable by keyword
Exportable as PDF for stakeholder sharing
→
The version switcher turns the canvas from a current-state view into a time machine you can show a stakeholder exactly what the system looked like before a major change.
→
The decision overlay (clicking an entry highlights affected screens) is the fastest way to answer "why does this look the way it does?" the rationale is one click away from the screen.
→
The changelog PDF export is useful for design reviews, quarterly retrospectives, or onboarding new team members.
The canvas version history is also a powerful tool for engineering conversations. When a token change is questioned, you can show the decision entry date, rationale, who approved it without digging through Slack or git blame.
Claude Codecanvasgit
5
Querying the decision history
Ask Claude to reason over past decisions not just retrieve them.
→
"Read /decisions/log.json. What decisions have we made about form patterns? Are any of them in conflict with each other?"
→
"A new engineer is joining. Generate a one-page summary of the most important design decisions made in the last 3 months and why."
→
"We're about to change the spacing scale. Read the decision log and flag any previous decisions that assumed the current scale those will need to be revisited."
→
"List all decisions with status 'under review' and suggest which ones are ready to be resolved based on the current state of the codebase."
The decision log becomes more valuable over time, not less. After 3–6 months it's a searchable institutional memory of why the system is the way it is which is exactly what gets lost when teams rely on Slack and verbal agreements.
Claude Code
Building Step 11
Content & copy
Copy is a design material: it lives in the system alongside tokens and components, not in a separate doc. Without a copy skill, Claude generates placeholder language that never gets replaced and ships. Setting this up means copy gets reviewed on every screen, not at the end of the project.
1
The copy skill file
Encode your voice, tone, and language rules so copy is never an afterthought.
# /skills/copy.md
## Voice
[Your product voice in 3 words e.g. warm, direct, human.]
Never: formal, legalistic, passive voice, jargon.
## Tone by context
Onboarding: encouraging, low-stakes, welcoming.
Errors: calm, specific, actionable. Never blame the user.
Success states: brief, warm don't over-celebrate.
Empty states: helpful, not apologetic. Show the path forward.
Destructive actions: clear and specific. State what will be lost.
## Button labels
Always verb-first and specific: "Save changes" not "OK".
Primary CTA: describes the outcome, not the action.
Good: "Send money" / Bad: "Submit"
Destructive: states what happens. "Delete account" not "Confirm".
Cancel: always "Cancel" never "No" or "Go back".
## Error messages
Structure: [what happened] + [why] + [what to do].
Never show raw error codes to users.
Always offer a path forward a retry, a support link, or next step.
## Character limits (mobile)
Screen titles: 24 chars max.
Subtitles / descriptors: 60 chars max.
Button labels: 20 chars max.
Toast notifications: 48 chars max.
Empty state body: 80 chars max.
## Things to never say
"Something went wrong" (too vague)
"Please try again later" (no timeline)
"Invalid input" (doesn't say what's invalid)
"Are you sure?" (not specific enough for destructive actions)
Claude Codeskills/copy.md
2
Generating copy for screens
Copy gets generated alongside layout not filled in afterwards with placeholder text.
→
Add "Read /skills/copy.md before generating any screen" to CLAUDE.md so language rules are always active.
→
Never accept "Lorem ipsum" or "[Button label]" placeholders in generated screens instruct Claude to generate real copy at the same time as the layout.
→
When generating a screen, specify the context: "This is an error state after a failed payment. Generate copy following /skills/copy.md error message rules."
→
For high-stakes copy (errors, destructive actions, legal-adjacent language) generate three options and choose one rather than accepting the first output.
Claude Codecopy.md
3
Copy audit consistency sweep across flows
Run alongside the pattern consistency audit to catch language drift before it compounds.
Read /skills/copy.md. Read all files in /app.
Audit all copy across every screen for:
1. Voice violations anything that sounds formal, cold,
or uses passive voice. Quote the offending string and
suggest a rewrite.
2. Button label inconsistencies same action labeled
differently across screens. List all button labels
grouped by action type.
3. Error messages without a clear path forward flag
any error that doesn't tell the user what to do next.
4. Character limit violations flag any string that
exceeds the limits in copy.md.
5. Placeholder text still in production any string
containing "Lorem", "TBD", "TODO", or "[".
Output: grouped by issue type, with file and line reference,
and a suggested fix for each.
Run the copy audit on the weekly system branch alongside the a11y and consistency audits all three together take less than a few minutes and catch the kind of drift that's invisible screen-by-screen but obvious at a macro level.
Claude Codeweekly branch
4
Copy as a design system export
Generate a content inventory alongside design tokens so engineering and content teams have a versioned reference of all strings.
Read all files in /app.
Generate /tokens/content-inventory.json a structured
export of every user-facing string in the app:
{
"screen": "payment-error",
"element": "error-title",
"string": "Payment didn't go through",
"context": "shown after a failed card charge",
"character-count": 30,
"last-updated": "2024-01-15"
}
Group by screen. Flag any string over the character
limits defined in /skills/copy.md.
→
Version the content inventory alongside design tokens same git tag, same release cadence.
→
Useful for localisation: the inventory becomes the source file for translation rather than manually hunting strings across the codebase.
Claude Codetokens/
Building Step 12
Build app-specific skills
You don't have to write skills from scratch Claude can derive them from the codebase you've already built together. Write them after patterns stabilize, not before.
1
The skill files to build first
→
/skills/flows.md the major user journeys, their screen sequences, and navigation logic between them.
→
/skills/components.md the canonical component library: what each is for, when to use it, when not to, props it accepts.
→
/skills/states.md how the app handles loading, error, empty, and success states. One consistent approach per state type.
→
/skills/copy.md voice and tone rules, button label conventions, error message patterns, microcopy standards.
→
/skills/a11y.md accessibility rules specific to your app: color usage, focus behavior, tap target sizes, screen reader conventions.
2
Ask Claude to generate skill files from what you've built
Read all files in /app and /components/ui.
Generate /skills/components.md a skill file documenting
every component in /components/ui with:
What it's for (one sentence)
When to use it vs. alternatives
Required and optional props
A usage example
Anything that should never be done with it
Write it so a designer new to this codebase could read it
and know exactly what to reach for and when.
Once skills are written, add them to CLAUDE.md so they load automatically. Every future task new screens, new flows, new engineers starts from the same foundation.
Claude Code
Eng collaboration Step 13
Performance budget
AI-generated component code can be bloated unused dependencies, heavy bundles, unoptimized assets. A performance audit runs before every weekly merge so issues are caught before they compound across the codebase.
1
The performance budget skill file
Define your budget once. Claude checks against it on every audit.
# /skills/performance.md
## Budget targets
JS bundle (initial load): < 200kb gzipped
CSS bundle: < 50kb gzipped
Largest Contentful Paint (LCP): < 2.5s on 4G mobile
Cumulative Layout Shift (CLS): < 0.1
Time to Interactive (TTI): < 3.5s on mid-range device
## Images
All images served as WebP or AVIF.
Max image weight: 200kb per asset.
All images must have explicit width and height to prevent CLS.
Use next/image (or equivalent) for automatic optimization.
## Dependencies
No new npm package without justification logged to decision log.
Prefer tree-shakeable libraries.
No package that duplicates functionality already in the stack.
## Audit cadence
Run before every weekly system branch merge.
Any budget breach blocks the merge until resolved or
a conscious exception is logged to the decision log.
Claude Codeskills/performance.md
2
Weekly performance audit prompt
Read /skills/performance.md.
Run a performance audit on the current branch:
1. BUNDLE ANALYSIS
Run: npx next build && npx @next/bundle-analyzer
Flag any route whose JS exceeds 200kb gzipped.
Identify the top 3 contributors to bundle size.
2. UNUSED DEPENDENCIES
Scan package.json against actual imports across /app
and /components. List any package imported nowhere.
3. DUPLICATE FUNCTIONALITY
Flag any two packages that do the same job
(e.g. two date libraries, two animation libraries).
4. IMAGE AUDIT
Find any <img> tags not using the optimized
image component. Find images without explicit
width/height. Find any image over 200kb.
5. CSS AUDIT
Find any inline styles that duplicate values
already defined in tokens.css.
Find any hardcoded color or spacing values
that should reference a CSS variable.
Output: pass ✓ | exceeds budget ✗ | warning ⚠
For each failure, cite the file and suggest the fix.
Claude Codeterminal
3
Catching bloat as it's generated
Prevention is cheaper than a weekly cleanup. Add these constraints to CLAUDE.md so they're active on every generation task.
→
Add to CLAUDE.md: "Never install a new npm package without asking first and explaining why no existing package covers the need."
→
Add to CLAUDE.md: "All animations must use CSS transitions or the existing animation library no new animation packages."
→
After generating any new screen or component, ask: "Does this introduce any dependency or pattern not already in the codebase? If so, flag it before I review."
→
Exceptions are allowed but they get logged to the decision log with a justification. Over time this becomes a record of intentional technical decisions, not just accumulated debt.
Claude CodeCLAUDE.md
Eng collaboration Step 14
Handoff & dev collaboration
Your Claude Code output is the handoff. Engineers get a branch with working code, not a Figma link.
1
Handoff via code, not specs
→
Share the generated code alongside your Figma file. Engineers use it as a reference or starting point not something to rebuild from scratch.
→
Ask Claude Code to annotate before handing off: "Add inline comments explaining design intent, spacing logic, and states not yet implemented."
→
Open a PR, not a Figma share. Use the PR description as the design brief Claude Code can draft it from your branch diff.
→
Agree upfront: designer owns HTML structure and component logic. Engineering owns performance, accessibility, and integration.
Claude CodeterminalGitHub
2
DB & backend integration
→
Describe your data model in plain language. Claude generates the schema, seed data, and basic queries validate with an engineer before running anything.
→
Use mock JSON first: "Generate realistic mock data for this component based on the shape I'd expect from the API." Decouples UI work from backend readiness.
→
Use Supabase with Claude Code for fast real-data prototypes Claude writes the client calls, RLS policies, and schema in one session.
Stop at auth and migrations hand those to engineering. Your boundary is the data shape and the UI that reads it.
Claude CodeSupabase
3
Day-to-day dev collaboration
→
Ask Claude Code to write a short comment block at the top of each new component what it does, what it should never do, known limitations.
→
When you hit something outside your lane (performance, a11y, build errors), paste the error into Claude Code first. It'll either fix it or tell you exactly what to hand to an engineer.
→
Ask Claude Code to generate a test checklist from each component's props and states covers edge cases you'd otherwise miss.
Claude Codeterminal
Eng collaboration Step 15
Designing on real code
Instead of handing off to engineering and waiting, you design directly on top of the production codebase read-only access to the real repo, Claude Code doing the work, engineering reviewing and approving before anything merges. Design intent becomes production-ready code without a translation layer.
1
Read-only access to the engineering repo
You work from the real codebase not a copy, not a design file with guardrails that prevent accidental damage.
→
Get read access to the production repo. You're not pushing to it directly you're reading it so Claude Code understands the real component structure, naming conventions, and patterns engineering is working with.
→
Clone the engineering repo locally in read-only mode and add it to CLAUDE.md: "The engineering codebase is at ../[repo-name]. Read it for reference. Never write to it."
→
Before starting any design session, ask Claude to read the relevant engineering files: "Read ../[repo-name]/src/components/[Feature] and tell me how this component works, what props it accepts, and what constraints I should design within."
→
This eliminates the most common handoff failure: a design that looks right but is incompatible with how the component is actually built. You see the real constraints before you design around them, not after.
# add to CLAUDE.md
Engineering repo: ../[repo-name] (read-only reference)
Before designing any component that engineering already owns,
read the relevant file in ../[repo-name]/src first.
Never create a file in ../[repo-name] directly.
All design work stays in this repo [your-design-repo].
Claude Codegitread-only
2
Designing against real data shapes
Read the actual API responses and data models engineering uses so your designs reflect what the product can actually show.
→
Ask Claude to read the engineering repo's types or API schema: "Read ../[repo-name]/src/types/[feature].ts and generate realistic mock data I can use for this screen." No more inventing data shapes that don't match production.
→
When a screen has edge cases (long strings, empty arrays, null values), ask Claude to identify them: "Read the type definitions and tell me what edge cases this component needs to handle that I haven't designed for yet."
→
Store the real type definitions as a reference in /skills/data-shapes.md so every design session starts from accurate data, not invented placeholders.
# example session opener
Read ../[repo-name]/src/types/transaction.ts
and ../[repo-name]/src/api/transactions.ts.
Before I design the transaction history screen:
1. What fields are available on a transaction object?
2. What are the possible status values?
3. What edge cases should I design for (empty, error,
partial data, very long merchant names)?
4. Are there any fields I might want to show that
don't exist in the current data model?
Claude Coderead-only
3
The design PR how you submit work for engineering review
Your design work becomes a PR against engineering's repo not a Figma link, not a spec doc. A real diff they can read, run, and approve.
→
When a design is ready for production, create a branch in the engineering repo (not your design repo) and apply your changes: "Read my design implementation at /app/[screen].tsx. Translate it to fit the engineering repo's patterns and apply it to ../[repo-name]/src/[path]."
→
Ask Claude to write the PR description: "Write a PR description for this design change. Include: what changed visually, why, what engineering needs to verify, and any implementation decisions they should know about."
→
The PR description format should include three sections: what changed (visual), how it was implemented (technical), and what to watch for (edge cases, a11y, performance). Engineers shouldn't have to guess the intent from the diff.
# design PR description template ask Claude to fill in
## What changed
[Visual description of the change what users see differently]
## Implementation notes
[How it was built component choices, token usage, state logic]
[Any deviations from the existing pattern and why]
## What to verify
- [ ] Visual: [specific thing to check in browser]
- [ ] A11y: [specific thing to check contrast, focus, ARIA]
- [ ] Edge cases: [list from data shape analysis]
- [ ] Mobile: [anything to check specifically on small screens]
## Design decision log
[Link to relevant entries in /decisions/CHANGELOG.md]
Claude CodeGitHubPR
4
Engineering review gates what requires approval before merge
Clear criteria for what engineering must sign off on. Not everything only the changes that carry real production risk.
→
Always requires engineering approval: Any change to a shared component that affects more than one screen. Any new dependency. Any change touching auth, payments, or data handling. Any change that alters an API request or response shape.
→
Requires engineering awareness but not blocking approval: New screen or route that uses only existing components. Copy changes. Token-level visual adjustments (color, spacing within existing scale). New page-level layout using existing components.
→
Designer can merge directly: Changes scoped entirely to the design repo (canvas, prototype, skill files, decision log). Token updates that don't affect shared components. Documentation and CHANGELOG updates.
→
Add this matrix to CODEOWNERS and document it in the team governance section so there's no ambiguity about who approves what.
The gate isn't about distrust it's about surface area. Engineering approving a shared component change is a 5-minute review that prevents a week of regression debugging. Make it frictionless: a Slack message with the PR link, a 24-hour SLA, and a clear checklist they run through.
GitHubCODEOWNERSprocess
5
Using Claude to pre-check before submitting for review
Run a self-review before opening the PR catch the obvious issues so engineering's time is spent on judgment calls, not catching basic mistakes.
Read ../[repo-name]/src/[path-to-affected-files].
Read my changes in /app/[screen].tsx.
Before I open a PR, review my changes as an engineer would:
1. COMPATIBILITY does my implementation use the same
patterns, naming conventions, and abstractions as the
surrounding engineering code? Flag any inconsistency.
2. COMPLETENESS are there states, edge cases, or error
conditions the engineering code handles that my design
doesn't account for?
3. PERFORMANCE any obvious inefficiencies? Unnecessary
re-renders, missing memoization, heavy inline operations?
4. ACCESSIBILITY does this meet the standards in
/skills/a11y.md? Any focus, ARIA, or contrast issues?
5. BREAKING CHANGES does anything I've changed affect
other screens that use the same component or token?
List every file that could be affected.
6. VISUAL VERIFICATION run the app and walk the affected
screens in the browser. Screenshot every state and
compare against the current production version. Flag
any unintended visual change, however small.
Output: ready to submit ✓ | needs revision ✗ | review note ⚠
For each issue, cite the specific line and suggest the fix.
→
Treat a clean self-review as the bar for opening a PR not "it looks right in the browser" but "Claude found no issues against the engineering codebase."
→
Any issues Claude flags go back into iteration before the PR opens. Engineering's review time is for judgment, not debugging.
→
Step 6 is what catches the failure class text-based review can't: AI-generated code that passes lint, types, and review while shipping a spacing bug or a token drift only visible in a rendered browser. It needs browser tooling connected (Claude Code's preview or the Playwright MCP server); at team scale, a visual regression tool in CI (Chromatic, Percy, or a vision-based checker) makes the same gate automatic.
Claude CodeGitHub
6
Keeping in sync as engineering changes the codebase
Engineering ships continuously. Your designs need to stay current with what they're building not drift against a snapshot from last month.
→
Add the engineering repo to your weekly sync routine: "Read the git log in ../[repo-name] from the past week. Flag any changes to components or APIs that affect screens I'm currently designing."
→
When engineering ships a refactor that affects your design work, ask Claude to reconcile: "Engineering changed [component]. Read the new version and update my design implementation to match."
→
Set up a shared Slack channel or GitHub notification between the design and engineering repos so you're notified when files you're designing on top of change, not when you accidentally discover it mid-session.
→
The goal is a continuous feedback loop not a handoff moment. Design feeds engineering a PR. Engineering reviews and merges. Engineering ships changes that design reads and adapts to. The cycle runs weekly, not per-feature.
The weekly git sync routine (Step 17) should include both repos your design repo and the engineering repo. Two
git log reads, one Claude summary, one picture of what changed on both sides.Claude Codegitweekly
Eng collaboration Step 16
Deploy & environments
Designer-owned: local and preview. Engineering-owned: staging and production.
1
The environment ladder
# designer-owned
local → vercel preview (feature branch URL)
# engineering-owned
staging → production
# never push directly to main
git checkout -b feature/name
# build → push → Vercel auto-deploys preview URL
→
Every push to a feature branch auto-deploys a Vercel preview URL that URL is your shareable artifact at every stage.
→
Tag preview deploys with milestone names:
git tag v0.3-user-test always recoverable to exactly what a user saw.→
For sensitive previews: ask Claude Code to add password protection, or use Vercel's built-in password feature for the preview URL.
→
Ask Claude Code to generate a
.env.example documenting which variables point to which environment keeps staging and prod clearly separated.terminalVercelgit
Eng collaboration Step 17
Git sync & design rhythm
A weekly and daily cadence for keeping your design system in sync with the team pulling in changes, reviewing impact, refactoring patterns, and escalating decisions that need a human call.
1
Weekly sync pull, review, merge
Start every week by getting current with the team before building anything new.
# weekly sync routine run every Monday morning
git fetch origin
git checkout main
git pull origin main
# check what changed since your last session
git log --oneline --since="7 days ago"
# then ask Claude Code:
Read the git log from the past week.
Summarize what changed across /components, /styles,
and /app. Flag anything that may affect the design
system or existing screen layouts.
→
Ask Claude to summarize the week's changes in plain language what was added, what was modified, what was removed before you look at any code.
→
Review any conflicts between your current feature branch and main before starting new work. Resolve them early, not mid-task.
→
After pulling, reload the living style guide and canvas view to visually verify nothing drifted unexpectedly.
terminalClaude Codegit
2
Daily branches isolated work, clean history
One branch per day or per task. Never build on main directly.
# start of each day branch from latest main
git checkout main && git pull origin main
git checkout -b design/2024-01-15-[task-name]
# end of day push and open a draft PR
git add -A
git commit -m "design: [what changed]"
git push origin design/2024-01-15-[task-name]
→
Use a consistent branch naming convention:
design/YYYY-MM-DD-task-name. Makes it easy to find, sort, and understand the history at a glance.→
Push at end of day even if work is unfinished draft PRs keep work visible to the team and prevent lost sessions.
→
Ask Claude Code to write the commit message from what changed: "Look at the git diff and write a clear, descriptive commit message for what was done."
terminalgit
3
Weekly design branch new styles, patterns & components
A dedicated weekly branch for system-level work, separate from feature work.
→
Each week, create a branch specifically for design system updates:
design-system/week-of-2024-01-15. Keep feature work and system work on separate branches.→
Bring in any new styles, components, or patterns discovered during the week's feature work onto this branch for consolidation and cleanup before merging to main.
→
This branch is where the consistency audit (Step 9) runs not on feature branches where context is narrower.
# weekly system branch
git checkout main && git pull origin main
git checkout -b design-system/week-of-2024-01-15
# then ask Claude Code:
Read all changes made to /components and /styles
across this week's feature branches. Identify any new
patterns, components, or style values that should be
promoted into the design system. List them with a
recommendation for each: promote, consolidate, or discard.
terminalClaude Codegit
4
Claude reviews incoming changes by scope
Not all changes are equal. Claude classifies them so you know what needs your attention and what can be handled automatically.
Read the diff between design-system/week-of-[date] and main.
Classify every change by scope:
SAFE cosmetic or additive. No existing screens affected.
→ Apply automatically. No review needed.
Examples: new component added, token value tweaked slightly,
new utility class, copy fix.
REVIEW affects existing components or token values.
Existing screens may look different.
→ Apply, then flag for visual review in the browser.
Examples: spacing scale change, border-radius update,
button variant modified, type scale adjusted.
REFACTOR a pattern has changed enough that screens using
the old pattern need to be updated to stay consistent.
→ Apply refactor across all affected files, then flag
a summary of what was changed for designer sign-off.
Examples: card component restructured, form pattern updated,
navigation component rebuilt.
ESCALATE breaking change or significant design decision
that affects major flows or brand-level tokens.
→ Do not apply. Write a clear brief explaining what
changed, what is affected, and what decision is needed.
Flag directly to the designer for a human call.
Examples: primary color value changed, type scale
restructured, component removed, major layout pattern shift.
Claude Code
5
Refactoring screens for updated patterns
When a REFACTOR-level change is identified, Claude updates all affected screens automatically then surfaces a summary for review.
The [ComponentName] pattern has been updated.
The new canonical version is in /components/ui/[ComponentName].tsx.
1. Scan all files in /app for usages of the old pattern.
2. Refactor each to use the updated component.
3. Do not change any logic, copy, or non-visual behavior.
4. After refactoring, output a list of every file changed
with a one-line note on what was updated in each.
5. Flag any file where the refactor was ambiguous or
where the old usage didn't map cleanly to the new pattern.
→
After Claude runs the refactor, do a visual pass in the browser across all affected flows before committing. The change list Claude produces is your review checklist.
→
Any file Claude flagged as ambiguous gets a manual review don't let those slip through automatically.
→
Commit the refactor as its own clean commit, separate from feature work:
refactor: update all screens to [ComponentName] v2.Claude Codeterminal
6
Escalation when Claude flags a decision for you
ESCALATE-level changes are the ones that need a human call. Claude writes the brief; you make the decision.
→
When Claude escalates, it produces a brief: what changed, which screens are affected, what the downstream impact is, and what decision is needed. Read it before touching anything.
→
Options: accept the change and run a full refactor, reject it and revert, or accept it for new screens only while leaving existing screens on the old pattern until a scheduled migration.
→
Document your decision in a short note in the PR description future you (or a teammate) will want to know why the call was made.
→
If the change came from engineering, loop them in before deciding a brand-level token change from the dev side needs a joint conversation, not a unilateral revert.
The escalation brief Claude writes doubles as the changelog entry. Keep them over time they become a record of how the design system evolved and why decisions were made.
Claude CodeGitHub
7
Weekly merge closing out the system branch
End each week by merging the system branch back to main with a clean, documented PR.
# end of week merge system branch to main
git checkout design-system/week-of-[date]
git rebase main # keep history clean
git push origin design-system/week-of-[date]
# open PR, ask Claude Code to write the description:
Read the diff between design-system/week-of-[date] and main.
Write a PR description that summarizes:
New components or patterns added
Components refactored and why
Token changes made
Any open decisions that were escalated
What designers should visually verify after merge
→
The PR description becomes the weekly design system changelog keep them consistent and they're a useful record over time.
→
After merging, regenerate
design-tokens.json and notify engineering that a new token version is available.→
Tag the merge commit:
git tag design-system/v[week] gives engineering a stable reference point for each week's token set.terminalgitClaude CodeGitHub
Appendix
Extended techniques, tooling, and team workflow →
▼
Appendix
Meta improvements Untested
Every time you set something up from scratch skill files, CLAUDE.md rules, token structure you're building what could be a template. Don't wait until you're experienced to start systemizing. Capture these improvements while building your first project or two and every project after starts ahead.
1
A starter template pre-wired for this workflow
One repo that has everything except the brand. Clone it, paste your brand.md, run one prompt, and you're building.
→
Build a GitHub template repo with: Next.js + shadcn + Tailwind scaffolded, blank tokens.css ready for brand input, AGENTS.md pre-written with all framework rules (plus the thin CLAUDE.md shim that imports it), all skill file stubs in /skills, the decisions log structure in /decisions, and the performance and a11y budgets pre-set.
→
Include a
setup.md at the root: "Step 1 fill in /skills/brand.md. Step 2 run this Claude Code prompt." One page, no ambiguity.→
Maintain it as a living repo when the workflow improves, update the template. Every new project automatically starts from the latest version.
→
The template prompt: "Read /skills/brand.md. This is a new project. Run the full design system scaffold from CLAUDE.md setup instructions." one command to go from blank to themed system.
# repo structure of the starter template
/skills/
brand.md # stub fill in for each project
a11y.md # pre-written universal rules
copy.md # stub fill in voice/tone per project
performance.md # pre-written universal budget
decisions.md # pre-written logging format
components.md # auto-generated after scaffold
/decisions/
log.json # empty, ready to receive entries
CHANGELOG.md # empty
/tokens/ # empty, generated by scaffold prompt
AGENTS.md # pre-written with all framework rules
CLAUDE.md # thin shim: @AGENTS.md
setup.md # one-page quickstart
GitHub templateClaude Code
2
shadcn as the permanent base never start from scratch
shadcn is the floor, not a starting point to deviate from. Every project starts with it fully installed, and the skill files assume it's there.
→
Pre-install the full shadcn component set in the template rather than adding components one by one per project. The overhead is minimal and it means Claude Code never has to install a component mid-session.
→
Include a pre-written shadcn skill stub in /skills: which components are available, what each is for, and the rule that no custom component is created if a shadcn equivalent exists.
→
As shadcn releases new components, update the template don't update individual projects manually.
The discipline is: shadcn for structure, brand tokens for appearance. Never fork a shadcn component to change how it looks always theme it through tokens. This keeps upgrades clean.
shadcnClaude Code
3
A standalone canvas & prototype app
Instead of building the canvas and prototype viewer inside every project, extract them as a standalone app that any project can plug into.
→
Build a separate Next.js app
design-viewer that can be pointed at any project's flows.config.ts and renders the canvas and prototype views without any per-project setup.→
The design-viewer reads from a project via a local path or a deployed URL no copy-paste of canvas code into each new project.
→
Include a locale switcher in the toolbar built into the viewer itself so every project gets it for free. Switching locale re-renders all screens with the selected language, making string-length and RTL issues visible during review without any per-project plumbing.
→
Include the decision log panel and version history in the shared viewer same UI across all projects, improvements in one place.
→
Deploy design-viewer to its own Vercel project. Each project's flows become a named workspace in the viewer switch between projects from a sidebar without leaving the tool.
# design-viewer multi-project structure
/workspaces/
[project-a]/
flows.config.ts # symlink or import from project
decisions/ # symlink or pulled via API
[project-b]/
flows.config.ts
decisions/
# single deploy, all projects accessible
design-viewer.vercel.app/[project-a]/canvas
design-viewer.vercel.app/[project-a]/prototype/[flow]
design-viewer.vercel.app/[project-b]/canvas
Password-protect the design-viewer deploy with a single shared credential every project's flows and decision history in one place, accessible to the whole team without separate Vercel logins per project.
Claude CodeVercelcanvas
4
A shared skill library across projects
Universal skills a11y, performance, decisions format live in one place and get pulled into any project. Only brand and copy are project-specific.
→
Maintain a
shared-skills repo with the universal skills: a11y.md, performance.md, decisions.md, shadcn.md. These rarely change and should be identical across projects.→
Pull shared skills into each project as git submodules or symlinks when a universal rule improves, one update propagates everywhere.
→
Project-specific skills (brand.md, copy.md, flows.md, components.md) stay in the project repo they're unique to each product.
→
Reference both from CLAUDE.md: "Universal skills in /skills/shared. Project skills in /skills/project. Project skills override shared skills on any conflict."
git submodulesClaude Code
5
A cross-project pattern library
Patterns that prove themselves on one project get promoted to a shared library so the second project starts with solved problems, not blank components.
→
After each project's pattern consolidation phase, review which components are generic enough to be reusable: empty states, loading skeletons, error boundaries, form patterns, status badges.
→
Promote them to a
shared-components repo stripped of brand tokens, themed purely through CSS variables so any project's token file skins them automatically.→
Ask Claude Code to do the promotion: "Extract EmptyState from this project into a brand-agnostic version that works with any CSS variable token system. Output to /shared-components."
→
The shared component library becomes the real accumulated value of the workflow over time a growing set of battle-tested, accessible, performant components that cost nothing to reuse.
Claude CodeshadcnGitHub
Appendix
When you're ready to grow
The solo workflow is worth proving before you scale it. The right moment to bring in a second designer is when the system is doing the work, when CLAUDE.md and the skill files are stable enough to hand to someone else without explaining everything verbally.
1
Signs the workflow is ready to scale
If you'd struggle to explain the system to a new hire, it's not ready. If the docs do the explaining, it is.
→
CLAUDE.md is stable. You've stopped making significant changes to it every sprint. It reflects how you actually work, not how you planned to work when you wrote it.
→
The skill files cover the system. brand.md, components.md, and any domain-specific skill files describe the product accurately enough that Claude Code produces consistent output without you having to correct it constantly.
→
You have a decision log with real entries. Not a template: actual documented decisions with context. This is the institutional knowledge a new designer needs, and it exists in the repo rather than in your head.
→
You've shipped at least one full flow through the PR process. Engineering has reviewed and merged design PRs. The collaboration pattern exists and is understood on both sides.
If none of this is true yet, don't hire; build. A second designer arriving before the system is stable will either go rogue (building outside the system) or blocked (waiting for you to define it). Either outcome is worse than staying solo longer.
Solo → TeamClaude Code
2
What to look for in a second designer
Technical curiosity matters more than existing Claude Code experience.
→
They don't need to already know this workflow; you'll teach them. But they need to be comfortable with the idea of working in code, reviewing PRs, and treating the design system as infrastructure rather than a style guide.
→
Ask in the interview: "What does your handoff process look like, and what breaks in it?" A designer who has felt the handoff problem is more motivated to solve it than one who hasn't noticed it.
→
Have them read CLAUDE.md and one skill file before or during the interview. Ask what questions it raises. Their questions tell you more about their technical depth than their portfolio.
Solo → Team
Appendix
Team & governance
At 2 designers, governance is a conversation. At 5, it needs structure. These rules define ownership by team size, branch authority, and how conflicting decisions get resolved. Add them gradually as the team grows.
1
Ownership at each team size
The system of record should always have a named owner. Ownership follows expertise.
1–2 designers
You own everything. The second designer contributes to skill files via PR. No formal rotation needed yet.
3 designers
Split ownership by domain: one owns brand + tokens, one owns components, you own CLAUDE.md and governance. PRs on shared files need one reviewer.
4–5 designers
Add CODEOWNERS on /skills/ and CLAUDE.md. Run a monthly consistency audit. Rotate ownership quarterly so knowledge doesn't silo.
Solo → TeamCODEOWNERSgit
2
Keeping the system consistent as the team grows
Consistency drift is invisible until it isn't. Catch it early with a monthly prompt.
→
As each designer builds independently, Claude Code will occasionally generate something that isn't in the design system: a valid but undocumented spacing value, a component variant that doesn't exist, a color that's close but not a token. The PR process catches most of this, but not all.
→
Run a consistency audit monthly: ask Claude Code to scan all screens for token deviations, undocumented patterns, and off-system values. The output is a gap list: some gaps should become system additions, others should be corrected.
→
Treat the gap list as a team agenda item, not a blame exercise. When the same off-system value appears in three different designers' work, the system is missing something, not the designers.
→
Standardize the artifacts, not the tools. One designer on Claude Code and another on Codex or Cursor is healthy; each picks the harness that fits the problem in front of them, and the monthly audit will tell you if that ever stops being true. Consistency problems trace to missing constraints (a token gap, an unwritten skill, a rule that never became a hook), not to tool diversity. Govern the files in the repo and let harness choice stay personal.
# monthly consistency audit
Read all screens in /src/screens.
Compare every color, spacing value, and component against:
- tokens.css
- /skills/components.md
- /skills/brand.md
List values used that aren't in the design system.
Flag any that appear across multiple files as candidates
for formalising into the system rather than correcting.
Solo → TeamClaude Code
3
Roles what each person owns
Clear ownership at each layer prevents silent conflicts and duplicate work.
Design system owner
Typically the lead designer
Owns the weekly system branch. Final say on token changes, canonical components, and any ESCALATE-level decisions. Merges the system branch to main.
Contributing designer
Additional team members
Owns daily feature branches. Can add new components to /components but cannot modify existing canonical components without a PR reviewed by the system owner.
→
One person merges the system branch to main per week not both. Concurrent merges from multiple designers without coordination is the primary source of design system drift in teams.
→
Engineering can never modify files in /components/ui or /styles without a PR reviewed by the design system owner. Add this rule to CLAUDE.md and the repo's CODEOWNERS file.
processGitHub
4
Branch rules for teams
# branch naming convention for teams
design/[designer-initials]/YYYY-MM-DD-[task]
# e.g. design/kl/2024-01-15-checkout-form
design-system/week-of-YYYY-MM-DD
# one per week, owned by system owner only
# CODEOWNERS add to repo root
/components/ui/ @design-system-owner
/styles/ @design-system-owner
/skills/ @design-system-owner
/decisions/ @design-system-owner
terminalgitGitHub
5
Resolving conflicting design decisions
When two designers make different calls on the same pattern, Claude surfaces the conflict the system owner resolves it.
Read /decisions/log.json and the diffs from both
design/[initials-1]/[branch] and design/[initials-2]/[branch].
Identify any components, tokens, or patterns where the
two branches made different choices for the same problem.
For each conflict:
Describe what each approach does differently
Note which is more consistent with existing decisions
Note which better matches /skills/brand.md and /skills/a11y.md
Recommend one approach with a rationale
Do not merge. Output the conflict report only
for the system owner to review and decide.
Claude CodeGitHub
6
Onboarding a new designer
The skills files and decision log contain everything a new person needs. Ask Claude to generate the brief from them.
Read all files in /skills and /decisions/CHANGELOG.md.
Generate a designer onboarding brief covering:
1. What this product is and who it's for (from brand.md)
2. The tech stack and tools (from CLAUDE.md)
3. The 10 most important design system rules
4. How branching and merging works on this project
5. The 5 most significant decisions made so far and why
6. What is currently in progress or under review
7. Where to find things: components, skills, tokens, flows
Keep it under 2 pages. Write for a competent designer
new to this specific project.
Regenerate the onboarding brief monthly the skills and decision log will have evolved. A stale onboarding doc is worse than none.
Claude Code
Appendix
Beyond prototypes Untested
Once your first major flow is built, these three services let you design against something that feels like a real app (persistent data, real emails, live rate limiting) before engineering has built anything. Add them when you need to validate decisions that mock data can't answer. Claude Code scaffolds every integration from a single prompt.
Railway
railway.app
Backend & DB
Persistent backends and managed databases for the parts of your stack Vercel can't host. Postgres, background workers, long-running APIs provisioned in one click, deployed from git.
→
Managed Postgres the most common first addition when your prototype needs to persist real data beyond what can live in localStorage or a flat file
→
Persistent API servers for endpoints that run longer than Vercel's serverless timeout, handle WebSockets, or need stateful connections
→
Background workers job queues, scheduled tasks, webhook processors that don't belong in the request cycle
→
Ask Claude Code to scaffold the connection: "Add Railway Postgres to this project. Set up Prisma, create an initial schema for [your model], generate the migration, and add the DATABASE_URL to .env.example."
Resend
resend.com
Email
Transactional email. Auth flows, notifications, onboarding sequences wired up via React Email templates that use your existing design tokens.
→
Auth emails magic links, password reset, email verification the most common first integration in any new product
→
Transactional notifications order confirmations, activity alerts, digest emails triggered from your app logic
→
React Email templates design emails as React components using your design tokens, previewed in the browser before sending
→
Ask Claude Code to scaffold the integration: "Add Resend for transactional email. Start with a magic link auth flow. Use React Email for templates and match our brand tokens."
Upstash
upstash.com
Redis / Edge
Serverless Redis for edge environments. Rate limiting, session storage, and background queues zero infrastructure, pairs naturally with Vercel deployments.
→
Rate limiting API routes prevent abuse on auth endpoints, AI completions, and any route that costs money per call
→
Session and token storage fast, TTL-aware key-value store for auth sessions, OTP codes, and temporary state
→
Background queues defer slow operations (email sends, webhooks, AI jobs) to a queue rather than blocking the request cycle
→
Ask Claude Code to scaffold the integration: "Add Upstash Redis for rate limiting on /api/auth and /api/ai. Use @upstash/ratelimit with a sliding window strategy."
Appendix
Unexplored design tools Untested
Tools I haven't used extensively enough to be prescriptive about. They're worth knowing exist and experimenting with, but I can't speak to them with the same confidence as the rest of this playbook.
1
AI imagery & video
Several capable tools each with different strengths for product design contexts.
→
Nano Banana Pro / ChatGPT imagery: Good for on-brand marketing and UI illustration. Nano Banana Pro renders accurate in-image text and brand-consistent sets; ChatGPT's image generation can follow brand direction from a text brief and produce consistently styled assets across a set.
→
Grok images & video: Strong for photorealistic and editorial imagery. Video generation is early but advancing quickly worth experimenting with for onboarding motion graphics or explainer content.
→
Midjourney: Still the benchmark for visual quality and stylistic range. Best for moodboarding, establishing visual direction, and generating reference imagery for illustration briefs.
MidjourneyChatGPTGrok
2
AI custom SVGs
Generating on-brand vector assets icons, spot illustrations, UI graphics without a dedicated illustrator.
→
Quiver.ai: Specialized in generating consistent, editable SVG sets from a prompt and style reference. Promising for icon libraries and spot illustration systems that need visual consistency across a large set.
→
Claude Code directly: For simpler geometric SVGs decorative backgrounds, custom dividers, abstract shapes Claude can generate SVG code directly from a description. Output is editable and fast.
→
The challenge: getting the same stroke weight, corner radius, and visual language across 30 icons is harder than a single asset. Tip: generate a reference icon first, then use it as a style seed for the rest of the set.
→
Store generated SVGs in /assets/icons with naming conventions that match your Lucide fallbacks so the system can gracefully use Lucide where custom icons don't exist yet.
Quiver.aiClaude Code
3
Custom illustrations
Building a coherent illustration system using AI as a starting point, not a final output.
→
The strongest approach: use Midjourney or ChatGPT imagery to establish the style (character, line weight, palette, mood), then use that reference to brief a human illustrator or seed consistent AI generation for the full set.
→
Encode the illustration style in /skills/brand.md not just descriptively but with specific reference images linked. Claude Code can use these when generating placeholder SVGs or writing illustrator briefs.
→
Prioritize: empty states, onboarding, and error screens are the highest-value illustration moments. Generate these first and use them to define the style before expanding the set.
→
The unsolved problem: AI illustration sets drift in style at scale. A human illustrator with an AI-generated style guide as a brief still produces more coherent results than pure AI generation across 30+ assets.
MidjourneyChatGPTClaude Code
4
Motion & animation
Lottie + Claude Code as a workflow for bringing motion into the product without a dedicated motion designer.
→
Lottie + Claude Code: Claude can generate Lottie JSON directly for simple animations loading states, success confirmations, empty state illustrations. Drop into any screen that supports Lottie Player.
→
CSS transitions: For micro-interactions (button presses, card hover, drawer entrance) Claude Code handles CSS transition and keyframe animation well. Always paired with
prefers-reduced-motion from the a11y skill.→
Framer Motion / Motion library: For more complex orchestrated animations in React staggered lists, page transitions, drag interactions. Describe the desired feel in plain language and Claude Code implements it.
→
Key question before adding any animation: does this communicate something or just decorate? Loading states, success moments, and state transitions earn motion. Everything else should be challenged.
Add a motion budget to /skills/performance.md max animation duration per screen, max simultaneous animations, and a rule that nothing animates on initial load unless it communicates state. Motion debt accumulates fast.
LottieFramer MotionClaude Code
5
Texture & custom graphics
Surface treatments, backgrounds, and decorative graphics that make a product feel less generic generated and maintained through code.
→
SVG noise & grain: Claude Code can generate SVG filter-based grain textures directly in CSS adds warmth and depth to flat surfaces without image assets. Lightweight and scalable.
→
Generative backgrounds: CSS gradient meshes, geometric patterns, and subtle grid overlays all generated and parameterized by Claude Code, keyed to brand tokens so they adapt automatically when colors change.
→
Hero and marketing graphics: For richer decorative graphics (landing pages, onboarding backgrounds), Midjourney or ChatGPT imagery exports are the fastest path. Export as WebP, optimize, and reference from tokens.
→
Store all texture and graphic assets in /assets/graphics with a naming convention that links back to their screen context. Claude Code can audit this folder for unused assets during the weekly performance sweep.
Code-generated textures (SVG filters, CSS gradients) are preferable to image assets where possible they scale perfectly, adapt to dark mode through CSS variables, add negligible weight, and can be regenerated from a prompt if the brand evolves.
Claude CodeMidjourneyChatGPT
Appendix
Custom slash commands & capability skills Untested
The playbook is full of prompts that work. Two native mechanisms make them permanent: slash commands (you invoke them: one keystroke instead of a 10-line prompt) and capability skills (Claude invokes them: auto-loaded when the task matches). Same markdown, different trigger. Start with commands; promote a command to a skill when you notice you always want it to run without asking.
1
How to create a command
A markdown file in
.claude/commands/. The filename becomes the slash command.→
Create a
.claude/commands/ directory in your project. Each .md file in that directory becomes a slash command new-screen.md becomes /new-screen.→
The file contents are the prompt. Everything in the file is sent to Claude when the command is invoked use the full multi-step prompts from this playbook as your starting point.
→
Commands can include
$ARGUMENTS a placeholder for anything typed after the command. /new-screen onboarding passes "onboarding" as the argument.→
Commit the
.claude/commands/ directory to git commands are project-level, shared with anyone who works on the repo.# .claude/commands/new-screen.md
Create a new screen for: $ARGUMENTS
Before building, read:
- /skills/brand.md
- /skills/components.md
- /src/stories/ if it exists
Build the screen using only components that exist in
the design system. If a new component is needed, flag
it before building don't invent one mid-session.
After building:
- Add an entry to /decisions/log.json
- Update /src/stories/ with any new components
- Run the a11y audit on the new screen
Claude Codecommands
2
Commands to build for this workflow
Start with the prompts you write most often. Every repeated prompt is a command waiting to be written.
→
/new-screen [name] Read skill files, build the screen using existing components, log the decision, update stories.
→
/audit Run the full consistency audit: scan all screens for design system drift, list violations by severity, propose fixes without applying them.
→
/export-tokens Read tokens.css, generate the JSON export for engineering, update the changelog with what changed.
→
/weekly-sync Pull the git log for the past week, summarise what changed, flag anything that affects current design work, generate the weekly changelog entry.
→
/localize [locale] Scan all components for hardcoded strings, extract them to the specified locale file, flag any copy that needs voice/tone review for that market.
→
/new-component [name] Scaffold a new shadcn-based component using brand tokens, write the Storybook story, add it to components.md.
Build your command library incrementally write a command the second time you use a prompt, not the first. If you only needed it once, it's not a command yet. And when a command earns a permanent place in the workflow (the audit that should run on every weekly branch, the decision-logging step that should never be skipped), graduate it to a capability skill at
.claude/skills/[name]/SKILL.md so it fires without you remembering to type it.Claude CodecommandsAgent Skillsgit
Appendix
Multi-agent parallelism Untested
Claude Code can spawn sub-agents that run concurrently. Instead of doing things one at a time in a single session, you coordinate a team each agent handles one job while the others run in parallel. What used to be a prompt trick is now first-party infrastructure: defined subagents, agent teams, and git worktrees for isolation.
1
How sub-agents work
The main session is the coordinator. Sub-agents are specialists that report back.
→
Claude Code can launch sub-agents using the
Agent tool. Each sub-agent gets its own context, runs its own task, and returns a result. The main session synthesises the results and decides what to do next.→
Define reusable specialists in
.claude/agents/: a markdown file per agent (an auditor that reads a11y.md and brand.md, a copy reviewer that reads copy.md) with its own system prompt and tool permissions. Committed to git, shared with the team, invoked by name.→
Sub-agents run in isolation they don't share context with the main session or each other. This means they're safe to run in parallel on independent work without interference.
→
The key constraint: sub-agents can read and write files. Avoid pointing two agents at the same file simultaneously, or give each agent its own git worktree (an isolated checkout of the same repo), which is the standard isolation mechanism for parallel agents that write.
→
Useful distinction: parallelism is for independent work. Don't parallelize tasks that depend on each other's output run those sequentially in the main session.
→
Beyond sub-agents, Claude Code's Agent Teams mode runs a lead agent that plans and delegates to teammates with independent context windows, which share a task list and can message and challenge each other's findings directly. It is still experimental and stays off until you set
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1, so treat it as something to try deliberately rather than a default. You compose a critique from that: one teammate briefed on brand, one on a11y, one on conversion, each reviewing the same flow and pushing back on the others. That is the multi-agent version of the weekly design critique. Each teammate is a separate session, so a team costs several times the tokens of a single one; reserve it for decisions worth that spend.Claude Codeagentsworktrees
2
Design workflow patterns for parallel agents
Tasks that are naturally independent in a design session are natural candidates for parallelism.
→
Build + audit simultaneously: While one agent builds a new flow, a second runs the consistency audit on the screens that already exist. The audit findings are ready when the build is done no waiting.
→
Build + document simultaneously: While one agent builds a component, a second writes the Storybook story and updates
components.md. Documentation is never a backlog item.→
Multi-flow building: Build two independent flows in parallel one agent on onboarding, one on settings. Each works on different files; neither blocks the other.
→
Parallel locale generation: Generate locale files for three markets simultaneously one agent per locale, all reading from the same English source file and the relevant voice/tone brief.
→
Build + performance check: While one agent builds a new screen, a second runs Lighthouse against the existing screens to establish a baseline before the new work lands.
# prompt pattern for parallel work
Run these two tasks in parallel using sub-agents:
Agent 1: Build the settings flow. Read /skills/components.md
first. Build /app/settings/page.tsx and its sub-pages.
Agent 2: Run the consistency audit on all screens in /app
except /app/settings. Read /skills/brand.md first.
Return a list of violations grouped by severity.
Wait for both to complete, then summarise what was built
and what the audit found.
Don't parallelize everything start by identifying the one task in your session that's always waiting on something else to finish. That's where a sub-agent saves the most time.
Claude Codeagentsparallelism
Appendix
Designing agentic products
Everything else in this playbook is about designing with agents. This section is about the other thing the phrase "AI design" gets used for: designing products that contain agents. The two get conflated constantly; they're different competencies, and clients will increasingly ask for the second one. A short field guide so you can tell them apart and know where to start.
1
Generative UI interfaces assembled at runtime
Instead of pre-designing every screen, the product streams UI components into the conversation as the agent works: a chart when data comes back, a form when input is needed.
→
The reference implementation is the Vercel AI SDK's generative UI support, plus its AI Elements library: production components for the recurring furniture of AI products: streaming text, tool-call displays, reasoning traces. AI SDK 7 (2026) widened it from chat primitives into an agent platform, adding Skills, MCP Apps, tool approvals, and durable workflow agents.
→
A standards-track version is emerging: Google's A2UI protocol (2026) has the agent return a declarative tree of components against a catalog the client already trusts, rendered natively across web, mobile, and desktop, instead of generating raw code. Same design task, expressed as a protocol: the product owns the vocabulary, the model composes within it.
→
The design shift: you stop designing screens and start designing a component vocabulary the model composes from. Which is exactly the skill this playbook builds: a tokenized, contract-bound component system is the prerequisite for generative UI that doesn't look chaotic.
→
Every generated component still needs its states designed (loading, error, empty, partial data) because you no longer control when or where it appears.
Vercel AI SDKGenUI
2
Agentic UX patterns the new interaction vocabulary
Products where an agent does multi-step work need interaction patterns that GUIs never needed. These are the ones showing up across the current generation of AI products.
→
Planning visibility: show what the agent intends to do before it does it; the plan is a design surface, and approving it is the new confirmation dialog.
→
Tool-use disclosure: surface what the agent is touching (files, APIs, services) while it works. Trust comes from legibility, not from hiding the machinery.
→
Streaming states: agent work takes seconds to minutes. Design the in-between: progressive results, interruptibility, what "still thinking" looks like at 30 seconds versus 3 minutes.
→
Recovery and override: the agent will be wrong sometimes. Undo, edit-the-plan, and take-over-manually are core flows, not edge cases.
→
Memory surfacing: when the product remembers things about the user, show what it remembers and let them correct it; silent memory reads as surveillance.
The same interaction-pattern rule from the prompting section applies here: these pattern names are a shared vocabulary. "Add planning visibility to this agent flow" is a complete instruction to Claude; the vocabulary works on both sides of the workflow.
agentic UXClaude Code
Appendix
Metrics-driven flow refinement Untested
The AutoResearch pattern propose a change, measure it, keep only improvements applied to product flows. The design system defines what's proposable. The metrics define what's better. Claude runs the loop.
1
The design system as a constrained search space
A design system built on tokens and component contracts isn't just a consistency tool it's a bounded vocabulary of valid experiments. The agent can only propose changes that stay within it.
→
Andrej Karpathy's AutoResearch runs an autonomous loop: modify a file → measure a scalar metric → commit if improved, discard if not. Applied to ML, it ran ~700 experiments over two days, found ~20 genuine improvements, and stacked them into an 11% training speedup on a larger model, all committed publicly, so the numbers are checkable. The same pattern works for product flows if you define the constraint layer correctly.
→
The constraint layer is your design system: tokens.css defines valid values, Storybook stories define valid component configurations, CLAUDE.md defines rules the agent cannot break. An agent proposing variants can only work within this vocabulary it cannot introduce a new color, violate spacing scale, or use a component variant that doesn't exist.
→
This is the key distinction from blunt A/B testing: traditional testing tools generate arbitrary variants that quietly erode the design system. An agent-run loop using your design system as the constraint produces variants that are always on-brand, always accessible, always within the component contracts.
→
The richer and more parameterized your design system, the larger the valid experiment space and the safer each experiment is. Flows built the way this playbook describes (tokens for everything, copy in locale files, components with explicit variant props) are already structured for this. Nothing needs to be retrofitted.
Claude Codedesign systemAutoResearch
2
What the loop looks like in practice
Three ingredients: a parameterized flow, a scalar metric, and a deploy target. Claude proposes variants, Vercel Preview serves them, analytics scores them.
→
The editable asset: a flow's components CTA copy, button weight and placement, step ordering, form field grouping, visual emphasis, empty state messaging. Each is a parameter with a finite set of valid values from the design system.
→
The scalar metric: funnel completion rate, drop-off at a specific step, time-to-complete, error rate. Must be a single number that unambiguously says "better" or "worse." Comes from Amplitude, PostHog, or whatever analytics is instrumented.
→
The cycle: Claude proposes a variant within design system constraints → deploys to a Vercel Preview → analytics measures the metric against the current baseline → if improved, the variant becomes the new baseline and is merged; if not, it's discarded.
→
The program file: following the AutoResearch pattern, you write a
program.md that tells the agent what to optimize and what it cannot touch. "Optimize the onboarding flow for step-3 completion rate. You may vary: CTA copy, button variant (primary/secondary), field ordering in the form. You may not change: the number of steps, brand colors, typography, or component structure."# program.md flow refinement instructions
Goal: increase completion rate on /onboarding/step-3
Metric: step3_completion_rate (from Amplitude, segment: new_users_7d)
Baseline: current production branch
What you may vary:
- CTA button copy (must be <5 words, present tense, action verb)
- CTA button variant: use ButtonPrimary or ButtonLarge from Storybook only
- Form field order (all fields must remain present)
- Helper text below each field (tone: reassuring, max 12 words)
What you may not change:
- Number of steps or step titles
- Any value in tokens.css
- Component structure or layout
- Anything in /skills/brand.md
Cycle: deploy preview → wait 48h for data → read metric → commit if >2% improvement
Claude CodeVercelanalytics
3
Maintaining design fidelity at scale
Fidelity isn't maintained by reviewing every variant it's maintained by the boundaries of what the agent is allowed to propose. The design review happens once, when you write program.md.
→
Write the constraint layer carefully. The time you spend on
program.md is the design review it defines the entire search space the agent will explore. A well-written program file means every variant that emerges is something you'd have approved anyway.→
Reference Storybook stories explicitly in the constraint layer. "CTA must use a variant defined in /src/stories/Button.stories.tsx" means the agent cannot invent a new button style mid-loop. The story is the contract.
→
Log every committed variant to the decision log with its metric delta. Over time, this builds a record of what actually moves user behaviour in your product not opinions, not best practices, but evidence from your specific flow with your specific users.
→
Set a minimum improvement threshold before committing small noise-level changes (0.5%) shouldn't overwrite a design decision. Require a meaningful delta (2–5% depending on traffic) before a variant becomes the new baseline.
The design system's value compounds here. A loose design system means wide, unsafe search space every loop introduces risk. A tight design system means the agent is exploring variations of the same well-considered vocabulary. The investment in tokens and component contracts pays back as safe iteration speed.
Claude Codedesign systemgit
4
What you need before this is viable
The pattern is sound. The infrastructure is non-trivial. Know what you're signing up for before wiring it up.
→
A measurable funnel: analytics instrumented at every step of the flow you want to optimize, with enough daily traffic to reach statistical significance in a reasonable cycle window (48–96h minimum).
→
Vercel Preview Deployments: each variant gets a unique preview URL. The agent deploys, notes the URL, waits for data, reads the metric back. Without preview deploys, the loop has no way to run variants in isolation.
→
An analytics read path for Claude: the agent needs to query the metric programmatically either via an analytics API (Amplitude, PostHog both have them) or a simple script that pulls the relevant number and writes it to a file the agent can read.
→
A tight design system: loose tokens and undocumented components produce unsafe experiments. The constraint layer is only as good as what it references. If Storybook stories don't exist yet, the loop isn't ready.
Start manually before automating the loop. Run one cycle by hand: write program.md, have Claude propose a single variant, deploy it, read the metric after 48h, commit or discard. Once you've done it manually twice, you understand the failure modes then automate it.
Claude CodeVercelanalyticsAutoResearch
5
Write the eval: taste as a testable rubric
Evals are becoming a designer deliverable. The metric loop above tells you which variant performs; an eval rubric tells you whether a variant was acceptable to try at all. Writing it is how your judgment scales beyond the screens you personally review.
→
An eval is a set of testable statements about quality, written per screen type or flow: "the primary action is visually unmistakable at a glance," "error copy names the cause and the next step," "no screen uses more than two type weights," "the empty state offers an action, not an apology." Specific enough that an agent can check them; general enough to survive a redesign.
→
Store the rubric in
/skills/evals.md and make it a standing gate: before any screen is presented to you, an agent scores it against the rubric and cites every failure. You review work that already passed your own written bar.→
Mine the rubric from what you already have: the decision log and your critique history. Anything you have corrected more than twice is a criterion waiting to be written. This is the same heuristic as skills, applied to judgment instead of knowledge.
→
In the automated loop, the rubric bounds the search space the same way tokens do: variants must pass the eval before they are worth deploying. Metrics decide winners; evals decide entrants.
The criteria are the craft. Translating tacit judgment into statements an agent can check is exactly the taste-to-system conversion this whole playbook is built around; the eval file is where it becomes enforceable.
Claude Codeevalsskills/evals.md
Appendix
Data & analytics Untested
Connect your behavioral and revenue analytics to the canvas and prototype views. See real user data in the context of what you designed then ask Claude what to change and why.
1
Analytics in design context
Funnel drop-off looks different when you're looking at it on the actual screen where it happens. Attach metrics to screens, not spreadsheets.
→
The default workflow separates design from data you read a dashboard, then try to map the numbers back to a screen in your head. Because the canvas and prototype views in this workflow are built from real code, you can connect analytics directly to them: drop-off rates, completion rates, and conversion data appear as an overlay on the actual screens they belong to, not static mocks.
→
Add a data panel to the canvas view that fetches metrics per screen from your analytics platform. Each screen tile in the canvas shows its key metric inline step completion rate, time-on-screen, exit rate so design decisions are always made with data visible, not recalled from memory.
→
The same panel on the prototype: when stakeholders review a flow, they see the live conversion numbers alongside the design. A drop-off problem is visible in the room, not buried in a follow-up analytics link.
→
Use behavioral analytics for interaction data (Amplitude, Mixpanel, PostHog) and revenue data for outcome context (Stripe, Paddle). They answer different questions "where do users get stuck" vs. "what converts to paid" and both belong in the canvas.
Claude CodeAmplitudeMixpanelPostHog
2
Wiring behavioral analytics to the canvas
Amplitude, Mixpanel, and PostHog all have APIs. Pull funnel data per screen and surface it where the design decisions happen.
→
Map your analytics event names to your flow screen IDs in a config file
analytics.config.ts. Each screen has a corresponding funnel step name in the analytics platform. This mapping is what lets the canvas fetch the right metric for each screen.→
Build a lightweight API route in the canvas app that proxies requests to your analytics platform. The canvas calls
/api/metrics?screen=onboarding-step-3 and gets back the completion rate, time-on-screen, and exit rate for that screen.→
Display metrics as a small badge on each screen tile in the canvas completion rate in green/amber/red depending on threshold, with a click-through to the full funnel view in your analytics platform for deeper investigation.
→
PostHog is the easiest to self-host and has the most flexible API for this pattern. Amplitude has excellent chart APIs. Mixpanel requires more auth setup but has the richest segmentation useful if you want to filter the canvas view by cohort (new users, returning users, paid vs. free).
# analytics.config.ts map screens to analytics events
export const analyticsMap = {
"onboarding-welcome": { funnel: "onboarding", step: "view_welcome" },
"onboarding-connect": { funnel: "onboarding", step: "view_connect_account" },
"onboarding-configure": { funnel: "onboarding", step: "view_configure" },
"onboarding-complete": { funnel: "onboarding", step: "view_complete" },
"checkout-cart": { funnel: "checkout", step: "view_cart" },
"checkout-payment": { funnel: "checkout", step: "view_payment" },
} satisfies Record<string, { funnel: string; step: string }>
Claude CodePostHogAmplitudecanvas
3
Revenue context from Stripe
Behavioral data tells you where users drop off. Revenue data tells you what that drop-off costs. Both belong in the same view.
→
Pull conversion-to-paid rate per funnel step from Stripe the percentage of users who complete each screen and eventually become paying customers. This reframes every design decision: a 10% drop-off at step 3 hits differently when you know each conversion is worth $200 MRR.
→
Add a revenue layer toggle to the canvas panel: behavioral view shows completion rates and exit rates, revenue view shows conversion-to-paid and ARR attribution per step. Toggle between them depending on whether you're optimizing for engagement or monetization.
→
Use Stripe's Events API to track checkout conversion by flow variant during A/B tests the cleanest signal for whether a design change actually moved revenue, not just clicks.
The most valuable metric to surface in the canvas is the one that connects a design screen to a dollar amount. When a stakeholder asks "why does this screen matter," pointing at a revenue attribution number is faster than any design argument.
Claude CodeStripecanvas
4
Querying Claude with live data
Don't just look at the metrics ask Claude what to do about them. With the screen code and the analytics data in context, the suggestions are specific, not generic.
→
Feed the analytics data directly into the Claude prompt alongside the screen code: "Here is the code for /onboarding/step-3. The completion rate is 42% users are dropping off before submitting the form. Here is the analytics breakdown by device and cohort. What are the 3 most likely causes and what would you change?"
→
Export the current screen's metrics as a JSON snippet from the canvas panel one click, copied to clipboard, ready to paste into the Claude prompt. The less friction between "I see a problem" and "I'm explaining it to Claude," the faster the loop.
→
Go further with session context: pull the top drop-off events from PostHog (the last event before users leave), attach them to the prompt, and ask Claude to diagnose the pattern. "The last event before 60% of exits is scroll_to_field_3. What does that tell us about the form layout?"
→
For revenue queries: "Our checkout conversion dropped 8% this month after we redesigned the payment step. Here is the before/after code diff and the Stripe conversion data by date. What changed that could cause this?" Claude can read the diff and the data simultaneously something no dashboard can do.
# canvas data export paste into Claude prompt
Screen: checkout-payment
Period: last 30 days (2026-03-18 → 2026-04-17)
Completion rate: 61.2% (↓ 8.1% vs prior period)
Exit rate: 38.8%
Median time: 2m 14s (↑ 47s vs prior period)
Top exit event: click_back_button (44% of exits)
Device split: mobile 71% / desktop 29%
Mobile completion: 54.1% | Desktop completion: 76.8%
Stripe conversion (completed → paid):
This period: 28.4%
Prior period: 31.1%
The combination of screen code + analytics data + Claude is the fastest design research loop available. You're not waiting for a user researcher to synthesize findings you're asking a question with real data in hand and getting a specific, actionable answer in seconds.
Claude CodePostHogAmplitudeStripecanvas
Appendix
Gstack live QA in the terminal Untested
A suite of Claude Code skills built by Garry Tan, CEO of Y Combinator: twenty-plus specialist roles (QA lead, design reviewer, security officer) of which the headless browser, /browse, is the one this section covers. Point it at your running app and Claude can navigate, interact, screenshot, and diff without leaving the terminal. github.com/garrytan/gstack
1
What Gstack does
Claude navigates your actual running app clicks buttons, fills forms, checks state, takes screenshots and reports back what it found.
→
Navigate to any page of your local or preview app and take a screenshot without switching windows or opening a browser manually.
→
Interact with elements: click a button, fill in a form, trigger a state change then screenshot the result to verify it looks right.
→
Diff before and after: run a change, then ask Claude to compare the screenshots and describe what visually changed.
→
Useful for closing the loop after a build session rather than manually clicking through every screen, ask Claude to walk the flow and flag anything that looks broken or inconsistent.
Install by cloning the repo into your Claude Code skills directory:
git clone --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup, then invoke skills like /browse directly in Claude Code. Note: gstack's /browse and the Playwright MCP server solve the same problem (agent eyes on the running app); pick one, not both.Claude CodeterminalQA
2
How to use it in a design workflow
Run it at the end of a session, not just when something breaks.
# end-of-session QA prompt
Use gstack to walk the onboarding flow.
Screenshot each screen. Flag anything that:
- looks visually broken
- has text that overflows or wraps badly
- uses a color or font that doesn't match the design system
- has an interactive element that doesn't respond correctly
→
Run this after every major build session as a lightweight design review catches obvious regressions before they make it into a PR.
→
Combine with the consistency audit (Step 9): after the audit generates a list of issues, use gstack to verify each fix landed correctly.
→
Use it to generate screenshots for the decision log a visual record of what the flow looked like at each milestone.
Claude Codegstack
3
Full skills reference
Each skill is a specialist. Invoke with / in Claude Code. Start with /office-hours before writing any code.
| Skill | Your specialist | What they do |
|---|---|---|
| /office-hours Essential | YC Office Hours | Start here. Six forcing questions that reframe your product before you write code. Pushes back on your framing, challenges premises, generates implementation alternatives. |
| /plan-ceo-review Essential | CEO / Founder | Rethink the problem. Find the 10-star product hiding inside the request. Four modes: Expansion, Selective Expansion, Hold Scope, Reduction. |
| /plan-eng-review Essential | Eng Manager | Lock in architecture, data flow, diagrams, edge cases, and tests. Forces hidden assumptions into the open. |
| /plan-design-review Essential | Senior Designer | Rates each design dimension 0–10, explains what a 10 looks like, then edits the plan to get there. AI Slop detection. Interactive. |
| /plan-devex-review | DX Lead | Interactive DX review: explores developer personas, benchmarks against competitors' TTHW, designs your magical moment, traces friction points step by step. |
| /design-consultation | Design Partner | Build a complete design system from scratch. Researches the landscape, proposes creative risks, generates realistic product mockups. |
| /review | Staff Engineer | Find the bugs that pass CI but blow up in production. Auto-fixes the obvious ones. Flags completeness gaps. |
| /investigate | Debugger | Systematic root-cause debugging. Iron Law: no fixes without investigation. Traces data flow, tests hypotheses, stops after 3 failed fixes. |
| /design-review | Designer Who Codes | Same audit as /plan-design-review, then fixes what it finds. Atomic commits, before/after screenshots. |
| /devex-review | DX Tester | Live developer experience audit. Actually tests your onboarding: navigates docs, tries the getting started flow, times TTHW, screenshots errors. |
| /design-shotgun | Design Explorer | Generates 4–6 AI mockup variants, opens a comparison board in your browser, collects your feedback, and iterates. Taste memory learns what you like. |
| /design-html | Design Engineer | Turn a mockup into production HTML that actually works. Pretext computed layout: text reflows, heights adjust, layouts are dynamic. 30KB, zero deps. |
| /qa Essential | QA Lead | Test your app, find bugs, fix them with atomic commits, re-verify. Auto-generates regression tests for every fix. |
| /qa-only | QA Reporter | Same methodology as /qa but report only. Pure bug report without code changes. |
| /pair-agent | Multi-Agent Coordinator | Share your browser with any AI agent. Works with OpenClaw, Hermes, Codex, Cursor, or anything that can curl. Each agent gets its own tab. |
| /cso | Chief Security Officer | OWASP Top 10 + STRIDE threat model. Zero-noise: 17 false positive exclusions, 8/10+ confidence gate, independent finding verification. |
| /ship | Release Engineer | Sync main, run tests, audit coverage, push, open PR. Bootstraps test frameworks if you don't have one. |
| /land-and-deploy | Release Engineer | Merge the PR, wait for CI and deploy, verify production health. One command from "approved" to "verified in production." |
| /canary | SRE | Post-deploy monitoring loop. Watches for console errors, performance regressions, and page failures. |
| /benchmark | Performance Engineer | Baseline page load times, Core Web Vitals, and resource sizes. Compare before/after on every PR. |
| /document-release | Technical Writer | Update all project docs to match what you just shipped. Catches stale READMEs automatically. |
| /retro | Eng Manager | Team-aware weekly retro. Per-person breakdowns, shipping streaks, test health trends. /retro global runs across all your projects and AI tools. |
| /browse | QA Engineer | Real Chromium browser, real clicks, real screenshots. ~100ms per command. /open-gstack-browser launches GStack Browser with sidebar and anti-bot stealth. |
| /setup-browser-cookies | Session Manager | Import cookies from your real browser (Chrome, Arc, Brave, Edge) into the headless session. Test authenticated pages. |
| /autoplan | Review Pipeline | One command, fully reviewed plan. Runs CEO → design → eng review automatically. Surfaces only taste decisions for your approval. |
| /learn | Memory | Manage what gstack learned across sessions. Review, search, prune, and export project-specific patterns, pitfalls, and preferences. Learnings compound over time. |
gstackClaude Code