figma-design-handoff — Claude Code skill: setup and features
The figma-design-handoff Claude Code skill guides Figma-to-code handoff, from design tokens to component details. It comes into play when translating layouts, inspecting Dev Mode, or checking a built UI against a Figma frame.
MIT 136 installs ★ 305 updated 2026-11-14
npx skills add yonatangross/orchestkit --skill figma-design-handoff -a claude-codeWhat figma-design-handoff does
The skill covers turning Figma Variables into W3C tokens, extracting component properties, and mapping Auto Layout to Flexbox or Grid. It also describes visual checks of a production interface against Figma with Applitools. Rules load on demand from the rules/ directory.
Style Dictionary version 5.5.5 or later is used to build CSS variables and a Tailwind theme. The skill does not include a Variables-to-W3C converter; the mapping depends on the collections and modes in the Figma file. Figma access can come through the Dev Mode MCP Server or the REST API. REST requests need a Figma token.
What it helps with
- convert Figma Variables into W3C design tokens
- extract component properties and variants from a design
- map Auto Layout to Flexbox or Grid styles
- compare a production UI with its Figma frame
Example prompts for the agent
- Turn the Variables in my Figma file into W3C tokens.
- Document this Figma component's properties and variants.
- Compare the production UI with this Figma frame using Applitools.
How to install figma-design-handoff
1Skills CLI (Vercel)
npx skills add yonatangross/orchestkit --skill figma-design-handoff -a claude-code2Manually: put the files in place
~/.claude/skills/figma-design-handoff/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/figma-design-handoff/
1Skills CLI (Vercel)
npx skills add yonatangross/orchestkit --skill figma-design-handoff -a codex2Manually: put the files in place
.agents/skills/figma-design-handoff/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add yonatangross/orchestkit --skill figma-design-handoff -a cursor2Manually: put the files in place
.cursor/skills/figma-design-handoff/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install yonatangross/orchestkit src/skills/figma-design-handoff2Manually: put the files in place
.github/skills/figma-design-handoff/SKILL.md1Skills CLI (Vercel)
npx skills add yonatangross/orchestkit --skill figma-design-handoff -a gemini-cli2Platform CLI
gemini skills install https://github.com/yonatangross/orchestkit --path src/skills/figma-design-handoffManually: put the files in place
.devin/skills/figma-design-handoff/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add yonatangross/orchestkit --skill figma-design-handoff -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about figma-design-handoff
How do I install figma-design-handoff in Claude Code?
Run npx skills add yonatangross/orchestkit --skill figma-design-handoff -a claude-code. The skill file is available at ~/.claude/skills/figma-design-handoff/SKILL.md.
What does figma-design-handoff do?
It guides the handoff from Figma to code: extracting tokens and component details, translating Auto Layout into CSS layout styles, and checking a built interface visually.
What does figma-design-handoff need to work?
Token builds use Style Dictionary version 5.5.5 or later. Figma REST API access requires a Figma token; the MCP route requires access to the Figma Dev Mode MCP Server.
Source text
SKILL.md · MIT
---
name: figma-design-handoff
license: MIT
compatibility: "Claude Code 2.1.277+."
description: "Figma-to-code handoff: Variables to design tokens, component specs, Dev Mode, Auto Layout to Flexbox/Grid, Applitools visual regression. Use when converting Figma designs to code, documenting component specs, or comparing production UI against Figma."
user-invocable: false
targets:
- library: "style-dictionary"
version: ">=5.5.5"
metadata:
owner-agent: "frontend-ui-developer"
category: document-asset-creation
figma-mcp-tool-count: 16
version: "1.1.0"
author: "OrchestKit"
complexity: "medium"
tags: "figma, design-handoff, design-to-code, figma-variables, dev-mode, auto-layout, component-specs, visual-regression, applitools, design-tokens"
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.
```jsonc
// .claude/mcp-servers/figma.json — sample config
{
"figma": {
"command": "figma-mcp",
"args": ["--mode=dev"],
"env": { "FIGMA_ACCESS_TOKEN": "${FIGMA_TOKEN}" }
}
}
```
## Quick Start
```bash
# 1. Export Figma Variables (Figma REST API)
curl -s -H "X-Figma-Token: $FIGMA_TOKEN" \
"https://api.figma.com/v1/files/$FILE_KEY/variables/local" \
> tokens/figma-local.json
# 2. Convert that response to W3C Design Tokens. This skill does NOT ship a
# converter — the mapping (variables, modes, aliases, and the $value/$type
# shape) is specified in rules/figma-variables-tokens.md, and the right
# implementation depends on which collections and modes your file uses.
# Earlier revisions of this Quick Start piped into a
# `scripts/figma-to-w3c-tokens.js` that has never existed in this skill.
# Result: tokens/figma-raw.json
# 3. Transform with Style Dictionary
npx style-dictionary build --config sd.config.js
# 4. 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: ... } }
```
```json
// 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}"
}
}
}
}
}
```
```typescript
// 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 │
│ (Variables, │ │ (Inspect, │ │ (W3C DTCG │
│ Auto Layout)│ │ Export) │ │ format) │
└─────────────┘ └──────────────┘ └───────┬───────┘
│
▼
┌─────────────┐ ┌──────────────┐ ┌───────────────┐
│ Visual QA │◀────│ Components │◀────│ Style │
│ (Applitools,│ │ (React + │ │ Dictionary │
│ Chromatic) │ │ Tailwind) │ │ (CSS/Tailwind)│
└─────────────┘ └──────────────┘ └───────────────┘
```
## Rules
Each rule is loaded on-demand from the `rules/` directory:
<!-- load:rules/figma-variables-tokens.md -->
<!-- load:rules/figma-component-specs.md -->
<!-- load:rules/figma-dev-mode.md -->
<!-- load:rules/figma-auto-layout.md -->
<!-- load:rules/figma-visual-regression.md -->
## Auto Layout to CSS Mapping
Quick reference for the most common mappings:
| Figma Auto Layout | CSS Equivalent | Tailwind Class |
|-------------------|---------------|----------------|
| Direction: Horizontal | `flex-direction: row` | `flex-row` |
| Direction: Vertical | `flex-direction: column` | `flex-col` |
| Gap: 16 | `gap: 16px` | `gap-4` |
| Padding: 16 | `padding: 16px` | `p-4` |
| Padding: 16, 24 | `padding: 16px 24px` | `py-4 px-6` |
| Align: Center | `align-items: center` | `items-center` |
| Justify: Space between | `justify-content: space-between` | `justify-between` |
| Fill container | `flex: 1 1 0%` | `flex-1` |
| Hug contents | `width: fit-content` | `w-fit` |
| Fixed width: 200 | `width: 200px` | `w-[200px]` |
| Min width: 100 | `min-width: 100px` | `min-w-[100px]` |
| Max width: 400 | `max-width: 400px` | `max-w-[400px]` |
| Wrap | `flex-wrap: wrap` | `flex-wrap` |
| Absolute position | `position: absolute` | `absolute` |
## Visual QA Loop
```typescript
// Applitools Eyes + Figma Plugin — CI integration
import { Eyes, Target } from '@applitools/eyes-playwright';
const eyes = new Eyes();
await eyes.open(page, 'MyApp', 'Homepage — Figma Comparison');
// Capture full page
await eyes.check('Full Page', Target.window().fully());
// Capture specific component
await eyes.check(
'Hero Section',
Target.region('#hero').ignoreDisplacements()
);
await eyes.close();
```
The Applitools Figma Plugin overlays production screenshots on Figma frames to catch:
- Color mismatches (token not applied or wrong mode)
- Spacing drift (padding/margin deviations)
- Typography inconsistencies (font size, weight, line height)
- Missing states (hover, focus, disabled not implemented)
## Key Decisions
| Decision | Recommendation |
|----------|----------------|
| Token format | W3C Design Tokens Community Group (DTCG) JSON |
| Token pipeline | Figma REST API → Style Dictionary → CSS/Tailwind |
| Color format | OKLCH for perceptually uniform theming |
| Layout mapping | Auto Layout → CSS Flexbox (Grid for 2D layouts) |
| Visual QA tool | Applitools Eyes + Figma Plugin for design-dev diff |
| Spec format | TypeScript interfaces matching Figma component props |
| Mode handling | Figma Variable modes → CSS media queries / class toggles |
## Anti-Patterns (FORBIDDEN)
- **Hardcoded values**: Never hardcode colors, spacing, or typography — always reference tokens
- **Skipping Dev Mode**: Do not eyeball measurements — use Dev Mode for exact values
- **Manual token sync**: Do not manually copy values from Figma — automate with REST API
- **Ignoring modes**: Variables with light/dark modes must map to theme toggles, not separate files
- **Screenshot-only QA**: Visual comparison without structured regression testing misses subtle drift
- **Flat token structure**: Use nested W3C DTCG format, not flat key-value pairs
## References
| Resource | Description |
|----------|-------------|
| [references/figma-to-code-workflow.md](references/figma-to-code-workflow.md) | End-to-end workflow, toolchain options |
| [references/design-dev-communication.md](references/design-dev-communication.md) | PR templates, component status tracking |
| [references/applitools-figma-plugin.md](references/applitools-figma-plugin.md) | Setup, CI integration, comparison config |
## Related Skills
- `ork:design-system-tokens` — W3C token architecture and Style Dictionary transforms
- `ork-extras:ui-components` — shadcn/ui and Radix component patterns
- `ork-extras:accessibility` — WCAG compliance for components extracted from Figma
© OrchestKit · MIT · yonatangross/orchestkit