# 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)

# 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

# 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.

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

// 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

// 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);

// 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')}`);
  }
}

// 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

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

# 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

# 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

// 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

// 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] });

// 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 } }
}];

// 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 } }
}];

// 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;