Before anything else: read $HOME/.agentic-workflow/toolkit/skills/_preamble.md and follow it (skill index, provider capability map, bootstrap check, session context). Run its Session Close section when this skill finishes.

Design context: read $HOME/.agentic-workflow/toolkit/skills/_design-preamble.md and follow it before continuing.

---

Design Implement Web — Generate Production Code from Mockup

Generate production-ready code from an approved mockup, generating token files directly from design-tokens.json, then proving the result against the mockup baseline before claiming completion.

Step 1: Select Mockup

Locate mockup sources in priority order — HTML source files are far more useful for code generation than PNG screenshots.

SHARED_DIR="$HOME/.agentic-workflow/toolkit/skills/_shared"
source "$SHARED_DIR/repo-slug.sh"
ls "$AW_DIR/design/mockup-"*.html 2>/dev/null          # HTML sources (preferred)
ls "$AW_DIR/design/mockup-web-"*.png 2>/dev/null       # CD3 PNG baselines (fallback)
ls "$AW_DIR/design/mockup-"*.png 2>/dev/null           # legacy baseline — re-run /design-mockup to upgrade

Selection rules (artifact ownership table: $SHARED_DIR/design-artifact-paths.md):

• No mockups found: stop — "Run /design-mockup <screen-name> first."
• One mockup: use it automatically (prefer HTML when both exist for the same screen).
• Multiple mockups: list both types with their source annotated and ask the user which to implement.

When an HTML source exists, it is the primary reference for layout and structure; a PNG baseline for the same screen is supplementary. Record which file was actually selected and whether it is HTML or PNG — the Step 5 report and implement-report.json must name the real source, never assume PNG.

Step 2: Generate Token Files

Generate both files directly from design-tokens.json (W3C DTCG: nested objects with $value/$type leaves). No external bridge is involved.

1. CSS custom properties — design-tokens.css:

• Flatten each token path to a kebab-case variable: color.text-primary → --color-text-primary, spacing.s2 → --spacing-s2, font.family-mono → --font-family-mono.
• Emit a single :root { ... } block containing every token.
• If the token set defines dark-mode variants (e.g. color.dark.* or dark values in $extensions), emit an additional @media (prefers-color-scheme: dark) { :root { ... } } block overriding only the affected variables.

2. Tailwind config extension:

• If a tailwind.config.{ts,js,mjs,cjs} exists, edit it in place: extend theme.extend.colors, theme.extend.spacing, theme.extend.fontFamily, and theme.extend.borderRadius with entries that reference the CSS variables (e.g. accent: "var(--color-accent)").
• If no Tailwind config exists, write tailwind.preset.js at the project root with the same theme.extend shape and note in the report that it must be wired into a future config.

Exact output paths:

File	Path
CSS custom properties	<project-root>/styles/design-tokens.css — if the project keeps global CSS elsewhere (src/styles/, app/), follow the existing location; create styles/ only if no convention exists
Tailwind extension	existing tailwind.config.{ts,js,mjs,cjs} edited in place; else <project-root>/tailwind.preset.js

Import design-tokens.css from the app's global stylesheet or root layout if it is not already imported.

Step 3: Generate Component Code

Using the mockup as visual reference and the generated token files:

• Generate React/Next.js components (or plain HTML/CSS if no framework detected)
• Import from tokens.css or use Tailwind classes from the preset
• Follow the component structure visible in the mockup
• Use semantic HTML elements
• Include responsive breakpoints matching the mockup

Reference .impeccable.md for design personality — spacing density, animation approach, interaction patterns.

Step 3.5: Token Compliance Scan

Always run a content search (e.g. rg -n) over every file created or modified in Steps 2–3 (excluding design-tokens.css itself, which legitimately holds raw values):

rg -n '#[0-9a-fA-F]{3,8}\b' <each changed file>
rg -n '\b[0-9]+px\b' <each changed file>

Report every hit as file:line — <matched value>. For each: replace it with the corresponding token variable, or record an explicit justification when no token corresponds (e.g. 1px hairline borders). Unjustified hits must be fixed before Step 4.

Dark factory (optional): follow $SHARED_DIR/dark-factory.md using its "design-implement (token-compliance)" objective template — gate on dark-factory.json, route via mcp: prism-mcp/session_task_route, run mcp: prism-mcp/prism_infer only on a claw target, and verify any reported violations yourself (re-search) before acting on them. Config absent ⇒ skip silently. The content search above runs regardless.

Step 4: Verification Gate (mandatory)

Run the visual diff against the mockup baseline:

Invoke skill design-verify-web with args "<screen-name>"

Read the run's design/verify/<run-id>/comparison-report.json (schema and CD11 thresholds: $SHARED_DIR/design-artifact-paths.md). The gate binds to overall.verdict:

• PASS (≤2%) or WARN (2–10%) → implementation may complete.
• FAIL (>10%) → print [BLOCKED] followed by the failing screen/viewport rows and the required fixes (region-level deviations from the report). Never print "Implementation Complete" while the verdict is FAIL — fix the deviations and re-run this step.

Step 5: Report

Write $AW_DIR/design/implement-report.json (machine artifact — consumed by design-verify, review, shipRelease):

{
  "schema": "implement-report/v1",
  "screens": ["<screen-name>"],
  "files_written": ["styles/design-tokens.css", "tailwind.config.ts", "<component files>"],
  "token_coverage_pct": 0,
  "mockup_source": "<selected file from Step 1> (html | png)",
  "verify_run_id": "<run-id from Step 4>",
  "overall_verdict": "PASS | WARN | FAIL"
}

token_coverage_pct = distinct tokens referenced in generated code ÷ tokens defined in design-tokens.json × 100.

Then print (only when overall_verdict is PASS or WARN):

Implementation Complete
=======================

Target:      web
Mockup:      <actually selected source from Step 1, e.g. mockup-dashboard.html (HTML source)>
Verify run:  <run-id> — <overall_verdict> (max diff <pct>%)

Generated token files:
  <CSS custom-properties path>
  <Tailwind config/preset path>

Generated components:
  <list of created/modified component files>

Rules

• Token files go at the exact paths in Step 2 — never scatter per-component token files
• Never hardcode values that exist in design-tokens.json — always reference the generated token files
• Do not modify design-tokens.json — it is the source of truth
• If the mockup HTML is available, use it as the primary reference for layout and structure — and report it as the source
• No completion claim without a PASS/WARN verify run recorded in implement-report.json

Next steps

• /design-refine "align color usage with the token palette" / "polish hover, focus, and transition states" / "tighten the type hierarchy" — refinement intents, dispatched through impeccable
• /shipRelease — ship once the verify verdict is PASS
• Commit generated token files: git add <token file paths>