Pointing Claude Design at Your Codebase: Closing the Design-to-Implementation Loop Solo

Use design-system import to kill the "slight drift"

Alongside code grounding, design-system import is what helps most. Because I used to describe the brand on every generation, drafts drifted—radius 6px here, 8px there. Import pins that source of truth on the tool's side.

The key is the priority order of what you import. I find this order keeps accuracy stable.

1. Shipped token definitions (CSS variables in tokens.css) — the most trustworthy source
2. Component implementations (the actual Button.tsx in use) — behavior and states included
3. Spec docs or style guides (if any) — articulated intent
4. Verbal or written descriptions — last-resort fill-in

Implementation comes first because running code does not lie. A style guide may say "radius 8px," but if the real code is 10px, what users see is 10px. Writing a tiny script once to harvest tokens mechanically makes pre-import cleanup easy.

// scripts/extract-tokens.ts
// Pull CSS variables from :root in tokens.css into an import-ready JSON.
// Expected output: { "color-primary": "#6d5ae6", "radius-md": "8px", ... }
import { readFileSync, writeFileSync } from "node:fs";
 
const css = readFileSync("src/styles/tokens.css", "utf8");
 
// Target only declarations inside :root { --name: value; }
const root = css.match(/:root\s*{([^}]*)}/s)?.[1] ?? "";
const tokens: Record<string, string> = {};
 
for (const line of root.split(";")) {
  const m = line.match(/--([\w-]+)\s*:\s*(.+)/);
  if (m) tokens[m[1].trim()] = m[2].trim();
}
 
writeFileSync("design-tokens.json", JSON.stringify(tokens, null, 2));
console.log(`Tokens extracted: ${Object.keys(tokens).length}`);
// Run: npx tsx scripts/extract-tokens.ts → Tokens extracted: 37

The script itself is humble, but the point is that no human re-picks colors with a screenshot or eyedropper. Because I keep token names aligned across four sites, writing it once lets me reuse it everywhere. Once I stopped picking colors by hand, the per-draft drift visibly shrank.

Generate first, then fix directly on the canvas

After a code-grounded mockup appears, the details are rarely perfect. A heading's line height is a touch tight; a card's shadow is too strong. I used to fix these by rewriting the prompt and regenerating. But saying "make the shadow 20% lighter" and regenerating can subtly change other parts too.

Direct canvas editing lets me fix this by hand. My rule is simple: structure in the prompt, visual fine-tuning on the canvas.

• Decide in the prompt: section composition, presence of elements, the rough layout
• Fix on the canvas: spacing, line height, shadow, font size by one or two steps

With this split, I avoid the "the place I fixed reverted" accident on regeneration. It is just that what is faster to convey in words differs from what is faster to move by hand—and the tool has finally caught up to that obvious truth.

A code-grounded draft hands off without breaking

This is the part I am happiest about. In the old handoff, Claude Code implemented a from-scratch design, so the agent still had to guess "which existing token does this spacing correspond to." A wrong guess slips a one-off value into the code.

A draft generated from code already sits on top of existing tokens. So the "find the matching token" step nearly vanishes at handoff. I keep a small slash command on the receiving side that forces the mapping to be explicit.

<!-- .claude/commands/accept-design.md -->
Implement the given design spec. Obey these constraints strictly.
 
1. Do NOT invent new color/spacing/radius values. Map everything to existing
   variables (var(--...)) in src/styles/tokens.css.
2. If a value has no matching existing token, do not implement it—report it
   in a list. Do not silently round to a near value.
3. Reuse existing components under src/components/ui/. If you must create a new
   one, add a one-line reason.
 
Output: list of changed files + a list of "no token match, needs decision" items

Constraints 1 and 2 are the crux. Make the agent promise to "stop and report when something is missing" rather than "make it up when something is missing." A code-grounded draft rarely produces a mismatch in the first place, but ensuring nothing slips in quietly pays off over a long run. The internal mechanics of the handoff are covered in the production handoff guide, but simply changing the starting point to code made this acceptance work noticeably lighter.

Choosing among export formats

With more export formats, you can pick the best handoff per downstream step. The three I actually switch between are these.

Solo, I often use one and the same mockup twice—"send to implementation" and "make it an announcement image." Exporting from a single generation in two directions—structured spec for code, image for promotion—is a genuinely welcome change for someone running both operations and outreach alone.

Where I tripped, and how I fixed it

Finally, three things I stumbled on early in the move. Concrete examples so you avoid the same ruts.

1. Reading the whole repo made drafts wander. Without scoping the starting point, it even picked up colors from test dummy data, adding noise. It stabilized the moment I narrowed reading to three layers in DESIGN_CONTEXT.md.

2. Feeding the style guide as top priority drifted. Putting the articulated spec first produced values at odds with the real code. Swapping the order to "implementation tokens > components > spec docs" resolved it. Treating running code as canonical is ultimately the most reliable.

3. Regenerating via prompt after canvas edits erased the touch-ups. Redoing a structural change in the prompt reverted the spacing I had dialed in on the canvas. Since then I fix the order—"settle structure, then finish on the canvas"—to avoid it.

In every case it was my sequencing, not the tool. The new code-grounded direction is powerful, but narrowing the starting point, deciding the source-of-truth priority, and splitting the roles of structure and fine-tuning—settle these three up front and you reach stability fastest.

Your next step

Start by writing a single DESIGN_CONTEXT.md in the small repo you touch most, and generate one screen from only the tokens and UI components as the starting point. Once you see how much of the existing look carries over, you'll have a feel—grounded in your own setup—for how far to trust the tool and where to keep your own hands on the work.

Thank you for reading. I'm still settling this new direction into running four sites myself, but I'd be glad to keep verifying, hands on the keyboard together, how the line between design and implementation keeps thinning.