/figma-design-handoff

name: figma-design-handoff
license: MIT
compatibility: "Claude Code 2.1.220+."
description: Figma-to-code design handoff patterns including Figma Variables to design tokens pipeline, component spec extraction, Dev Mode inspection, Auto Layout to CSS Flexbox/Grid mapping, and visual regression with Applitools. Use when converting Figma designs to code, documenting component specs, setting up design-dev workflows, or comparing production UI against Figma designs.
tags: [figma, design-handoff, design-to-code, figma-variables, dev-mode, auto-layout, component-specs, visual-regression, applitools, design-tokens]
context: fork
agent: frontend-ui-developer
version: 1.1.0
author: OrchestKit
user-invocable: false
disable-model-invocation: true
complexity: medium
persuasion-type: guidance
targets:
  - library: "style-dictionary"
    version: ">=5.3.0"
metadata:
  category: document-asset-creation
  figma-mcp-tool-count: 16
allowed-tools:
  - Read
  - Glob
  - Grep
  - WebFetch
  - WebSearch

Figma Design Handoff

Figma dominates design tooling in 2026, with the majority of product teams using it as their primary design tool. A structured handoff workflow eliminates design drift — the gap between what designers create and what developers build. This skill covers the full pipeline: Figma Variables to design tokens, component spec extraction, Dev Mode inspection, Auto Layout to CSS mapping, and visual regression testing.

Quick Reference

| Rule | File | Impact | When to Use | |------|------|--------|-------------| | Figma Variables & Tokens | `rules/figma-variables-tokens.md` | CRITICAL | Converting Figma Variables to W3C design tokens JSON | | Component Specs | `rules/figma-component-specs.md` | HIGH | Extracting component props, variants, states from Figma | | Dev Mode Inspection | `rules/figma-dev-mode.md` | HIGH | Measurements, spacing, typography, asset export | | Auto Layout → CSS | `rules/figma-auto-layout.md` | HIGH | Mapping Auto Layout to Flexbox/Grid | | Visual Regression | `rules/figma-visual-regression.md` | MEDIUM | Comparing production UI against Figma designs |

**Total: 5 rules across 1 category**

Figma Dev Mode MCP Server (2026 default path)

The Figma Dev Mode MCP Server replaces most manual REST + Dev Mode inspection. Configure it once and any Claude Code session with Figma access can pull design context, tokens, and code mappings directly.

Key tools (16 documented — `developers.figma.com/docs/figma-mcp-server/tools-and-prompts`):

| Tool | Returns | Use for | |------|---------|---------| | `get_design_context` | Component tree + layout + typography + spacing | First call on any Figma node → grounds every other tool | | `get_variable_defs` | Token collections (variables + modes + aliases) | Straight export to W3C DTCG JSON — skip the REST pipeline | | `get_code_connect_map` | Figma node → codebase component mapping | Linking generated code to existing repo components | | `get_screenshot` | PNG of a node or frame | Screenshot for visual diffing / embed in chat | | `search_design_system` | Token/component search across libraries | Finding existing tokens before generating new ones | | `use_figma` *(beta)* | Writes back to the Figma canvas | Code-to-design round-trip (write-to-canvas) | | `generate_figma_design` *(beta)* | Creates a design frame from a prompt | AI-generated design stubs for handoff |

**Install**: Enable in the Figma desktop app under *Preferences → Dev Mode MCP Server*, or use the remote MCP endpoint (no desktop required for read tools). Pair with **Code Connect UI** (GA 2026) to map Figma node IDs → codebase components without manual JSON wiring.

// .claude/mcp-servers/figma.json — sample config
{
  "figma": {
    "command": "figma-mcp",
    "args": ["--mode=dev"],
    "env": { "FIGMA_ACCESS_TOKEN": "${FIGMA_TOKEN}" }
  }
}

Quick Start

# 1. Export Figma Variables → tokens.json (using Figma REST API)
curl -s -H "X-Figma-Token: $FIGMA_TOKEN" \
  "https://api.figma.com/v1/files/$FILE_KEY/variables/local" \
  | node scripts/figma-to-w3c-tokens.js > tokens/figma-raw.json

# 2. Transform with Style Dictionary
npx style-dictionary build --config sd.config.js

# 3. Output: CSS custom properties + Tailwind theme
# tokens/
#   figma-raw.json        ← W3C Design Tokens format
#   css/variables.css     ← --color-primary: oklch(0.65 0.15 250);
#   tailwind/theme.js     ← module.exports = { colors: { primary: ... } }

// W3C Design Tokens Format (DTCG)
{
  "color": {
    "primary": {
      "$type": "color",
      "$value": "{color.blue.600}",
      "$description": "Primary brand color"
    },
    "surface": {
      "$type": "color",
      "$value": "{color.neutral.50}",
      "$extensions": {
        "mode": {
          "dark": "{color.neutral.900}"
        }
      }
    }
  }
}

// Style Dictionary config for Figma Variables
import StyleDictionary from 'style-dictionary';

export default {
  source: ['tokens/figma-raw.json'],
  platforms: {
    css: {
      transformGroup: 'css',
      buildPath: 'tokens/css/',
      files: [{ destination: 'variables.css', format: 'css/variables' }],
    },
    tailwind: {
      transformGroup: 'js',
      buildPath: 'tokens/tailwind/',
      files: [{ destination: 'theme.js', format: 'javascript/module' }],
    },
  },
};

Handoff Workflow

The design-to-code pipeline follows five stages:

1. **Design in Figma** — Designer creates components with Variables, Auto Layout, and proper naming 2. **Extract Specs** — Use Dev Mode to inspect spacing, typography, colors, and export assets 3. **Export Tokens** — Figma Variables → W3C tokens JSON via REST API or plugin 4. **Build Components** — Map Auto Layout to CSS Flexbox/Grid, apply tokens, implement variants 5. **Visual QA** — Compare production screenshots against Figma frames with Applitools

┌─────────────┐     ┌──────────────┐     ┌───────────────┐
│  Figma File  │────▶│  Dev Mode    │────▶│  tokens.json  │
│