Designing a design system in Figma, then implementing it with Claude Code

What the Figma side of the system looked like

The design system was built in Figma with structured tokens: spacing, color, typography, border radius, shadow, all defined as variables with explicit naming conventions. Components were built with clearly named auto-layout frames, variants organized by state (default, hover, focus, disabled, error), and component properties exposed in a consistent way. Documentation was embedded directly in the component structure rather than maintained separately.

This level of structure is not exceptional for a mature design system, but it matters here for a specific reason: it made the file legible to Claude Code via the Figma MCP. The model could read component names, variant labels, token values, and structural hierarchy. A loosely organized Figma file with inconsistent naming would have produced much noisier output at the implementation stage.

How Claude Code reads the design system

The Figma MCP gives Claude Code access to the file's data: component structure, token values, layer names, variant combinations. This is not screenshot-to-code. The model is reading structured design data, which is a meaningfully different input. It can distinguish between a "Button/Primary/Large/Default" and a "Button/Primary/Large/Hover" state, not by interpreting a visual, but by reading the component tree.

In practice, this produced several concrete outcomes. Atomic components (buttons, inputs, badges, tags, chips) were implemented with high fidelity in the first pass. The spacing, the border radius, the color tokens, the typography scale: all matched the Figma spec without manual correction. The gap that normally exists between what a designer specifies and what gets built was close to zero for these elements.

Composite components (cards, navigation, form sections) required more iteration. The structural logic of how sub-components should interact was not always readable from the file structure alone. This required going back to Figma, making the hierarchy more explicit, and running the implementation pass again. It is work, but it is a different quality of work: design clarification rather than bug-fixing after the fact.

The implementation platform and why Astro made sense

The dedicated design system site was built in Astro with Tailwind CSS. Astro was chosen for its component isolation model and its ability to produce a lightweight, fast static site without a heavy JavaScript framework overhead. Tailwind mapped cleanly to the token system: the design token values were translated directly into Tailwind config extensions, so the CSS layer and the design file shared the same underlying values.

Claude Code drove the implementation of each component page: generating the component code from the Figma data, building the documentation layout, creating the usage examples, and writing the token reference tables. The role of the designer in this phase was to evaluate fidelity, flag deviations, and clarify ambiguities in the design structure rather than to write markup or CSS.

Where the single source of truth actually holds

The practical result of this workflow is that the Figma file and the implementation stay in sync as long as the design file stays structured. When a token value changes in Figma (a color, a spacing unit, a border radius), the change can be propagated to the codebase through a targeted Claude Code session rather than through a manual find-and-replace across dozens of files. When a new component variant is added in Figma, the implementation can be generated from the new file state rather than from a written spec.

This doesn't eliminate human judgment. It changes what that judgment is applied to. Instead of spending time on translation, making sure what was designed in Figma is accurately reflected in the code, the designer's attention goes to structural decisions: is this component variant necessary, does this token name communicate the right intent, does this documentation page help an engineer make the right decision without asking for clarification. These are higher-order questions. They are also the questions that actually determine whether a design system gets used or ignored.

The ceiling of the approach

The experiment had clear limits. Animation, motion, and interaction behavior were not readable from the Figma file in a way that produced accurate implementation. Complex layout decisions involving responsive behavior required explicit description rather than inference from the design data. And the quality of the Figma MCP output degraded noticeably for deeply nested component structures.

The conclusion is not that AI-driven design system implementation replaces designer involvement. It is that a well-structured design file in the hands of a designer who knows how to direct an AI implementation layer can compress the distance between specification and artifact to a degree that was not practically achievable before. The work that remains is design work. The work that disappears is translation work, and that is exactly what should disappear.