design-to-production

name	design-to-production
description	Convert Claude Design HTML (*.v2.image-first.dc.html) into production Next.js React screens with verified visual parity. Use whenever the user says "design to production", "DC parity", "convert HTML to React", "match the design file", "image-first parity", references Universal design prompt/*.dc.html (including Shoots List), or asks to port Command Center / Brand List / Brand Detail / Shoots List into app/. Load before line 1 on any DESIGN-* UI task. HTML design wins for layout; React wins for data/auth/shell. Enforces RSC + CSS modules + tokens + state parity + side-by-side verification. Does NOT replace claude-design-handoff for full program planning — use this skill for execute-and-verify on a single screen or small route bundle.
version	2.0.0

design-to-production — HTML design → React parity

Workflow: Phase 0 gates → read DC HTML → audit React → minimal files → side-by-side verify → report

Design SSOT: Universal design prompt/*.v2.image-first.dc.html — layout, spacing, cards, image ratios, states, responsive behavior.

Production: app/ (Next.js 16) · /app/* · legacy Vite src/ retired.

---

Load before line 1 (mandatory stack)

Order	Skill / doc	Purpose
1	design-md	Tokens, 3-panel contract, HITL
2	This skill	DC → React execution
3	dc-html-anatomy.md	Parse Workspace zones + states
4	react-next-parity-rules.md	RSC, CSS modules, no hex
5	screen-checklists.md	Per-screen dimensions
6	vercel-react-best-practices	Search/filter performance
7	task-verifier	Phase 2 readiness + Done gate

Shoot domain: also shoot/lessons-from-brand-parity.md.

---

Non-negotiable rules

Layer	Wins for
HTML .dc.html	Visual layout, spacing, card structure, image-first ratios, chip rows, workspace width, empty/loading/error presentation
React app/	Live data, routing, auth, Supabase, CopilotKit, Mastra, APIs, business logic

Do not:

• Rebuild OperatorPanel, NavSidebar, IntelligencePanel, PersistentChatDock
• Use min-h-screen, #FBF8F5, #E87C4D, or other legacy Vite hex in workspace
• Whole-page 'use client' + useEffect fetch when RSC + loading.tsx suffices
• Invent fake DNA scores, history, or counts when API null
• Copy DC Inter font or :root wholesale — map to tokens.css
• Mix parity with migrations/infra in one PR

Do:

• Parity = main[data-screen-label="Workspace"] column only
• RSC page + client workspace + loading.tsx skeleton matching DC
• CSS modules + app/src/styles/tokens.css
• Production state table + data-source table in issue md before code
• Side-by-side screenshots DC :8765 vs React :3002
• Branch ipi/<issue>-<slug> via worktree

---

Regression guardrails (IPI-383/372 lessons — do not repeat)

Folded from tasks/design-docs/audit/checklist.md. These are the exact mistakes that cost review cycles — each is now a hard step, not advice.

#	Trap	Guardrail
1	Edit/Write before reading the file's exact path	Read (after graphify query) every file before editing. Never assume a path.
2	Ran tsc/tests before deps installed in a fresh worktree	First worktree command is npm ci. Baseline-green before writing code.
3	Stale worktree — local branch behind remote; a commit would revert shipped work	Before editing: git fetch && git status vs origin/<branch> + gh pr list --head <branch>. Reset/rebase to remote first.
4	Crammed all detail into aria-label, overriding visible text	Concise aria-label (accessible name) + aria-describedby → className="sr-only" summary. Never one giant label.
5	Brittle exact-string name assertions broke on copy tweaks	Assert accessible names by prefix regex (/^Select …/), not ===.
6	<Link> to current route as "retry" — silent no-op	Retry re-runs the server fetch: "use client" + useRouter().refresh(). Mock next/navigation in tests.
7	Test mocked only own CSS module, not shared base module	Mock every *.module.css the tree imports with the Proxy stub.
8	Panel/dock preview test asserted on a published node never rendered	Render provider + a DetailSink that renders detail (copy shoots-list-workspace.test.tsx).
9	Read exit code 0 from a piped test run that had failed	Read actual test output, not just tail/exit-code notification.
10	Over-scoped to the whole DC file (extra steps/flows)	Honor the decision of record (e.g. IPI-252: 6 steps ship, not 10). Build only in-scope nodes; mark the rest ➖ deferred with its issue.
11	Trusted local as ground truth without checking the live ledger

Full write-ups, dates, and PR links: Universal-design-prompt-4/lessons.md.

---

Phase 0 — gates (before Discover)

Run from improve.md + brand parity lessons:

[ ] Audit Supabase FIRST — live schema, RLS, and migration ledger before reading anything else
[ ] Read target *.dc.html + screen checklist row
[ ] Production state table — shell/route/API exists on disk?
[ ] Data-source table — Supabase MCP probe for list/tab columns
[ ] Negative AC — no fake fallbacks documented
[ ] @task-verifier readiness — fix 🔴 spec gaps before coding

Audit Supabase first — before trusting any local file. Local schema/migration files and written specs can both diverge from what's actually live. Before building against any table/column/RPC this screen needs, run against the live project via Supabase MCP (read-only):

1. list_tables / a targeted select — does the column the DC mockup implies actually exist, and is it non-null on real rows (not just in dev fixtures)? A field that's always null in seed data hides whether the feature works at all (lessons #7, #8).
2. For any RPC the screen calls, execute_sql: select pg_get_functiondef('public.<fn>(<args>)'::regprocedure) — confirm the live function body, not just the migration file's version. create or replace migrations can be reapplied incrementally on the live project (via apply_migration during iteration) in a way local files don't always track 1:1 (lesson #9).
3. list_migrations — confirm the live ledger's version/name list matches what's in supabase/migrations/ locally. A squashed or renumbered local file that doesn't match a live-applied version is invisible to CI and will desync on the next db push (lesson #9).

Only after this — not before — read the .dc.html and start the Discover phase below.

Shoots List example: Shoots List.v2.image-first.dc.html requires 920px workspace, 3-col grid, 5 distinct states — current /app/shoots/page.tsx fails layout + tokens + architecture.

---

Route mapping

Full map: references/route-map.md

Priority	HTML	Route	Linear
P0	Command Center · Brand List · Brand Detail	/app · /app/brand · /app/brand/[id]	IPI-271/272
P1	Shoots List.v2.image-first.dc.html	/app/shoots	IPI-273
P1+	Shoot Detail · Wizard · Assets · …	/app/shoots/[id] · /app/shoots/new · …	IPI-274+

Conversion plans (shoot family):

• Shoots List → tasks/design-docs/shoot/PLAN/shoots-list-dc-conversion.md — 14 parity dimensions; Phase 7 must be >0% before Done.
• Shoot Wizard → tasks/design-docs/shoot/PLAN/shoot-wizard-dc-conversion.md — scope-locked to 6 steps (IPI-274); DC's extra 4 steps + booking flow are deferred (IPI-252 / IPI-340-342). Folds the IPI-383 regression guardrails into §0.1.

---

Workflow (run in order)

1. Discover

1. Read target *.v2.image-first.dc.html — grep data-screen-label, max-width, grid-template-columns, sc-if state flags (dc-html-anatomy.md).
2. Open dc-import components under Universal design prompt/components/.
3. Grep production route + app/src/components/<feature>/.
4. Fill production state table — what exists vs what this PR changes.
5. Read screen row in screen-checklists.md.

Output: HTML zones table + file touch list (3–8 paths).

2. Audit

Side-by-side: DC server optional :8765 vs :3002.

Area	DC	React	Action
Workspace width	e.g. 920px		fix module
Grid cols / gap	e.g. 3 × 20px
States	loading/empty/error/no-match/grid		each distinct
Tokens	#111 action	legacy orange?	🟢/🔴
Architecture	N/A	RSC vs client page
Mobile @1024	tab bar / sheet	shell OK?

Score: 🟢 match · 🟡 partial · 🔴 missing · ➖ defer.

3. Plan

• Reuse: ShootCard, BrandCard, panel hooks
• Create: *-workspace.tsx + *.module.css only
• Defer: DC STATE switcher, bulk select demos
• Out of scope: explicit list in PR

Link Linear · one concern per PR · ≤500 LOC target.

4. Implement

Follow react-next-parity-rules.md:

1. Worktree branch
2. RSC page.tsx fetch → pass props to client workspace
3. loading.tsx = DC skeleton (shimmer, correct aspect ratio)
4. CSS module measurements from DC inline styles
5. Wire live data — honest empty/error; onRetry on error
6. Map DC labels to schema (shoot_portfolio_view, etc.)

# Style gate on changed paths
rg '#FBF8F5|#E87C4D|min-h-screen' app/src/components/shoot app/src/app/\(operator\)/app/shoots

5. Verify

cd app && npm run lint && npm test && npx tsc --noEmit && CI=true npm run build
npx playwright test e2e/shoots-list.spec.ts   # when Shoots List touched
npx playwright test e2e/brand-dc-parity-screenshots.spec.ts  # brand screens

Browser QA ([e-mail], :3002):

• 1280 desktop + 390 mobile (+ 1024 if shell mobile in scope)
• Console clean · network 200 on data routes
• Screenshot each state vs DC toggle

Save: docs/qa/screenshots/YYYY-MM-DD/<screen>/

6. Report

Use references/report-template.md — include 14-dimension table for Shoots List.

@task-verifier before merge · Bugbot threads resolved.

---

Parity scoring

Score	Meaning
90–100%	Layout, cards, typography, all states match; live data honest
75–89%	Structure match; documented minor gaps
50–74%	Grid present; major states or mobile gaps
<50%	Wrong paradigm (legacy hex, wrong cols, client-only fetch)

Dimensions: layout · spacing · cards/images · typography · states (×5) · responsive · data honesty.

---

Example prompts

@design-to-production — audit Shoots List.v2.image-first.dc.html vs /app/shoots.
Phase 0 tables only; cite dc-html-anatomy zones + 14-dimension checklist.

@design-to-production implement IPI-273 workspace only — RSC page + shoots-list.module.css.
Match 920px / 3-col / DC empty state. No shell rebuild.

---

Overlap

Need	Skill
Single screen parity	design-to-production
Full program / Linear phases	claude-design-handoff
Linear steps + proof	ipix-task-lifecycle
Forensic Done	task-verifier

---

Checklist before merge

• Phase 0 tables in issue md
• DC HTML file read; Workspace-only diff
• No legacy hex / min-h-screen in changed files
• RSC + loading.tsx where list screen
• All DC states implemented (not collapsed)
• lint · test · tsc · build green
• Side-by-side screenshots per checklist dimension
• Report + known gaps honest
• One concern per PR

---

References

File	Contents
dc-html-anatomy.md	Parse DC HTML structure
react-next-parity-rules.md	Next.js + React patterns
screen-checklists.md	Shoots List 14 dims + index
route-map.md	HTML → route
report-template.md	PR / QA report