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.)
1---2name: design-to-code-pipeline3description: 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.4---56# design-to-code-pipeline — the router78Going 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.910Source of truth: `docs/audits/2026-06-06-ui-ux-design-pipeline-playbook.md`.1112**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.1314---1516## The 4 hard rules (read these before anything else)17181. **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.)192. **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.203. **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.214. **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.2223---2425## The pipeline spine (steps 0, 2–5 are identical for every path)2627| Step | What | Skills (invoke via `Skill`) |28|---|---|---|29| **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) |30| **1. Generate** | Pick ONE middle path (1A / 1B / 1C) — see the decision table below. | path-specific |31| **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` |32| **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 |33| **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). |34| **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` |3536---3738## Decision table — situation → path → skills in order3940| You said / situation | Path | Skills in order |41|---|---|---|42| "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` |43| Want a bold single-aesthetic look, no reference | **1A (variant)** | pre-build checklist → `frontend-design:frontend-design` → Step 4 → `release-ship` |44| "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` |45| "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). |46| "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` |47| "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` |48| "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` |49| "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` |50| "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 |51| "Audit the copy/prose on X" | **copy only** | brand-voice/copy rules (non-blog) or `blog-post-template` (blog) |5253**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**.5455---5657## Path details (the parts that aren't obvious)5859**1A — driving Claude Design in the browser (claude.ai/design, Opus 4.7):** the interactive generate step, before the handoff intake below.601. **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.)612. **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.623. **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.634. **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.6465**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).6667**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.6869**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.7071---7273## Max out the paid memberships (aura.build Pro + Figma) — we pay for these; use them fully7475operator directive 2026-07-02: we hold **aura.build Pro** + a **Figma** seat. Most sessions use ~20% of each. Reach for these BEFORE hand-rolling.7677**aura.build Pro — under-used capabilities (verified 2026-07-02 via aura.build/pricing + /changelog):**78- **`@ 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.79- **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.80- **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.81- **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**.82- **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`.83- **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).8485**Figma seat — under-used capabilities (verified 2026-07-02 via developers.figma.com/docs/figma-mcp-server):**86- **`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.87- **`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.88- **`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.89- **`codeSyntax.WEB` on every Figma variable** (on `figma-generate-library`) so design→code emits `--accent`, not the Figma variable name.90- `figma:figma-use` is **MANDATORY before any `use_figma`** call.9192**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`).9394## Browser-access note (when claude-in-chrome isn't mounted)9596Step 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.9798---99100## Backup / fallback matrix — when a tool or site is down (operator ask 2026-07-02)101102**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.103104| If this fails | Symptom | Fall back to |105|---|---|---|106| **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). |107| **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`. |108| **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). |109| **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. |110| **`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**. |111| **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. |112| **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. |113114**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).115116---117118## Common mistakes119120| Mistake | Fix |121|---|---|122| Generating before pinning tokens (Step 0) | Claude Design / Aura infer a parallel design system; the import keeps both. Always pin the token set first. |123| Hand-writing a hex / font / gradient | Use `var(--*)` + the effect skills. Raw hex breaks light mode. |124| Shipping UI without render+score | Step 4 is non-negotiable. `tsc` clean ≠ looks designed. |125| Dumping the Claude Design bundle into `<web-app>/src/` | Quarantine + diff + prefer our tokens (1A intake). |126| Trying to make CLI Code Connect work on this seat | It's Org/Enterprise-only. Use the Pro fallback. |127| Running two Figma-reading MCP servers at once | Confuses the agent. Use html.to.design as the bridge, then one Figma MCP. |128| Calling `use_figma` without `figma:figma-use` first | Mandatory — it carries the Plugin-API gotchas. |129| Picking the aesthetic unilaterally | Design taste is the operator's call — surface options + a recommendation. |130131---132133## Known gaps (playbook §4 — not yet closed)134135- No `/design-intake` slash command for the 1A handoff bundle (manual quarantine for now).136- No generated Figma design-system-rules file (`figma-create-design-system-rules`); we rely on CLAUDE.md prose + the pre-build checklist.137- 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.)
oimiragieo