| name | design-to-code-pipeline |
| description | Use when going from "I want a beautiful page/section/component" to shipped React in <web-app>/src/ — picking a design engine (claude.ai/design vs aura.build vs Figma), wiring the generate → assets → build → audit → ship pipeline, or deciding which generate-path fits ("build a new page", "make our nav look like X", "clone this site", "get my Claude Design mockup into Figma", "this UI looks like AI slop"). Router/meta-skill that bundles the existing UI/UX skills; it selects + sequences them, it does not redefine them. |
design-to-code-pipeline — the router
Going from a design idea to shipped React on your product is a multi-skill recipe. This is the router: it names the default path, the branch points, the handoff mechanics, and the hard rules. It bundles existing skills (same meta-skill pattern as arch-driven-release-workflow) — invoke each via the Skill tool when its step fires. It never duplicates their content.
Source of truth: docs/audits/2026-06-06-ui-ux-design-pipeline-playbook.md.
One-paragraph default: claude.ai/design → handoff bundle → Claude Code → audit, because producer and consumer are the same model family and the handoff integrates into our repo. Use aura.build when you want Aura's visual ceiling (bento / glass / WebGL) or its native URL/screenshot clone. Use Figma only when a human designer must touch layers, or downstream for review. In every path: declare the tokens.css tokens first, build into <web-app>/src/, then run the audit cluster — and never hand-roll a token a tool already owns.
The 4 hard rules (read these before anything else)
- Never hand-roll tokens.css. Reference
var(--*) tokens from <web-app>/src/styles/tokens.css — never raw hex. Raw hex breaks light mode (the var(--*) indirection cascades to the light :root block for free; inline hex = the #030304-contrast regression class). A new color is a new semantic token name in tokens.css, never an inline literal. Use the effect skills (web-css-border-gradient / web-progressive-blur / web-css-alpha-masking / the WebGL set), not bespoke CSS. Reuse src/components/ui/* instead of regenerating a card/button every screen. (Full table: playbook §3.)
- ALWAYS render + score before shipping any UI. No UI change ships without going through Step 4 (render via Chrome MCP →
frontend-audit peer-rated to a 9+/10 → a page-auditor pass cycled to convergence, zero new findings). "It compiles" and "tsc is clean" are not "it looks designed." This is the never-change-ui-without-render-and-score discipline.
- The generator does the boilerplate; you do the taste pass + tokens.css mapping + the audit. Don't hand-translate a Figma frame, hand-clone a layout, or hand-build a token library when a skill does the mechanical first draft.
- Design taste is the operator's call. When a choice is aesthetic (direction, which reference, button feel, "premium" vs minimal), surface options + your recommendation; don't unilaterally pick the look. Tooling/mechanics are yours; taste is escalated.
The pipeline spine (steps 0, 2–5 are identical for every path)
| Step | What | Skills (invoke via Skill) |
|---|
| 0. Declare the design system FIRST (non-negotiable) | Pin our tokens.css tokens authoritatively so neither Claude Design nor Aura introduces parallel tokens. Confirm audience+outcome and the token set before generating anything. | a pre-build checklist (audience+outcome, tokens) |
| 1. Generate | Pick ONE middle path (1A / 1B / 1C) — see the decision table below. | path-specific |
| 2. Assets / imagery (if media needed) | aura assets first; programmatic motion/effects via recipe skills (don't hand-roll). next/image 400s any host not in images.remotePatterns — allowlist in the SAME commit as <Image src>. | web-aura-asset-images → web-unsplash-asset-images (fallback); web-animation-systems + web-gsap/web-animation-on-scroll; web-css-border-gradient/web-progressive-blur/web-css-alpha-masking; web-threejs/web-vantajs/web-cobejs/web-globe-gl/web-matterjs |
3. Build in <web-app>/src/ | Confirm location/naming + the state matrix before JSX. Tailwind + tokens.css var(--*). Copy on EVERY visible string. Next.js 16: await props.params + setRequestLocale; cd <web-app> && npm run check-types before commit; React #418 → STOP after 2 attempts. | web-tailwindcss, brand-voice/copy rules (non-blog copy) / blog-post-template (blog), web-landing-page / web-pricing-page where they fit |
| 4. Render + audit + score (loop to convergence) | Capture via Chrome MCP, then audit cluster. Iterate the UI-quality rating pass until 9+/10; iterate the page-auditor pass until 3 cycles with zero NEW findings (any NEW resets to 0/3). | capture: use-claude-in-chrome (authed/session) or use-chrome-devtools-mcp (DOM-first + Lighthouse). Audit: frontend-audit → a UI-quality rater → a page auditor. High-stakes second opinion: use-gemini (--approval-mode plan) or a codex CLI pass on the screenshots (3/3 ship · 2/3 investigate · 1/3 verify). |
| 5. Ship | Version bump, CHANGELOG, Vercel deploy, post-deploy verify. Web-only changes still need the deploy path; vercel --prod --yes --force to bake env/CDN. | release-ship / /release-ship |
Decision table — situation → path → skills in order
| You said / situation | Path | Skills in order |
|---|
| "Build a new page/section from scratch" (no reference, no designer) — DEFAULT | 1A | pre-build checklist → mengto-ui-prompting → claude-design → (handoff intake) → web-tailwindcss + brand-voice/copy rules → Step 4 audit → release-ship |
| Want a bold single-aesthetic look, no reference | 1A (variant) | pre-build checklist → frontend-design:frontend-design → Step 4 → release-ship |
| "Build it, and a designer must refine layers" / "stand up our Figma design system" | 1B | figma:figma-create-new-file (if new) → figma:figma-use (MANDATORY before any use_figma) → figma:figma-generate-design (or figma:figma-generate-library for a DS) → figma:figma-code-connect (Pro fallback, see caveat) → translate to tokens.css → Step 4 → release-ship |
| "I have a Claude Design mockup, get it into Figma" | 1A→1B bridge | Claude Design has NO native Figma export. Bridge it: export standalone HTML → html.to.design (Chrome-extension "Copy to Clipboard" → paste into Figma, OR the html.to.design Figma plugin drop-zone), OR the Anima Figma design-agent. Then resume 1B at the implement flow. Never run two Figma-reading MCP servers at once. Ask first whether Figma is even needed — if the target is our repo, skip it (1A → Claude Code is direct). |
| "Generate in Claude Design, ship to our site" — browser-driven | 1A (browser) | /design-sync (connect our DS) → use-claude-in-chrome drive of claude.ai/design (prompt + file_upload screenshots) → Handoff to Claude Code OR Send to Vercel (mcp__plugin_vercel_vercel__import-claude-design-from-url) → handoff intake → Step 4 → release-ship |
| "Make our nav/hero look like [site X]" / "clone that component" | 1C (single) | use-claude-in-chrome or use-chrome-devtools-mcp (capture) → aura-screenshot-clone → re-house into <web-app>/src/ with tokens.css → Step 4 → release-ship |
| "Pixel-perfect clone of this whole site" | 1C (whole site) | use-chrome-devtools-mcp → clone-website (parallel builders in worktrees; each passes tsc --noEmit + npm run build) → Step 4 → release-ship |
| "I want Aura's bento/glass/WebGL aesthetic specifically" | 1C/1A | aura.build (native React mode) → re-house with tokens.css → Step 4 → release-ship |
| "Polish/audit an EXISTING live page" / "this UI feels off / looks like AI slop" | Step 4 only | frontend-audit → a UI-quality rater (score) → a page auditor (critique) → fix loop |
| "Audit the copy/prose on X" | copy only | brand-voice/copy rules (non-blog) or blog-post-template (blog) |
Shortcuts: target is our monorepo + tightest loop → 1A. Need editable artifacts a human touches, or a reusable Figma DS → 1B. Copying an existing look → 1C (single = aura-screenshot-clone; whole site = clone-website). Page already exists → skip generation, go to Step 4.
Path details (the parts that aren't obvious)
1A — driving Claude Design in the browser (claude.ai/design, Opus 4.7): the interactive generate step, before the handoff intake below.
- Connect our real design system FIRST — the load-bearing step. From a Claude Code session run
/design-sync (shipped 2026-06-17): it pushes our design system (a linked GitHub repo / design files / the local <web-app>/ codebase) into Claude Design so generation starts from our real src/components/ui/* + tokens.css tokens, not a generic look. Skip this and the output is off-brand and the intake below fights a parallel token set. (Alternatively upload the codebase subset via the org design-system panel — lower-left org name → Publish.)
- Open + prompt via
use-claude-in-chrome (needs the operator's Claude login; NOT chrome-devtools-mcp, which has no session): navigate to https://claude.ai/design → pick Prototype/Wireframe → type the intent in the chat pane → attach reference screenshots with file_upload (Claude Design accepts screenshots, competitor shots, wireframes, DOCX/XLSX as context). Capture each state with take_screenshot for the observe-first record.
- Iterate via the CHAT pane, not by automating drag/resize. Broad changes ("darker, more minimal", "move pricing above the fold") go in chat; canvas drag/resize/inline-comment manipulation is unreliable under browser automation — steer with text prompts and re-screenshot. Start in wireframe mode — a polished session can burn >50% of a weekly Pro allotment; polish only after structure settles.
- Get it OUT. The export menu (upper-right) offers: Handoff to Claude Code (local or Web — the direct-to-repo path, preferred), Send to Vercel (then pull via the
mcp__plugin_vercel_vercel__import-claude-design-from-url MCP tool we already have), .zip / PDF / PPTX / Canva / standalone HTML, or a share URL. There is NO native Figma export (confirmed 2026-07-02 across Anthropic's docs + 3 sources) — for Figma see the 1A→1B bridge row.
1A — handoff intake (the step people skip): Export → "Handoff to Claude Code." The bundle is manifest.json (tokens/fonts) + components/*.tsx + pages/ + assets, hosted at api.anthropic.com/v1/design/h/…, fetched via WebFetch. Quarantine it into a preview/ (or design-intake/) dir; prefer existing tokens.css tokens on conflict; rewrite imports to the @/ alias; print a diff. Do NOT let it dump straight into <web-app>/src/ (it ships dead --primary tokens next to our real --accent). /design-sync at step 1 makes this intake far cleaner (fewer token conflicts to reconcile).
1B — Figma Pro-seat caveat (load-bearing): This workstation is Pro / Full seat (not Org/Enterprise), so CLI Code Connect does NOT work — no <CodeConnectSnippet> real-import injection. Don't burn time trying to make it work. The documented Pro substitute: get_variable_defs (our tokens) + search_design_system (component reuse) + a strong CLAUDE.md token-rules file. figma:figma-use is MANDATORY before any use_figma call (it carries the Plugin-API gotchas). On figma-generate-library, set codeSyntax.WEB on every variable so design→code emits --accent, not the Figma name.
1C — Aura clone is now NATIVE: paste a URL or drag a screenshot into aura.build and it generates React/Tailwind directly (no Chrome extension required for the core flow). The Anima/Chrome-extension path is a fallback for login-gated pages Aura can't fetch server-side. See aura-screenshot-clone for the brand-token table + known-blocked-sites list.
Max out the paid memberships (aura.build Pro + Figma) — we pay for these; use them fully
operator directive 2026-07-02: we hold aura.build Pro + a Figma seat. Most sessions use ~20% of each. Reach for these BEFORE hand-rolling.
aura.build Pro — under-used capabilities (verified 2026-07-02 via aura.build/pricing + /changelog):
@ References (Full) + Prompt Builder (Full) — inside an aura prompt you can @-reference existing templates, components, assets, chats, AND code snippets. Feed aura our tokens.css token values + an existing src/components/ui/* snippet so its output already aligns to our system → far less re-housing. This is the single biggest lever we skip.- 1,700+ templates + 1,400+ Pro components — for a STANDARD section (pricing table, feature grid, testimonial, FAQ, bento), start from a Pro component/template, not a from-scratch prompt or a clone. Faster + higher visual ceiling.
- Native image tools: Remove BG · Upscale · Remix · Download in 4K — route asset editing through aura (Pro) instead of defaulting to
use-nano-banana / web-unsplash-asset-images. Pair with web-aura-asset-images for picking.
- Native Figma import + export (organized layers) — aura ↔ Figma is BUILT-IN. Prefer aura's own "Export to Figma" over the
html.to.design bridge when the source is an aura design (the bridge is only for a Claude-Design HTML export). aura also imports FROM Figma.
- Page transitions (fade / slide / scale / blur / push / wipe) + multi-page + CMS — for an animated multi-section page or a small microsite, let aura generate the transitions rather than hand-rolling
web-gsap.
- Real code out (HTML + Tailwind + vanilla JS, no lock-in) — always re-house into
<web-app>/src/ with tokens.css var(--*) tokens (never ship aura's raw hex/utility values).
Figma seat — under-used capabilities (verified 2026-07-02 via developers.figma.com/docs/figma-mcp-server):
figma-create-design-system-rules — generate a CLAUDE.md/AGENTS.md rules file that maps our tokens.css tokens → Figma variables so the Figma MCP binds to OUR tokens instead of re-deriving them. We don't have this yet (design-to-code-pipeline known-gaps) — highest-value Figma close.get_variable_defs (our tokens) + search_design_system (component/variable reuse across linked libraries; includeVariables:true) — the Pro-seat substitute for CLI Code Connect (which is Org/Enterprise-only on our seat). Run multiple short search_design_system queries in parallel by variable name.get_design_context returns React+Tailwind by default — treat as a REPRESENTATION, replace Tailwind utilities with our tokens.css tokens, reuse existing components. Always get_design_context + get_screenshot first — never implement from assumption.codeSyntax.WEB on every Figma variable (on figma-generate-library) so design→code emits --accent, not the Figma variable name.figma:figma-use is MANDATORY before any use_figma call.
Rule of thumb: standard section → aura Pro component/template. Bespoke aesthetic → aura prompt with @-referenced tokens. Designer-touchable artifact or reusable DS → Figma (with figma-create-design-system-rules + get_variable_defs). Asset editing → aura image tools. Always re-house to <web-app>/src/ on tokens.css tokens + render-verify (ui-fix-observe-first).
Browser-access note (when claude-in-chrome isn't mounted)
Step 4 needs a real render to capture. If use-claude-in-chrome isn't mounted this session, route the render/score through use-chrome-devtools-mcp (DOM-first, account-agnostic, also gives Lighthouse). If neither Chrome MCP is available, the documented fallback is browser-via-gemini: dispatch use-gemini with chrome-devtools access to capture + critique the rendered page (cross-ref the browser-via-gemini memory technique). Never claim a UI "rendered fine" without an on-disk screenshot — the UI-quality rating pass caps the score at 7 without evidence.
Backup / fallback matrix — when a tool or site is down (operator ask 2026-07-02)
Governing principle: every external design SITE is an ACCELERATOR, not a dependency. The always-available floor is Claude Code building directly — the frontend-design:frontend-design skill (or a hand-build) from tokens.css tokens + reference screenshots-as-context + the ui-fix-observe-first render loop. If everything external is down we are never blocked — we lose the speed-up, not the capability. Ship discipline (Step 0 tokens, Step 4 render+score, release-ship) is identical on every fallback path.
| If this fails | Symptom | Fall back to |
|---|
| Claude Design (claude.ai/design down · weekly Pro allowance exhausted · canvas won't load · handoff bundle 404s) | blank canvas, "usage limit", export hangs | aura.build (native prompt / URL-screenshot clone) for the generate step → same intake. If aura is also down → frontend-design:frontend-design builds directly in Claude Code from tokens.css + screenshots (no external site). |
| aura.build (down · rate-limited · can't fetch a login-gated source URL) | clone step errors / returns nothing | Claude Design (1A) for generate; for a login-gated CLONE specifically → capture via use-claude-in-chrome then aura-screenshot-clone from the local screenshot, OR the Anima/html.to.design path. Assets → use-nano-banana / web-unsplash-asset-images. |
| Figma (figma.com down · Figma MCP won't connect · Pro-seat Code Connect unavailable) | MCP timeout / no use_figma | Skip Figma — it is only needed when a human designer must touch layers. Go Claude Design → Handoff to Claude Code directly. If the artifact MUST reach Figma and Figma-web is up but MCP is down → the html.to.design browser bridge (no MCP needed). |
| html.to.design (Figma bridge down) | paste/plugin fails | Anima Figma design-agent (drop the exported HTML), OR rebuild the section in Figma from the Claude Design screenshot by hand, OR skip Figma and go straight to code. |
use-claude-in-chrome (not mounted · unresponsive · lost session) | tools deferred / dialog-blocked / stale tab | use-chrome-devtools-mcp (DOM + Lighthouse, no login — good for PUBLIC pages + the audit). For an AUTHED Claude Design session it can't log in → have the operator drive claude.ai/design manually + export the bundle, then resume at the handoff intake. Last resort: browser-via-gemini. |
Vercel import-claude-design-from-url (MCP down) | import tool errors | Use Claude Design's Handoff to Claude Code export instead (same bundle, WebFetch it), or download .zip and quarantine locally. |
| ALL external design sites down | nothing external reachable | frontend-design:frontend-design (or hand-build) in Claude Code: tokens.css tokens + reference screenshots as context + web-tailwindcss + the Step-4 observe-first render loop. This is the floor and it always works. |
Rule: on any fallback, log() which primary tool failed + which fallback you took (no silent substitution — the operator should see "Claude Design was rate-limited → built via frontend-design skill", not a mystery path).
Common mistakes
| Mistake | Fix |
|---|
| Generating before pinning tokens (Step 0) | Claude Design / Aura infer a parallel design system; the import keeps both. Always pin the token set first. |
| Hand-writing a hex / font / gradient | Use var(--*) + the effect skills. Raw hex breaks light mode. |
| Shipping UI without render+score | Step 4 is non-negotiable. tsc clean ≠ looks designed. |
Dumping the Claude Design bundle into <web-app>/src/ | Quarantine + diff + prefer our tokens (1A intake). |
| Trying to make CLI Code Connect work on this seat | It's Org/Enterprise-only. Use the Pro fallback. |
| Running two Figma-reading MCP servers at once | Confuses the agent. Use html.to.design as the bridge, then one Figma MCP. |
Calling use_figma without figma:figma-use first | Mandatory — it carries the Plugin-API gotchas. |
| Picking the aesthetic unilaterally | Design taste is the operator's call — surface options + a recommendation. |
Known gaps (playbook §4 — not yet closed)
- No
/design-intake slash command for the 1A handoff bundle (manual quarantine for now).
- No generated Figma design-system-rules file (
figma-create-design-system-rules); we rely on CLAUDE.md prose + the pre-build checklist.
- No automated pixel-delta-vs-mockup QA gate (design→code is ~85–90% accurate; the UI-quality rating pass checks states qualitatively but there's no CDP pixel-measurement loop yet). (verify — candidate future skill.)
