Handing Claude Design Mockups Straight to Claude Code: Folding the Design-to-Code Loop

// design/tokens.json — the one source of truth for design and code
{
  "color": {
    "brand":   { "value": "#5B5BD6" },
    "fg":      { "value": "#1A1A2E" },
    "fg-muted":{ "value": "#5C5C70" },
    "bg":      { "value": "#FFFFFF" },
    "bg-subtle":{ "value": "#F5F5FA" },
    "border":  { "value": "#E2E2EC" }
  },
  "radius": { "sm": { "value": "8px" }, "md": { "value": "12px" }, "lg": { "value": "20px" } },
  "space":  { "1": { "value": "4px" }, "2": { "value": "8px" }, "3": { "value": "12px" }, "4": { "value": "16px" }, "6": { "value": "24px" } },
  "font":   { "size-body": { "value": "15px" }, "size-h2": { "value": "22px" }, "line-body": { "value": "1.8" } }
}

// scripts/build-tokens.mjs — generate CSS variables from tokens.json
import { readFileSync, writeFileSync } from "node:fs";
 
const tokens = JSON.parse(readFileSync("design/tokens.json", "utf8"));
const lines = [];
 
// Recursively flatten nested tokens into "--group-key: value;"
function walk(node, prefix) {
  for (const [key, val] of Object.entries(node)) {
    if (val && typeof val === "object" && "value" in val) {
      lines.push(`  --${prefix}${key}: ${val.value};`);
    } else if (val && typeof val === "object") {
      walk(val, `${prefix}${key}-`);
    }
  }
}
walk(tokens, "");
 
const css = `:root {\n${lines.join("\n")}\n}\n`;
writeFileSync("src/styles/tokens.css", css);
console.log(`✅ wrote ${lines.length} tokens to src/styles/tokens.css`);

/* src/styles/tokens.css — generated. Do not edit by hand */
:root {
  --color-brand: #5B5BD6;
  --color-fg: #1A1A2E;
  --color-fg-muted: #5C5C70;
  --color-bg: #FFFFFF;
  --color-bg-subtle: #F5F5FA;
  --color-border: #E2E2EC;
  --radius-sm: 8px;
  --radius-md: 12px;
  --radius-lg: 20px;
  --space-1: 4px;
  /* …and so on… */
}

## Design rules (mandatory during implementation)
 
- Always use the CSS variables in src/styles/tokens.css for color, spacing,
  radius, and font. Never write raw hex or px in components.
- Radius: card = var(--radius-md), button = var(--radius-sm), modal = var(--radius-lg).
- Body text uses var(--font-size-body) / line-height var(--font-line-body).
  H2 uses var(--font-size-h2).
- Need a new color or spacing value? Add it to design/tokens.json, rerun
  build-tokens.mjs, then reference it with var() — never inline it.
- Never drop the focus ring (2px outline in var(--color-brand)).

# Handoff prompt to Claude Code (example)
 
Implement the membership card I created in Claude Design.
 
Constraints:
- Use only the CSS variables in src/styles/tokens.css (no raw color or px).
- Reuse the existing <Card> and <Button variant="primary">; do not add new styles.
- Match the structure of the existing src/components/cards/PlanCard.tsx.
- Dark mode should follow automatically via the existing [data-theme="dark"] variables.
- Accessibility: the button must be a real button element; the price is emphasized
  text, not a heading.
 
Before you finish, list any raw color or px values you had to add.

// scripts/check-tokens.mjs — detect inline values in components
import { readFileSync, globSync } from "node:fs";
 
const files = globSync("src/components/**/*.{tsx,css}");
const hexRe = /#[0-9a-fA-F]{3,8}\b/;   // raw hex colors
const pxRe  = /:\s*\d+px/;             // raw px (not via var())
 
let violations = 0;
for (const file of files) {
  const lines = readFileSync(file, "utf8").split("\n");
  lines.forEach((line, i) => {
    if (line.includes("var(--")) return;  // variable references are fine
    if (hexRe.test(line) || pxRe.test(line)) {
      console.log(`⚠️ ${file}:${i + 1}  ${line.trim()}`);
      violations++;
    }
  });
}
console.log(violations === 0 ? "✅ no inline values" : `🛑 ${violations} inline values found`);
process.exit(violations > 0 ? 1 : 0);