Purpose: Define the optimal Figma file structure so Claude Code can read designs efficiently and generate accurate code. A well-structured Figma file is to Claude Code what well-written HTML is to a browser.

Why Figma Structure Matters

When Claude Code reads a Figma file through the MCP integration, it receives a structured data tree — node names, auto-layout properties, spacing values, color fills, text styles, component hierarchy, and variant properties. The cleaner and more semantic that tree is, the better the code output.

Generic names like "Frame 47" and deeply nested groups with no auto-layout are the equivalent of div soup — technically readable, but the AI has to guess at intent.

The Two-Layer System: Tokens + Components

Layer 1: Design Tokens (Figma Variables)

This is the theming system — values that change per client. Set up as Figma Variables organized into collections.

Color Tokens

• Primitives — Raw palette (blue-500, gray-100, etc.)
• Semantics — What colors mean (color-primary, color-surface, color-text-primary, color-border, color-accent)
• Components reference the semantic layer. New client = swap primitive values, semantics cascade automatically.

Why this matters for Claude Code: When it sees a button background uses color-primary rather than raw hex #FF6B00, it maps directly to var(--color-primary) in CSS. Named variables eliminate guessing.

Spacing Tokens

Consistent scale: spacing-xs through spacing-3xl, mapped to pixel values (4, 8, 12, 16, 24, 32, 48, 64). Maps directly to CSS custom properties.

Typography Tokens

• Font family (font-heading, font-body)
• Size scale (size-xs through size-3xl)
• Weight (weight-regular, weight-medium, weight-bold)