Articles/Claude Code

⟐ Claude Code/2026-04-04Advanced

Claude Code + Figma MCP Advanced Guide: Automating Your Personal Design Workflow

Master the deep integration of Claude Code and Figma MCP. Complete Design.md system design, advanced implementation patterns, iteration strategies, and real-world optimization techniques.

Claude Code²²⁵ Figma MCP Design Automation Design-md Advanced³

✦ Premium Article

The first time a Figma design turned into working components right in front of me, I stayed up far too late just watching it happen. The thrill was real — and so was the lesson that followed over the next few weeks: "the first generation runs" and "it survives real maintenance" are two very different things.

Running several apps and a handful of sites on my own as a solo developer, the time I spend bouncing between design and implementation is, quite literally, the ceiling on how fast I can ship. That is exactly why I have leaned so hard on Figma MCP.

This guide records what I learned along the way — where the tooling's boundaries actually are, how to structure Design.md, and the pitfalls that only surface once you are running it for real, with the numbers I measured. Not a summary of the docs, but the hands-on instincts I picked up myself.

Figma MCP: Technical Specifications

Figma MCP is the bridge between Claude Code and Figma files. Knowing precisely what it reads and writes is critical for reliable automation.

What Figma MCP Extracts

1. Layer Hierarchy (Complete DOM-like structure)

{
  "id": "1:2",
  "name": "Button Primary",
  "type": "component",
  "parent": "3:4",
  "visible": true,
  "children": [
    {
      "id": "5:6",
      "name": "Icon",
      "type": "instance"
    },
    {
      "id": "9:10",
      "name": "Label",
      "type": "text",
      "content": "Click me"
    }
  ]
}

This translates directly to React component structure. A Figma component becomes a React component; a text layer becomes a {children} prop.

2. Design Tokens (Full precision)

MCP returns colors, typography, spacing, sizing, effects, and grid data. Each value maps to Tailwind CSS classes or CSS variables with zero ambiguity.

3. Component Metadata (Interface-level)

{
  "componentId": "12:34",
  "componentName": "Button / Primary",
  "properties": {
    "size": {
      "type": "enum",
      "values": ["small", "medium", "large"],
      "default": "medium"
    },
    "disabled": {
      "type": "boolean",
      "default": false
    }
  }
}

This auto-generates TypeScript interfaces.

4. Interaction & Animation Definitions

Figma's Prototype panel exports interaction data that Claude Code translates to Next.js routing or CSS transitions.

What Figma MCP Cannot Extract

Image pixel data (only URLs)
Complex mask/blend modes (hand-tuning required)
Plugin metadata
External tool data (use Design.md instead)

Key mindset: MCP is "90% automation + 10% human judgment."

When the Connection Itself Fails: Check in This Order

Knowing the spec is moot when Claude Code cannot reach Figma at all — and I stalled at this doorstep more than once. In the order I hit these myself:

Symptom	Cause	Fix
Figma never appears in the tool list	Dev Mode MCP server is not running	Enable the MCP server from the Figma desktop app preferences (the browser version does not serve it)
Connected, but "cannot fetch the design"	URL is missing a node-id	Select the frame and use "Copy link to selection" so the URL carries the node reference
Results come back nearly empty	Seat permissions fall short	Dev Mode assumes a paid seat; a view-only invite will not surface the internals

Because this setup routes through the locally running Figma desktop app, nothing flows while the app is closed. You never notice that during interactive use — but the moment I wired generation into an automated step, I forgot the "app must be awake" premise and stalled. If you want design extraction inside a nightly batch, exporting the JSON ahead of time and passing that instead is the more stable arrangement.

Generation Quality Is Decided on the Figma Side

Once I understood the spec, the place I ended up investing the most time was not the Claude Code prompt. It was how I structured the Figma file itself. The same screen, organised differently, produces wildly different code. That realisation stopped me in my tracks.

Fifteen to twenty minutes before you hand it over. That is where the leverage is.

Name Layers After Their Role

Hand over Frame 123 and Group 45 and the generated component names inherit that emptiness. Rename them by role—HeroSection, PricingCard, NavigationBar—and the component names and class names come back readable.

A layer name is the shortest documentation that reaches Claude Code.

Promote Repeating Elements to Figma Components

Buttons, cards, headers. Anything that appears more than once should be an explicit Figma component. Claude Code then splits it out as a React component. Elements you leave un-componentised tend to get generated as duplicated inline markup, even when they look identical.

Decide the Atoms → Molecules → Organisms granularity in Figma first. That small effort erases the deduplication work you would otherwise do afterwards.

Replace Absolute Coordinates With Auto Layout

Of the four, this one moved the needle most.

Figma setup	Generated code	When the viewport changes
Absolute coordinates (fixed x, y)	position: absolute, fixed px	Breaks — hand-fixing required
Auto Layout	Flexbox / CSS Grid	Adapts as-is

Screens built with Auto Layout need almost no responsive rework. Screens handed over with absolute coordinates had to have their layout rewritten after generation, which rather defeated the point of generating them.

Put Non-Visual Specs in Annotations

Hover opacity. Scroll-triggered fade-ins. Behaviour that a static frame cannot show should be stated in Figma annotations.

If the "Animation & Motion" section of Design.md is the source of the values, annotations are the source of where those values apply. Only with both in place does the interaction come out matching the spec.

The Difference It Makes

Aspect	Prepared design	Unprepared design
Component reuse	Split along the Figma hierarchy	Identical UI inlined several times over
Responsiveness	Adapts via Flexbox / Grid	Breaks on fixed px
Naming consistency	Role names carry through	Frame1, Group2 survive into the code
Post-generation rework	Minor tuning only	Structural rewrite

Fifteen to twenty minutes before the handoff removes hours after it. For me this remains the highest-return step in the whole Figma MCP workflow.

✦

Thank you for reading this far.

Continue Reading

What follows includes implementation code, benchmarks, and practical content we hope you'll find useful. This site runs without ads — server and development costs are supported entirely by members like you. If it's been helpful, we'd be truly grateful for your support.

WHAT YOU'LL LEARN

✦Map exactly what Figma MCP can and cannot extract, with JSON examples, so you know upfront which parts still need hand-tuning

✦Design Design.md as the single source of truth and build sync rules that propagate color, type, and spacing changes into Figma and code

✦Use measured numbers from solo development (20–30s initial generation, 2–3h → 15–30m update loops) to decide what to automate and what to keep human

Secure payment via Stripe · Cancel anytime

✦

Unlock This Article

Get full access to the rest of this article. Buy once, read anytime. This site is ad-free — your support goes directly toward keeping it running.

Unlock all articles with Membership →

Design.md: System Architecture

Design.md evolves from Stitch output into a living design system specification—the source of truth that keeps Figma, Claude Code, and future iterations aligned.

Complete Design.md Structure

1. Color System

Token	Hex	Usage
primary-50	#EBF8FF	Lightest surfaces
primary-500	#3B82F6	Primary actions
primary-900	#1E3A8A	Dark text, borders

Semantic colors: Success, Warning, Error, Info Neutral scale for accessibility (WCAG AA contrast guaranteed)

2. Typography System

Name	Size	Weight	Line Height	Context
H1	48px	700	1.2	Hero titles
Body-Large	16px	400	1.6	Long-form content
Body-Small	12px	400	1.5	Captions, metadata

Font families: System fonts + 'Noto Sans JP' fallback for Japanese

3. Spacing & Layout

Base unit: 8px Scale: 8 | 16 | 24 | 32 | 48 px

Layout Grid:

Desktop: 12 columns, 24px gap, 1200px max
Mobile: 4 columns, 16px gap, full-width

4. Component Specifications

Button example:

Variants: primary / secondary / ghost
Sizes: sm (32px) / md (44px) / lg (56px)
States: default / hover / active / disabled
Base styles: Tailwind classes, transitions

Card:

Elevation scale: 1 (light shadow) to 3 (heavy shadow)
Hover behavior: elevation +1
Base: 12px radius, 24px padding, white background

5. Animation & Motion

Fast (150ms): hover states, micro-interactions
Normal (250ms): transitions, state changes
Slow (400ms): entrance/exit, attention-grabbing
Easing: cubic-bezier(0.4, 0, 0.2, 1) (default, ease-in-out)

Common patterns: Fade, Slide, Scale Pop, Rotate Spin

6. Responsive Breakpoints

Mobile-first CSS strategy

7. Change Log

### v1.2.0 (2026-04-04)
- Added: Dark mode color scale
- Changed: Button padding 12px 24px → 14px 28px

### v1.1.0 (2026-03-15)
- Added: Input error state specification

Design.md ↔ Figma Sync Strategy

Design.md is the source of truth. Figma is the visual implementation.

Sync rules:

Color change → Update Design.md + Figma components
New component → Record in Design.md + Create in Figma
Monthly audit: Check Design.md ↔ Figma alignment

Implementation Patterns

Pattern 1: Simple Site (Full Auto-Generation)

/code
Figma: https://figma.com/design/xxx/SimpleLandingPage

Requirements:
- Next.js App Router
- Tailwind CSS v4
- TypeScript strict mode
- i18n: next-intl (EN, JA)

Design.md: [paste template above]

Claude Code generates: All components, page.tsx, layout.tsx, tailwind.config.js, i18n setup

What the Output Actually Looks Like: Tokens to Interfaces

How does the component-definition JSON from earlier actually land as code? Lined up against the Design.md tokens, the mapping looks like this:

// tailwind.config.ts — generated from the Design.md "Color Tokens" table
export default {
  theme: {
    extend: {
      colors: {
        primary: {
          50: "#EBF8FF",  // primary-50: backgrounds
          500: "#3B82F6", // primary-500: CTAs and headings
          900: "#1E3A8A", // primary-900: text and borders
        },
      },
    },
  },
};

// Button.tsx — the metadata enums become the Props verbatim
interface ButtonProps {
  size?: "small" | "medium" | "large";
  state?: "default" | "hover" | "active" | "disabled";
}

I would not ship that interface as-is, though. Hover and active belong to CSS pseudo-classes in practice, so after generation I remove state from the Props and turn disabled into a plain boolean. Code that is faithful to Figma and code that is natural React diverge by exactly one final step.

The reverse reading is just as useful: whenever a vague type like variant?: string shows up in an interface, the Figma component property behind it is almost never defined as an enum. The generated types let you back-trace gaps in the Figma file itself — and that back-trace is where I start every post-generation review.

Pattern 2: Complex App (Targeted Generation + Refinement)

/code
Figma: https://figma.com/design/xxx/ComplexApp

Issues:
1. Animation needs framer-motion
2. Multilingual: text length varies EN → JA
3. Dark mode: auto-invert colors

Instructions:
- Generate all components
- Wrap animation components with framer-motion
- Add i18n text-length comments
- Implement dark mode via Tailwind dark: prefix

Pattern 3: Design Iteration (Post-Launch Updates)

/code
Figma update: https://figma.com/design/xxx/ComplexApp

Changes:
- Button font-weight: 600 → 700
- Button padding: 12px 24px → 14px 28px
- Card radius: 4px → 12px
- Primary color: #3B82F6 → #2563EB

Instruction:
Update ONLY affected components. Verify no regressions. Run test suite.

Time: 15–30 minutes vs. 2–3 hours of manual updates.

Design.md Maintenance Strategy

Version Numbering

X.Y.Z format:

X = Major rebrand (rare)
Y = New components, color system expansion
Z = Token tweaks, accessibility fixes

Update Triggers

Any color value change
New component introduction
Breakpoint modification
Animation specification update

Record all changes in the Change Log section.

Claude Code Briefing Template

Good:

/code
Figma: https://figma.com/design/abc/MyProject

Design System: Reference above Design.md

Color Tokens:
- Primary: #3B82F6
- Neutral-900: #111827
[... details ...]

Implementation Requirements:
- Next.js 15 + App Router
- Tailwind CSS v4
- TypeScript strict mode
- i18n: next-intl (EN, JA)

Poor (avoid):

/code
Figma: https://figma.com/design/abc/MyProject
Design the components from Figma

(← Missing Design.md, unclear color/padding specs, increases iterations)

What the Docs Don't Tell You — Lessons From Running This for Real

After a few months of leaning on Figma MCP, I ran into quirks no documentation mentions. Here is what I noticed rebuilding the admin screens of my own wallpaper and wellness apps with this exact workflow.

1. Feeding one screen at a time is faster

Hand over an entire Figma file and generation starts drifting once the layer count climbs past a few hundred. On my machine, passing a single screen (roughly 20–40 components) gave stable initial generation in about 20–30 seconds, while dumping ten screens at once made naming wander and cost me over an hour of cleanup. Slice by frame. That was the single biggest win.

2. Convert Design Tokens to Figma Variables first

Feed raw hex values and Claude Code will happily mix #3B82F6 and bg-blue-500 for the same color. Register them as Figma Variables and record token names in Design.md, and roughly 80% of the generated color references lined up on token names. Setting up "change every color in one place" from the start pays off quickly.

3. Scoping updates to the diff cuts iteration dramatically

Ask for "regenerate everything" on a design update and unrelated files get rewritten, eating your regression-checking time. When I listed only the changes and stated "update the affected components only, leave the rest untouched," a single update dropped from 2–3 hours to 15–30 minutes. That "don't touch it" instruction is the same spirit as the spec-quality-drives-speed approach.

4. Accessibility always dips right after generation

Freshly generated code often has weaker contrast ratios and focus rings than Design.md intends. I always slot in one pass to check contrast and keyboard operation immediately after generation. Skip it and the one-off fixes pile up later, making you slower overall.

These habits get far more stable when combined with implementing an LP from a design comp with Claude Code alone and a practical React & Next.js workflow.

Full Workflow Timeline

Day 1: System Design (3.5 hours)

Create/finalize Design.md (2 hours)
Generate 3 design directions via Stitch (1 hour)
Select final direction (30 min)

Day 2: Figma Refinement (4.5 hours)

Refine in Figma Make (animations, typography) (2 hours)
Align layer hierarchy with React design (1.5 hours)
QA: colors, sizes, spacing match Design.md (1 hour)

Day 3: Code Generation (2 hours)

Paste Figma URL into Claude Code (2 min)
Initial generation (30 min)
Review + targeted feedback → regenerate (1 hour)
TypeScript compile check (10 min)

Day 4+: Polish & Launch (4 hours)

Responsive testing, accessibility audit (1 hour)
Content integration (copy, images) (2–3 hours)
Deploy, GA/GSC setup (1 hour)

Total: ~16 hours (vs. ~5–7 days from scratch)

Why This Workflow Scales

Quality assured at each stage: Ideation → Refinement → Implementation
Eliminates 70–80% of code writing: Not design, not creative; just repetitive translation
Maintenance is deterministic: Design.md + Figma + code stay synchronized
Iteration is fast: Feedback loops close in hours, not days

The result is the kind of output that would normally take a small team, shipped by one person.

Your competitive advantage isn't design skill or coding skill—it's the system that bridges them.

If you take one thing away, make it this: pick a single screen, put its tokens into Design.md, and let Claude Code generate it end to end tonight. The bottleneck you remove first is the one you will miss the least.

Thank you for reading this far — I hope it buys back a little of your building time.

Thank You for Reading

Claude Lab is ad-free, supported entirely by members like you. We publish practical guides daily with implementation code, benchmarks, and production-ready patterns. If you've found it useful, we'd love to have you on board.