Claude Code + Figma MCP

A Figma frame can tell Claude Code a great deal about appearance and hierarchy, but it does not explain the application around that screen. The repository holds the routing conventions, component APIs, typography setup, data layer, tests and deployment constraints. If you ask for implementation before Claude Code reads that context, it may faithfully reproduce the frame in a way that is completely foreign to the product.

I ask for a written mapping first. Which existing component corresponds to the primary button? Where are form controls defined? Does the repository use CSS modules, Tailwind, a token package or a component library? Which layout component owns the page width? Is there already a loading skeleton or error banner? The mapping reveals uncertainty while it is still cheap.

This is also the moment to protect the work of another developer or agent. Tell Claude Code to inspect the worktree, identify existing changes and avoid overwriting unrelated files. Specify the route and the files it is allowed to touch when the boundary is known. A design implementation should not become permission for broad refactoring.

The audit should end with questions, not hidden assumptions. A desktop frame may not define the mobile sequence. A polished card may contain placeholder data that is much shorter than production content. A disabled state may be absent. Ask Claude Code to list those gaps and propose conservative behavior for approval.

The most expensive design-to-code failure is not a four-pixel spacing difference. It is a page that introduces near-duplicates of components the product already owns. The new button looks correct today but lacks the existing analytics hook, loading state, accessibility behavior and future style updates. The visual review passes while the architecture quietly gets worse.

Code Connect addresses that problem by mapping a Figma component to its implementation in code. When the Figma frame contains a mapped instance, the MCP context can tell Claude Code which component and source correspond to it. The agent has a much stronger reason to import the real component rather than reconstructing one from divs and CSS.

Not every object deserves a mapping. Start with the repeated primitives that carry behavior: buttons, inputs, select controls, cards, navigation items, alerts and dialogs. Keep the mappings current as component APIs change. A stale mapping can be worse than no mapping because it looks authoritative.

Even without Code Connect, you can improve reuse by pointing Claude Code to the component directories and requiring an inventory before creation. I use a blunt rule: if the agent proposes a new primitive with a generic name, it must explain why no existing primitive can do the job.

I separate the work into four passes. The first pass establishes semantic structure and uses the correct components. The second handles responsive layout and content extremes. The third refines typography, spacing, borders and assets. The fourth validates interactions and tests. This order prevents hours of pixel polishing on markup that later needs to be replaced.

In the structure pass, the agent should use headings, landmarks, labels and controls that make sense without CSS. In the responsive pass, it should test the longest realistic labels and data. Stable controls should have stable dimensions so a loading message or validation icon does not shift the surrounding layout. Tables require a deliberate mobile strategy rather than accidental horizontal overflow.

Visual refinement should use the product's tokens. Hard-coded values are acceptable only when the design truly introduces a new approved value. If the Figma file says “Brand/Primary” and the repository has a matching token, using an arbitrary hex value is a context failure. The agent should also retrieve and use the actual supplied assets rather than replacing them with generic icon packages or placeholders.

Finally, validate behavior. Tab through the page. Open menus and dialogs. Submit invalid and valid data. Check loading and empty states. Resize the viewport. Inspect the browser console. Run the repository's normal type, lint and test commands. The Figma reference is one source of truth; the working application has several.

Start at the exact reference viewport when the design provides one. Confirm the page width, major grid, header height and content order before measuring small gaps. Then test the width just above and below each layout transition. A page can look excellent at 1440 pixels and 390 pixels while failing at 768 pixels, where neither desktop nor mobile assumptions hold.

Compare real states, not an empty shell. Use representative long titles, validation messages, unavailable images and slow-loading content. Check whether text fits its container without reducing the font based on viewport width. Confirm that buttons do not resize when icons or status labels appear. Look for overlays that cover headings or sticky elements that hide anchor targets.

Pixel checks are valuable for confirming that the rendered canvas is nonblank and roughly aligned, but I do not use a single difference score as a release gate. Browser font rendering, responsive content and dynamic data create legitimate differences. The meaningful questions are whether the hierarchy, spacing system, components, behavior and brand intent survived implementation.

Ask Claude Code to report intentional deviations. If it changed color contrast for accessibility, adjusted a tap target or reorganized mobile content, that should be visible to the designer. A silent “improvement” is still a broken handoff if the owner never approved it.

Product reality often moves ahead of the design file. A feature gains an error state, a table receives real data or a responsive layout changes during implementation. Figma's remote MCP server can support a code-to-canvas capture in compatible clients, allowing Claude Code to start the local application and guide you through capturing selected pages or states as editable Figma layers.

Capture the state that needs discussion, not every route. A single settings screen with open, loading, error and success states is more useful than an indiscriminate import of the application. Name the destination file and page clearly, note the source commit and add an annotation explaining why the state was captured.

Once designers refine the captured state, use a new linked frame for the next implementation request. The process is a controlled loop rather than automatic synchronization. That makes ownership clearer: Figma remains the place for visual exploration, and the repository remains the executable source of truth.

Imagine the selected Figma frame is an authenticated billing dashboard. It contains a navigation rail, current-plan summary, invoice table, payment method and an upgrade action. A weak request says, "Build this Figma design." Claude Code may produce an attractive static page, invent sample invoice data and attach the upgrade button to nothing. The screen resembles the reference, but the product behavior is fiction.

I begin by asking for an implementation brief. Claude Code should identify the visible regions, likely reusable components, responsive changes, interaction states and open questions. It should then inspect the repository for the existing application shell, table, button, badge, billing client, authentication guard and route conventions. At this stage I want a map, not code. If the repository already has a table with sorting and empty-state behavior, the plan should name it. If the Figma frame uses a color that has no project token, the plan should flag the mismatch.

The first coding pass builds only the route shell with existing components and typed placeholder data. The goal is to prove hierarchy and responsiveness. The second pass connects the real billing data through the project's established data layer, including loading, empty, error and permission states. The third pass implements actions: changing a payment method, downloading an invoice and opening the upgrade flow. Each action needs a success path, failure feedback and keyboard behavior. The fourth pass compares the page with Figma and records approved deviations.

Real content is the stress test. An invoice identifier can be longer than the design sample. A localized currency can change column width. A past-due account may need two status badges and an explanatory alert. I ask Claude Code to test those cases before tightening pixels. If the mobile design omits the table, the agent should not simply hide financial history; it should propose a stacked invoice list or another usable representation and ask for approval.

Finally, I review the change as engineering work. I inspect the diff for duplicate primitives, hard-coded tokens, broad dependencies and accidental edits outside the route. I run the repository's checks, verify the route while authenticated and unauthenticated, and capture the principal states for design review. Figma MCP shortens the distance between reference and implementation, but this sequence is what turns that speed into maintainable product code.

Claude Code and Figma MCP are most valuable when the repository already has structure worth preserving. A product team with a component library, tokens and review checks benefits because the agent can connect design intent to existing implementation patterns. The workflow is also useful when designers and developers repeatedly lose information during handoff.

It is less valuable for a one-page disposable prototype with no design system and no future maintenance. In that case, Figma Make, Lovable or a smaller direct build may reach the result with less setup. It is also a poor fit when the design is not approved or the repository is in the middle of a large migration; the agent will automate uncertainty rather than resolve it.

Measure total delivery time. Include design preparation, prompt supervision, code review and repair. If MCP saves one hour of initial markup but creates two hours of component cleanup, the team has learned where its context is weak. Improve the Figma structure, mappings and project rules before scaling.