Design System Handoff to Claude Code

The weakest handoff to Claude Code is a screenshot plus a request to make it identical. The screenshot shows the outcome at one moment. It does not identify existing components, token names, responsive rules, content states, or the tests that decide whether the implementation is finished.

The Private by Design reference on Refframe has a clear composition: one dominant serif statement, small red outlined panels, an icon, and a controlled black field. To implement it inside a product, Claude Code still needs to know whether the serif is already licensed and loaded, which red token passes the intended contrast, how the panels move on mobile, and which component owns their rounded outline.

Start with a repository map

Before asking for implementation, give Claude Code the smallest map that prevents unnecessary exploration and duplication:

• framework and package manager;
• application and shared UI directories;
• token and theme files;
• component exports;
• icon, image, and font conventions;
• page and route location;
• lint, type-check, test, build, and screenshot commands;
• files or directories that must not change.

Ask Claude to inspect the mapped components before proposing new ones. A short discovery step often reveals that the needed container, button, card, or typography utility already exists.

Put persistent facts in CLAUDE.md

Claude Code reads CLAUDE.md files as persistent project instructions. Anthropic recommends keeping them concise, specific, and focused on facts the tool should know in every session: commands, architecture, conventions, and non-negotiable workflow rules.

Useful design-system entries include:

• tokens are consumed from a named file and raw hex values are not added to components;
• shared components live in a named package;
• pages compose public components rather than importing internal files;
• all interactive states require keyboard-visible focus;
• screenshots are checked at specified viewport sizes;
• new tokens or variants require design-system review.

Do not turn CLAUDE.md into a full component catalog. Anthropic’s documentation suggests moving multi-step procedures or context needed only sometimes into skills or path-scoped rules. Point the project map to detailed documentation instead of loading it into every conversation.

Give tokens as a versioned file

Pass the actual token source, not a pasted palette. A useful token file contains stable names, explicit types, values or aliases, modes, and descriptions. Tell Claude which generated formats must not be edited directly.

Map Figma and code names when they differ:

• Figma variable action/background/primary maps to the code token color.action.background.primary;
• Figma spacing/layout/gutter maps to space.layout.gutter;
• Figma text/heading/display maps to the Display typography component or utility.

Include the command that validates or builds tokens. If there is no automated check, require Claude to list every new raw color, spacing value, or font size it introduces so a reviewer can catch drift.

Provide a component manifest

The manifest can be Markdown or JSON. It does not need to duplicate TypeScript types if Claude can read them. It should help the agent find the correct public interface quickly.

For each relevant component, include:

• Figma name and code name;
• import path;
• purpose;
• variants and states;
• content slots;
• responsive behavior;
• accessibility notes;
• example or story path.

For the reference above, the manifest might point to PageContainer, DisplayHeading, AnnotationCard, and FocusableLink. If AnnotationCard does not exist, ask Claude to explain whether the pattern is reusable before adding it to the shared library. One page-specific arrangement does not automatically deserve a global component.

Describe page structure as relationships

A page spec should say what each section accomplishes, which components it uses, how content is ordered, and how the layout transforms. Avoid a list of absolute coordinates copied from Figma.

For each section, record:

• semantic heading level;
• container and grid;
• component composition;
• content source;
• desktop and mobile ordering;
• optional and failure states;
• interaction and motion;
• reference URL and the specific decision to borrow.

A Refframe board is useful when several references inform the page. Add notes such as use this for headline scale, use this for card grouping, and do not copy the imagery. That is more actionable than a board called inspiration.

Write the implementation request around evidence

A strong request can follow this sequence:

1. inspect the listed token, component, and route files;
2. summarize which existing pieces will be reused;
3. flag missing decisions before editing;
4. implement the page within the named boundaries;
5. run focused checks;
6. capture screenshots at the specified viewports;
7. compare against the references and list differences;
8. fix material differences and report any intentional deviation.

Tell Claude what must remain original. A reference can guide hierarchy, density, rhythm, or responsive behavior. It should not become a request to reproduce protected branding, copy, imagery, or proprietary code.

Give Claude something it can verify

Anthropic’s best-practices guide calls verification one of the most valuable parts of a request. For interface work, provide expected states and screenshot targets alongside code checks.

A practical acceptance list includes:

• existing tokens and components are reused where appropriate;
• no unexplained raw colors, spacing, or type sizes were added;
• headings and landmarks follow the intended structure;
• focus, hover, error, loading, and disabled states work;
• long copy and missing media do not break the layout;
• the page reflows at narrow widths;
• lint, types, and focused tests pass;
• screenshot differences are reviewed, not merely generated.

The quality of the result depends less on one enormous prompt than on a clean chain of evidence: system map, token source, component interface, page relationships, inspected references, and checks that can fail.