claude2figma-design-system-harness

claude2figma Design System Harness

Skill by ara.so — Design Skills collection.

A harness for Claude Code + Figma that enforces Design System compliance in AI-generated designs. Prevents hardcoded values, ensures components stay linked, and binds all visual properties to tokens and styles.

What This Does

When AI writes to Figma without guidance, it creates everything from scratch:

• Hardcoded hex colors instead of color tokens
• Raw spacing values instead of spacing variables
• Components rebuilt from primitives instead of instances

claude2figma fixes this with 4 Claude Code Skills:

1. figma-preflight — 3-step parallel check that loads Token Map + Component Registry
2. component-rules — Library-first lookup, Auto Layout patterns, semantic naming
3. figma-style-binding — Enforces Variable/Style binding + post-write QA verification
4. reference-interpreter — Converts screenshots/references → structured Design Brief

Every design operation follows: search DS → create Instances → bind tokens → verify.

Installation

Prerequisites

# 1. Claude Code installed (CLI, Desktop, or VS Code)
# 2. Figma MCP Server installed and authenticated
npm install -g @anthropic-ai/figma-mcp

# 3. A Figma file with a Design System (local or linked library)

Setup

# Clone the repo
git clone https://github.com/senlindesign/claude2figma.git
cd claude2figma

# Copy skills to your project
cp -r .claude/skills/* /path/to/your-project/.claude/skills/

# Copy settings
cp .claude/settings.json /path/to/your-project/.claude/settings.json

# Copy CLAUDE.md template
cp CLAUDE.md.template /path/to/your-project/CLAUDE.md

Configure CLAUDE.md

# Figma Design Project

- **Figma file:** https://www.figma.com/design/YOUR_FILE_KEY/...
- **Fonts:** [leave blank — auto-detected by preflight]
- **Session goal:** Build login page with email/password fields

## Rules

1. Every visual value must bind to a Style or Variable.
2. Always search connected libraries before building any component from scratch.
3. Never start designing before the Design Brief is confirmed.

Key Skills Structure

Your project should have this structure after installation:

your-project/
├── CLAUDE.md                          # Config: Figma URL, fonts, rules
└── .claude/
    ├── settings.json                  # Permissions + QA Hook
    └── skills/
        ├── figma-preflight/           # Skill 1: Parallel check + Token Map
        │   └── SKILL.md
        ├── component-rules/           # Skill 2: Library-first patterns
        │   └── SKILL.md
        ├── figma-style-binding/       # Skill 3: Token binding + QA
        │   └── SKILL.md
        └── reference-interpreter/     # Skill 4: Reference → Design Brief
            └── SKILL.md

Usage Patterns

Pattern 1: Start Every Session with Preflight

// User says: "let's start" or "run preflight"
// Claude executes figma-preflight skill:

// 1. Parse Figma URL from CLAUDE.md
const fileKey = extractFileKey(CLAUDE_MD_CONTENT);

// 2. Parallel preflight checks
const [mcpStatus, fileAccess, dsAssets] = await Promise.all([
  checkMCPConnection(),
  verifyFilePermissions(fileKey),
  loadDesignSystemAssets(fileKey)
]);

// 3. Build Token Map
const tokenMap = {
  colors: await figma.getLocalVariableCollectionsAsync('COLOR'),
  spacing: await figma.getLocalVariableCollectionsAsync('NUMBER'),
  textStyles: await figma.getLocalTextStylesAsync(),
  effectStyles: await figma.getLocalEffectStylesAsync()
};

// 4. Build Component Registry
const components = await figma.getLocalComponentsAsync();
const componentRegistry = components.map(c => ({
  name: c.name,
  id: c.id,
  variantProperties: c.componentPropertyDefinitions
}));

// Output: ✓ Preflight complete — 47 tokens, 23 components loaded

Pattern 2: Component-First Design

// User says: "Add a primary button"
// Claude executes component-rules + figma-style-binding skills:

// 1. Search Component Registry first
const button = componentRegistry.find(c => 
  c.name.toLowerCase().includes('button') &&
  c.variantProperties?.variant?.includes('primary')
);

if (!button) {
  throw new Error('No Button/Primary in DS — check library or request custom component');
}

// 2. Create Instance (not from scratch)
const instance = figma.createInstance();
instance.mainComponent = figma.getNodeById(button.id);

// 3. Set variant properties (validated against componentPropertyDefinitions)
instance.setProperties({ variant: 'primary', size: 'medium' });

// 4. Bind any overrides to tokens
if (instance.children[0].fills) {
  const primaryColorVar = tokenMap.colors.find(v => v.name === 'primary');
  instance.children[0].fills = [{
    type: 'SOLID',
    color: { r: 0, g: 0, b: 0 }, // placeholder
    boundVariables: { color: { id: primaryColorVar.id } }
  }];
}

// 5. Auto-verify after write
await verifyTokenBindings(instance);

Pattern 3: Token Binding Enforcement

// figma-style-binding skill enforces this on EVERY visual property:

// ✅ CORRECT: Bound to variable
node.fills = [{
  type: 'SOLID',
  boundVariables: { color: { id: tokenMap.colors.find(v => v.name === 'surface').id } }
}];

// ❌ WRONG: Hardcoded hex value
node.fills = [{ type: 'SOLID', color: { r: 1, g: 1, b: 1 } }]; // REJECTED by QA

// Post-write QA verification:
async function verifyTokenBindings(node) {
  const violations = [];
  
  if (node.fills && !node.fills[0]?.boundVariables) {
    violations.push(`${node.name}: fills not bound to token`);
  }
  
  if (node.textStyleId === '') {
    violations.push(`${node.name}: no text style bound`);
  }
  
  if (violations.length > 0) {
    throw new Error(`Token binding violations:\n${violations.join('\n')}`);
  }
}

Pattern 4: Reference-Driven Design

// User shares screenshot and says: "Build this"
// Claude executes reference-interpreter skill:

// 1. Analyze reference → structured Design Brief
const designBrief = {
  layout: 'Two-column grid, 16px gap',
  components: [
    { type: 'Header', contains: ['Logo', 'Navigation/Horizontal', 'Button/Primary'] },
    { type: 'Hero Section', contains: ['Heading/H1', 'Body/Large', 'Button Group'] }
  ],
  tokens: {
    colors: ['primary', 'surface', 'on-surface'],
    spacing: ['space-4', 'space-8', 'space-16'],
    typography: ['heading-1', 'body-large']
  }
};

// 2. Output Design Brief to user for confirmation
// 3. User says "looks good"
// 4. Claude builds section by section, following component-rules + style-binding

Configuration

settings.json — QA Hook

{
  "mcpServers": {
    "figma": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/figma-mcp"]
    }
  },
  "qaHooks": {
    "postWrite": "verifyTokenBindings"
  },
  "permissions": {
    "figma": ["read", "write"]
  }
}

CLAUDE.md — Session Rules

# Figma Design Project

- **Figma file:** https://www.figma.com/design/ABC123/...
- **Session goal:** Build dashboard with data table and filters

## Rules

1. Run preflight before starting design work
2. Every component must be an Instance, not built from scratch
3. Every color, font, spacing must bind to a token
4. Take screenshot after each major section for verification

Real-World Workflow

# Terminal in your project
$ claude-code chat

User: "let's start"

Claude:
  ✓ MCP connection verified
  ✓ File permissions confirmed
  ✓ Design System loaded: 47 tokens, 23 components
  
  Ready to design. What are we building?

User: "Build a login form with email, password, and a submit button"

Claude:
  [Searches Component Registry]
  Found: Form/Vertical, Input/Email, Input/Password, Button/Primary
  
  [Creates Instances + binds tokens]
  - Form container: padding bound to space-6
  - Input fields: text style bound to body-medium
  - Submit button: fills bound to primary color token
  
  [Takes screenshot]
  ✓ Verification passed — all tokens bound
  
  Screenshot: [shows form in Figma]

User: "Add a forgot password link below the form"

Claude:
  [Searches for Link component]
  Not found in registry — creating text node with hyperlink style
  
  [Binds text style + color token]
  ✓ Verification passed

Troubleshooting

Error: "No components found in registry"

// Cause: Working in a new file without linked library
// Fix: Link your DS library in Figma first

// In Figma: Assets → Libraries → Enable your DS library
// Then re-run preflight to rebuild Component Registry

Error: "Invalid variant property value"

// Cause: setProperties() called with invalid variant value
// Fix: Read componentPropertyDefinitions first

const component = figma.getNodeById(componentId);
const validVariants = component.componentPropertyDefinitions.variant.variantOptions;

// Only use values from validVariants array
instance.setProperties({ variant: validVariants[0] });

Error: "Token binding verification failed"

// Cause: A property was set with a raw value instead of binding to token
// Fix: Always use boundVariables

// ❌ WRONG
node.fills = [{ type: 'SOLID', color: { r: 0.2, g: 0.4, b: 0.8 } }];

// ✅ CORRECT
const token = tokenMap.colors.find(v => v.name === 'primary');
node.fills = [{
  type: 'SOLID',
  boundVariables: { color: { id: token.id } }
}];

Working with Library Variables (Can't See Them Locally)

// Limitation: getLocalVariablesAsync() only returns file-local variables
// Workaround 1: Instances inherit bindings automatically (no action needed)

// Workaround 2: Import library variable for new frames
const libraryVarKey = 'VariableID:123:456'; // from library file
const importedVar = await figma.variables.importVariableByKeyAsync(libraryVarKey);

frame.fills = [{
  type: 'SOLID',
  boundVariables: { color: { id: importedVar.id } }
}];

Best Practices

1. Always run preflight at session start — loads Token Map + Component Registry
2. Search before creating — check componentRegistry before building any UI element
3. Bind, don't hardcode — every visual property must reference a token
4. Verify after write — QA hook catches token binding violations automatically
5. Confirm Design Brief — when working from reference, output structured brief before building

API Reference

Key Figma MCP Methods

// File access
const file = await figma.getFileAsync(fileKey);

// Design System assets
const variables = await figma.getLocalVariableCollectionsAsync();
const textStyles = await figma.getLocalTextStylesAsync();
const components = await figma.getLocalComponentsAsync();

// Instance creation
const instance = figma.createInstance();
instance.mainComponent = masterComponent;
instance.setProperties({ variant: 'primary' });

// Token binding
node.fills = [{
  type: 'SOLID',
  boundVariables: { color: { id: variableId } }
}];
node.textStyleId = textStyle.id;

// Verification
const bindings = node.boundVariables;
const hasColorBinding = bindings?.fills?.[0]?.color !== undefined;

When to Use This

✅ Good For	❌ Not For
Building pages from existing DS	Creating a DS from scratch
Natural language → Figma design	Pixel-perfect illustration
Ensuring 100% token compliance	FigJam / whiteboard work
Working in DS file or with linked library	Free-form design without DS

---

License: MIT
Repository: https://github.com/senlindesign/claude2figma
Figma MCP Server: https://www.npmjs.com/package/@anthropic-ai/figma-mcp