Figma Design System to LLM Integration Guide

Without tokens:
button-color: #3B82F6
link-color: #3B82F6
badge-color: #3B82F6
(Change requires updating 500+ instances)

With tokens:
token: primary-blue = #3B82F6
button-color: primary-blue
link-color: primary-blue
badge-color: primary-blue
(Change token once, updates everywhere)

Layer 1: PRIMITIVES (Raw values)
├── What: Actual colors (#3B82F6), actual numbers (16px)
├── Who edits: Design system managers only
├── How often: Rarely (maybe once a year for rebrand)
└── Example: primitive/color/blue/500 = #3B82F6

        ↓ Referenced by ↓

Layer 2: SEMANTIC (Purpose-based)
├── What: References to primitives with meaningful names
├── Who edits: Design system managers
├── How often: Occasionally (quarterly adjustments)
└── Example: semantic/text/primary = primitive/color/gray/900

        ↓ Referenced by ↓

Layer 3: COMPONENT (Component-specific)
├── What: References to semantic tokens for specific components
├── Who edits: Component designers
├── How often: Frequently (when building/updating components)
└── Example: component/button/text/default = semantic/text/inverse

Atoms (Basic building blocks)
├── Button
├── Input
├── Icon
├── Label
├── Badge
└── Avatar

Molecules (Simple combinations)
├── Input with Label
├── Button Group
├── Search Field
└── Select Dropdown

Organisms (Complex patterns)
├── Navigation Bar
├── Form Section
├── Card with Actions
└── Data Table

{
  "primitive": {
    "color": {
      "blue": {
        "50": {
          "$type": "color",
          "$value": "#eff6ff"
        },
        "500": {
          "$type": "color",
          "$value": "#3b82f6"
        }
      }
    }
  },
  "semantic": {
    "background": {
      "primary": {
        "$type": "color",
        "$value": "{primitive.color.gray.50}"
      }
    }
  }
}

❌ Error 1: Broken Reference
{
  "$value": "{primitive.color.blue.500}"
}
// But primitive.color.blue.500 doesn't exist

✓ Fix: Create the missing token or update the reference

❌ Error 2: Circular Reference
semantic.text.primary → semantic.text.body → semantic.text.primary

✓ Fix: Break the circle by referencing primitives

❌ Error 3: Wrong Type
{
  "$type": "dimension",
  "$value": "#3B82F6"  // This is a color, not a dimension!
}

✓ Fix: Correct the $type to "color"

URL: https://mcp.figma.com/mcp
Benefits: Always up-to-date, no local installation needed
Transport: Streamable HTTP with SSE
Supported: VS Code, Cursor, Windsurf, Claude Code CLI

URL: http://127.0.0.1:3845/mcp
Benefits: Works offline, faster responses
Requirement: Figma Desktop app must be running
Transport: Streamable HTTP with SSE
Supported: VS Code, Cursor, Windsurf, Claude Code CLI

claude mcp add --transport http figma https://mcp.figma.com/mcp

{
  "mcp.servers": {
    "figma-remote": {
      "type": "streamableHttp",
      "url": "https://mcp.figma.com/mcp"
    }
  }
}

{
  "mcpServers": {
    "figma": {
      "url": "https://mcp.figma.com/mcp"
    }
  }
}

// Generated server structure:
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

// Exposes resources like:
// - design-system://context (overview, brand, principles)
// - design-system://tokens (all design tokens)
// - design-system://component-template (React boilerplate)
// - design-system://accessibility (WCAG guidelines)

// Provides tools like:
// - generate_component (create new components)
// - generate_design_tokens (export to CSS/Tailwind/TypeScript)
// - audit_accessibility (check WCAG compliance)
// - add_component_variant (extend existing components)

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "my-design-system": {
      "command": "node",
      "args": [
        "/absolute/path/to/your-mcp-server/dist/index.js"
      ],
      "env": {}
    }
  }
}

Example workflow:
1. "Pull the button component from Figma file xyz"
   → Figma MCP server fetches the design

2. "Generate React code following HypnoLabs design system patterns"
   → Custom MCP server provides templates and guidelines

3. LLM combines both → Generates code matching Figma design + your patterns

:root {
  /* Primitive Colors */
  --color-blue-50: #eff6ff;
  --color-blue-500: #3b82f6;
  --color-blue-900: #1e3a8a;

  /* Semantic Colors */
  --background-primary: var(--color-gray-50);
  --text-primary: var(--color-gray-900);

  /* Component Tokens */
  --button-bg-primary: var(--color-blue-500);
  --button-text-primary: var(--color-white);

  /* Spacing Scale */
  --spacing-xs: 0.25rem; /* 4px */
  --spacing-sm: 0.5rem;  /* 8px */
  --spacing-md: 1rem;    /* 16px */
}

/* Dark Mode */
[data-theme="dark"] {
  --background-primary: var(--color-gray-900);
  --text-primary: var(--color-gray-50);
}

You are a design system expert helping to structure and implement a design system.

DESIGN SYSTEM CONTEXT:
- Name: [System Name]
- Version: [Version]
- Platforms: [Web, iOS, Android]

TOKEN HIERARCHY:
1. Primitive tokens: Raw values (colors, sizes)
2. Semantic tokens: Purpose-based aliases
3. Component tokens: Component-specific values

RULES:
1. Always use tokens, never hardcode values
2. Reference semantic tokens, not primitive ones
3. Maintain 4.5:1 contrast for normal text
4. Touch targets must be at least 44x44px

your-project/
├── design-tokens/
│   ├── figma-export/           # Raw export from Figma
│   │   └── tokens.json         # DTCG JSON from Figma Variables
│   ├── processed/              # Transformed tokens
│   │   ├── tokens.css          # CSS custom properties
│   │   ├── tokens.scss         # Sass variables
│   │   ├── tokens.ts           # TypeScript constants
│   │   └── tailwind.config.js  # Tailwind theme extension
│   └── README.md               # Documentation on token usage
├── src/
└── package.json

# Step 1: Export from Figma
# File → Variables → Export variables → Save as design-tokens/figma-export/tokens.json

# Step 2: Transform tokens
npm run tokens:transform

# Step 3: Review changes
git diff design-tokens/

# Step 4: Commit with descriptive message
git add design-tokens/
git commit -m "design-tokens: update primary blue shade (500 → 600)

- Adjusted primary blue from #3b82f6 to #2563eb
- Improves contrast ratio from 4.2:1 to 5.1:1 (WCAG AA compliant)
- Affects: buttons, links, focus states"

# Step 5: Create pull request for review
git push origin feature/update-primary-color
gh pr create --title "Update primary color for better accessibility"

// package.json
{
  "name": "@your-company/design-tokens",
  "version": "2.1.3",
  "description": "Design tokens for Your Company design system",
  "main": "processed/tokens.js",
  "exports": {
    "./css": "./processed/tokens.css",
    "./scss": "./processed/tokens.scss",
    "./tailwind": "./processed/tailwind.config.js"
  }
}

# Changelog

## [2.1.3] - 2025-11-26

### Changed
- `primitive.color.blue.500`: #3b82f6 → #2563eb (improved contrast)
- `semantic.text.link`: Now uses blue.600 instead of blue.500

### Impact
- Affects all link colors and primary buttons
- WCAG AA compliant (5.1:1 contrast on white)

## [2.1.2] - 2025-11-20

### Added
- `semantic.border.focus`: New token for focus outlines
- `component.input.border.focus`: Uses semantic.border.focus

### Fixed
- `semantic.background.danger`: Fixed incorrect reference to red.100

{
  "scripts": {
    "tokens:export": "# Manual: Export from Figma to design-tokens/figma-export/tokens.json",
    "tokens:transform": "node scripts/transform-tokens.js",
    "tokens:validate": "node scripts/validate-tokens.js",
    "tokens:sync": "npm run tokens:validate && npm run tokens:transform",
    "sync:components": "figma-code-connect sync",
    "sync:all": "npm run tokens:sync && npm run sync:components"
  }
}

// scripts/sync-figma-tokens.js
import { figmaAPI } from './figma-api.js';

async function syncTokens() {
  // 1. Fetch variables from Figma API
  const variables = await figmaAPI.getVariables(fileId);

  // 2. Transform to DTCG format
  const tokens = transformToD TCG(variables);

  // 3. Write to file
  await fs.writeFile('design-tokens/figma-export/tokens.json',
                     JSON.stringify(tokens, null, 2));

  // 4. Run transformation
  await exec('npm run tokens:transform');

  console.log('Tokens synced successfully!');
}

syncTokens();

# .github/workflows/sync-tokens.yml
name: Sync Design Tokens

on:
  schedule:
    - cron: '0 9 * * 1' # Every Monday at 9am
  workflow_dispatch: # Manual trigger

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Sync tokens from Figma
        run: npm run sync:figma
        env:
          FIGMA_TOKEN: ${{ secrets.FIGMA_TOKEN }}
      - name: Create PR if changes detected
        run: |
          if [[ `git status --porcelain` ]]; then
            gh pr create --title "chore: sync design tokens from Figma" \
                        --body "Automated token sync"
          fi

// style-dictionary.config.js
module.exports = {
  source: ['tokens/**/*.json'],
  platforms: {
    figma: {
      transformGroup: 'js',
      buildPath: 'build/figma/',
      files: [{
        destination: 'tokens.json',
        format: 'json/nested',
        filter: (token) => {
          // Only export color and dimension tokens
          return ['color', 'dimension', 'fontFamily'].includes(token.type);
        }
      }]
    }
  }
};

// Then transform to DTCG format for Figma
npm run tokens:build
node scripts/upload-to-figma.js

// scripts/upload-to-figma.js
const fs = require('fs');
const fetch = require('node-fetch');

const FIGMA_TOKEN = process.env.FIGMA_TOKEN;
const FILE_KEY = process.env.FIGMA_FILE_KEY;

async function uploadTokensToFigma() {
  const tokens = JSON.parse(fs.readFileSync('build/figma/tokens.json', 'utf8'));

  // Transform tokens to Figma Variables format
  const variables = Object.entries(tokens.color).map(([name, value]) => ({
    name: `color/${name}`,
    resolvedType: 'COLOR',
    valuesByMode: {
      [modeId]: rgbaToFigmaColor(value)
    }
  }));

  // POST to Figma API
  const response = await fetch(
    `https://api.figma.com/v1/files/${FILE_KEY}/variables`,
    {
      method: 'POST',
      headers: {
        'X-Figma-Token': FIGMA_TOKEN,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ variables })
    }
  );

  console.log('Tokens uploaded:', await response.json());
}

uploadTokensToFigma();

PROMPT: Token Structure Audit

I have the following design token structure exported from my codebase:

[Paste tokens.json here]

Please analyze:
1. Are token names semantic and consistent?
2. Do I have proper primitive → semantic → component hierarchy?
3. Are there any missing token types I should add before importing to Figma?
4. Are color values using accessible contrast ratios?
5. Suggest improvements for Figma Variable organization (collections, modes)

Format your response as:
- Issues Found: [list]
- Recommendations: [list]
- Suggested Figma Collections: [list]

// scripts/extract-colors.js
const fs = require('fs');
const glob = require('glob');

// Regex patterns for common color formats
const colorPatterns = [
  /#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})/g,              // Hex
  /rgba?\([^)]+\)/g,                                // RGB/RGBA
  /hsl\([^)]+\)/g,                                  // HSL
];

const colorInventory = new Map();

// Scan all CSS/JS/JSX files
glob.sync('src/**/*.{css,scss,js,jsx,tsx}').forEach(file => {
  const content = fs.readFileSync(file, 'utf8');

  colorPatterns.forEach(pattern => {
    const matches = content.match(pattern) || [];
    matches.forEach(color => {
      const normalized = normalizeColor(color);
      colorInventory.set(
        normalized,
        (colorInventory.get(normalized) || 0) + 1
      );
    });
  });
});

// Sort by frequency
const sortedColors = [...colorInventory.entries()]
  .sort((a, b) => b[1] - a[1])
  .map(([color, count]) => ({ color, count }));

fs.writeFileSync(
  'design-audit/colors.json',
  JSON.stringify(sortedColors, null, 2)
);

console.log(`Found ${sortedColors.length} unique colors`);

PROMPT: Design Pattern Extraction

I need to extract an implicit design system from an existing React codebase.

Here are the CSS files and component files:

[Attach or paste key style files]

Please analyze and:

1. **Color Inventory:**
   - List all unique colors used
   - Group similar colors (e.g., shades of blue)
   - Suggest semantic naming (primary, secondary, accent, etc.)
   - Recommend which to keep vs. consolidate

2. **Spacing Patterns:**
   - Identify all margin/padding values used
   - Suggest a consistent spacing scale (4px, 8px, 16px, etc.)
   - Map existing values to suggested scale

3. **Typography:**
   - List font families, sizes, weights, line heights
   - Suggest a type scale and hierarchy

4. **Shadows & Effects:**
   - Extract box-shadow values
   - Suggest elevation scale (sm, md, lg, xl)

5. **Output Format:**
   - Provide DTCG JSON format suitable for importing to Figma
   - Include collections structure for Figma Variables

Example output format:
```json
{
  "color": {
    "primitive": {
      "blue": {
        "500": { "value": "#3b82f6", "type": "color" }
      }
    },
    "semantic": {
      "primary": { "value": "{color.primitive.blue.500}", "type": "color" }
    }
  }
}
```

# Button Component Documentation

## React Implementation
```tsx
<Button
  variant="primary" | "secondary" | "ghost"
  size="sm" | "md" | "lg"
  disabled={boolean}
  leftIcon={ReactNode}
  rightIcon={ReactNode}
>
  Button Text
</Button>
```

## Figma Recreation Guidelines

1. **Create Component Set:**
   - Name: "Button"
   - Variants: variant, size, state

2. **Variant Properties:**
   - variant: primary, secondary, ghost
   - size: sm (32px), md (40px), lg (48px)
   - state: default, hover, active, disabled

3. **Tokens to Use:**
   - Background: {button.background.[variant]}
   - Text: {button.text.[variant]}
   - Border: {button.border.[variant]}
   - Padding horizontal: {button.padding.x.[size]}
   - Padding vertical: {button.padding.y.[size]}

4. **States:**
   - Hover: Reduce opacity to 90%
   - Active: Darken background by 10%
   - Disabled: 50% opacity, cursor not-allowed

PROMPT: Generate Figma Component Spec

I have the following React component:

[Paste component code]

Please generate a detailed Figma component specification including:

1. **Component Properties:**
   - Map React props to Figma component properties
   - Define variant sets (what should be variants vs. separate components)
   - Specify property types (variant, boolean, instance swap, text)

2. **Visual Specifications:**
   - Dimensions for each size variant
   - Spacing (padding, gap)
   - Typography settings
   - Color tokens to use
   - Border radius, shadows, etc.

3. **Interactive States:**
   - Default, hover, active, focus, disabled states
   - Specify visual changes for each state

4. **Component Hierarchy:**
   - Break down nested component structure
   - Define Auto Layout settings (direction, spacing, alignment)

5. **Design Tokens Reference:**
   - List which design tokens should be used
   - Create token mapping table

Format as a structured Figma component creation guide.

# Bidirectional Sync Architecture

┌─────────────────────────────────────────────────────────────┐
│                         Git Repository                      │
│                                                             │
│  ┌─────────────────┐              ┌──────────────────┐    │
│  │ design-tokens/  │              │ figma-sync/      │    │
│  │   - primitive/  │◄────sync────►│   - last-sync/   │    │
│  │   - semantic/   │              │   - conflicts/   │    │
│  │   - component/  │              └──────────────────┘    │
│  └─────────────────┘                                       │
└──────────▲──────────────────────────────────▼──────────────┘
           │                                  │
     [Figma Export]                    [Figma Import]
           │                                  │
    ┌──────┴──────────────────────────────────┴──────┐
    │              Figma File                        │
    │  Design Variables → Code Tokens (Export)       │
    │  Code Tokens → Design Variables (Import)       │
    └───────────────────────────────────────────────┘

**Workflow:**
1. Changes in Figma trigger webhook → export tokens → PR
2. Changes in code → transform tokens → upload to Figma → notify team
3. Conflicts → manual review → resolve → sync

# .github/workflows/design-tokens-sync.yml
name: Design Tokens Bidirectional Sync

on:
  push:
    paths:
      - 'design-tokens/**'
  repository_dispatch:
    types: [figma-webhook]

jobs:
  sync-to-figma:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Transform tokens
        run: npm run tokens:build
      - name: Upload to Figma
        run: node scripts/upload-to-figma.js
        env:
          FIGMA_TOKEN: ${{ secrets.FIGMA_TOKEN }}
      - name: Post Slack notification
        run: |
          curl -X POST ${{ secrets.SLACK_WEBHOOK }} \
            -d '{"text":"Design tokens synced to Figma ✅"}'

  sync-from-figma:
    if: github.event_name == 'repository_dispatch'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Export from Figma
        run: node scripts/export-from-figma.js
        env:
          FIGMA_TOKEN: ${{ secrets.FIGMA_TOKEN }}
      - name: Check for conflicts
        id: conflict-check
        run: node scripts/check-conflicts.js
      - name: Create PR or Auto-merge
        run: |
          if [ "${{ steps.conflict-check.outputs.has-conflicts }}" == "true" ]; then
            gh pr create --title "🔀 Figma sync (conflicts)" \
                        --body "Conflicts detected - manual review required"
          else
            git commit -am "chore: sync from Figma"
            git push
          fi

PROMPT: Design Token Conflict Resolution

I have conflicting changes to the same design token:

**Figma Version (designer changed):**
```json
{
  "color/primary": {
    "value": "#2563eb",
    "type": "color",
    "description": "Updated to meet WCAG AA contrast"
  }
}
```

**Code Version (engineer changed):**
```json
{
  "color/primary": {
    "value": "#3b82f6",
    "type": "color",
    "description": "Matches brand guidelines v2.1"
  }
}
```

**Context:**
- Last sync was 3 days ago
- Figma change: contrast accessibility fix
- Code change: brand update

Please:
1. Analyze the conflict reason
2. Recommend which version to keep (or if we need a new value)
3. Suggest communication to team
4. Provide updated token with combined context

Consider:
- Accessibility requirements (WCAG AA)
- Brand consistency
- Breaking changes to existing components
- User impact

// 1. Create Variables (bulk)
POST https://api.figma.com/v1/files/{file_key}/variables/batch

{
  "variableCollections": [{
    "name": "Primitives",
    "modes": [{ "name": "Light" }, { "name": "Dark" }]
  }],
  "variables": [{
    "name": "color/blue/500",
    "resolvedType": "COLOR",
    "variableCollectionId": "{collection_id}",
    "valuesByMode": {
      "{mode_id}": { r: 0.231, g: 0.51, b: 0.965, a: 1 }
    }
  }]
}

// 2. Update Existing Variables
PUT https://api.figma.com/v1/files/{file_key}/variables/{variable_id}

{
  "valuesByMode": {
    "{mode_id}": { r: 0.145, g: 0.227, b: 0.925, a: 1 }
  }
}

// 3. Get All Variables (for sync comparison)
GET https://api.figma.com/v1/files/{file_key}/variables/local

// upload-tokens-to-figma.ts
import fs from 'fs';

interface Token {
  value: string;
  type: 'color' | 'dimension' | 'fontFamily';
  description?: string;
}

interface TokenCollection {
  [category: string]: {
    [token: string]: Token;
  };
}

async function uploadTokensToFigma(
  tokens: TokenCollection,
  fileKey: string,
  accessToken: string
) {
  const baseUrl = 'https://api.figma.com/v1';

  // Step 1: Get or create Variable Collection
  const collectionsRes = await fetch(
    `${baseUrl}/files/${fileKey}/variables/local`,
    { headers: { 'X-Figma-Token': accessToken } }
  );
  const { meta } = await collectionsRes.json();

  let collectionId = meta.variableCollections.find(
    (c: any) => c.name === 'Design Tokens'
  )?.id;

  if (!collectionId) {
    // Create collection
    const createRes = await fetch(
      `${baseUrl}/files/${fileKey}/variables/batch`,
      {
        method: 'POST',
        headers: {
          'X-Figma-Token': accessToken,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          variableCollections: [{
            name: 'Design Tokens',
            modes: [{ name: 'Light' }]
          }]
        })
      }
    );
    const created = await createRes.json();
    collectionId = created.variableCollections[0].id;
  }

  // Step 2: Transform tokens to Figma format
  const variables = [];
  const modeId = meta.variableCollections
    .find((c: any) => c.id === collectionId)
    .modes[0].modeId;

  for (const [category, categoryTokens] of Object.entries(tokens)) {
    for (const [name, token] of Object.entries(categoryTokens)) {
      variables.push({
        name: `${category}/${name}`,
        resolvedType: mapTypeToFigma(token.type),
        variableCollectionId: collectionId,
        valuesByMode: {
          [modeId]: transformValue(token.value, token.type)
        },
        description: token.description || ''
      });
    }
  }

  // Step 3: Upload in batches (Figma has rate limits)
  const BATCH_SIZE = 50;
  for (let i = 0; i < variables.length; i += BATCH_SIZE) {
    const batch = variables.slice(i, i + BATCH_SIZE);

    await fetch(`${baseUrl}/files/${fileKey}/variables/batch`, {
      method: 'POST',
      headers: {
        'X-Figma-Token': accessToken,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ variables: batch })
    });

    console.log(`Uploaded batch ${i / BATCH_SIZE + 1}`);

    // Rate limit: wait 1 second between batches
    await new Promise(resolve => setTimeout(resolve, 1000));
  }

  console.log('✅ All tokens uploaded to Figma');
}

function mapTypeToFigma(type: string): string {
  const mapping: Record<string, string> = {
    'color': 'COLOR',
    'dimension': 'FLOAT',
    'fontFamily': 'STRING'
  };
  return mapping[type] || 'STRING';
}

function transformValue(value: string, type: string): any {
  if (type === 'color') {
    // Convert hex to RGBA object
    const hex = value.replace('#', '');
    const r = parseInt(hex.substr(0, 2), 16) / 255;
    const g = parseInt(hex.substr(2, 2), 16) / 255;
    const b = parseInt(hex.substr(4, 2), 16) / 255;
    return { r, g, b, a: 1 };
  }

  if (type === 'dimension') {
    // Convert rem/px to number
    return parseFloat(value);
  }

  return value;
}

// Usage
const tokens = JSON.parse(
  fs.readFileSync('design-tokens/tokens.json', 'utf8')
);

uploadTokensToFigma(
  tokens,
  process.env.FIGMA_FILE_KEY!,
  process.env.FIGMA_TOKEN!
);

// Example MCP server tools for design system analysis

{
  "tools": [
    {
      "name": "extract_design_tokens",
      "description": "Scan codebase for implicit design tokens",
      "inputSchema": {
        "type": "object",
        "properties": {
          "directory": {
            "type": "string",
            "description": "Root directory to scan"
          },
          "tokenTypes": {
            "type": "array",
            "items": { "enum": ["color", "spacing", "typography", "shadow"] }
          }
        }
      }
    },
    {
      "name": "analyze_component_props",
      "description": "Extract component API from TypeScript definitions",
      "inputSchema": {
        "type": "object",
        "properties": {
          "componentPath": {
            "type": "string",
            "description": "Path to component file"
          }
        }
      }
    },
    {
      "name": "upload_tokens_to_figma",
      "description": "Upload extracted tokens to Figma Variables",
      "inputSchema": {
        "type": "object",
        "properties": {
          "tokens": {
            "type": "object",
            "description": "DTCG formatted tokens"
          },
          "figmaFileKey": { "type": "string" }
        }
      }
    }
  ]
}

PROMPT: Code to Figma Workflow

Please analyze my React component library and create a Figma design system:

1. Use extract_design_tokens to scan ./src/components for colors, spacing, typography
2. Analyze the extracted tokens and normalize similar values
3. Create a proper token hierarchy (primitive → semantic → component)
4. Use analyze_component_props on key components (Button, Input, Card)
5. Generate Figma component specs for each component
6. Use upload_tokens_to_figma to push the structured tokens to Figma file: {file_key}

Provide a summary report of:
- How many tokens were extracted and consolidated
- Which components were analyzed
- Recommendations for design system improvements

Error in Figma:
semantic/text/primary → {primitive.color.gray.900}
❌ Shows "Unresolved" badge

Common causes:
1. Typo in reference path
2. Referenced token doesn't exist
3. Referenced token is in different collection
4. Circular reference loop

Common issues:
❌ Missing closing braces
❌ Trailing commas
❌ Invalid escape characters in token names
❌ Special characters in values

Possible causes:
1. Color space mismatch (sRGB vs Display P3)
2. Gamma correction differences
3. Browser color profile settings
4. Monitor calibration differences
5. Dark mode/light mode context

Error messages:
"Failed to connect to MCP server"
"Connection timeout"
"Server not responding"

Example bad output:
// LLM hardcodes colors instead of using tokens
const Button = () => (
  <button style={{ background: '#3B82F6' }}>  // ❌ Hardcoded
    Click me
  </button>
)

// Should be:
const Button = () => (
  <button className="bg-primary">  // ✓ Uses token
    Click me
  </button>
)

Signs of token bloat:
• 500+ tokens in your system
• Multiple similar tokens (blue-light, blue-lighter, blue-lightest, etc.)
• Tokens used only once
• Overlapping semantic tokens

:root {
  /* Map your tokens to shadcn variables */
  --primary: 217 91% 60%;        /* Your brand blue in HSL */
  --background: 210 20% 98%;     /* Your background */
  --radius: 0.75rem;             /* Your border radius */
}

.dark {
  --primary: 217 91% 60%;
  --background: 222 47% 11%;
}

// Example with Chromatic or Percy
import { render } from '@testing-library/react';
import { Button } from '@/components/ui/button';

describe('Button Visual Tests', () => {
  it('matches snapshot', () => {
    const { container } = render(
      <>
        <Button variant="primary">Primary</Button>
        <Button variant="secondary">Secondary</Button>
        <Button variant="ghost">Ghost</Button>
        <Button variant="primary" disabled>Disabled</Button>
      </>
    );
    expect(container).toMatchSnapshot();
  });
});

// Using jest-axe and Testing Library
import { render } from '@testing-library/react';
import { axe, toHaveNoViolations } from 'jest-axe';
import { Button } from '@/components/ui/button';

expect.extend(toHaveNoViolations);

describe('Button Accessibility', () => {
  it('should not have accessibility violations', async () => {
    const { container } = render(
      <Button>Click me</Button>
    );
    const results = await axe(container);
    expect(results).toHaveNoViolations();
  });

  it('has proper ARIA attributes', () => {
    const { getByRole } = render(<Button>Submit</Button>);
    const button = getByRole('button', { name: 'Submit' });
    expect(button).toBeInTheDocument();
  });
});

// Check contrast ratios for all color combinations
import { getContrastRatio } from '@/lib/color-utils';

describe('Token Contrast Tests', () => {
  it('primary text on white meets WCAG AA', () => {
    const ratio = getContrastRatio('#1F2937', '#FFFFFF');
    expect(ratio).toBeGreaterThanOrEqual(4.5); // WCAG AA
  });

  it('primary button has sufficient contrast', () => {
    const bgColor = '#3B82F6'; // semantic.action.primary
    const textColor = '#FFFFFF'; // semantic.text.inverse
    const ratio = getContrastRatio(bgColor, textColor);
    expect(ratio).toBeGreaterThanOrEqual(4.5);
  });
});

import { render, screen, fireEvent } from '@testing-library/react';
import { Button } from '@/components/ui/button';

describe('Button Component', () => {
  it('renders with correct variant classes', () => {
    render(<Button variant="primary">Text</Button>);
    const button = screen.getByRole('button');
    expect(button).toHaveClass('bg-primary');
  });

  it('calls onClick handler when clicked', () => {
    const handleClick = jest.fn();
    render(<Button onClick={handleClick}>Click</Button>);
    fireEvent.click(screen.getByRole('button'));
    expect(handleClick).toHaveBeenCalledTimes(1);
  });

  it('is disabled when disabled prop is true', () => {
    render(<Button disabled>Disabled</Button>);
    expect(screen.getByRole('button')).toBeDisabled();
  });
});

// Token validation script
import tokens from './design-tokens/figma-export/tokens.json';

describe('Design Token Tests', () => {
  it('all token references are valid', () => {
    const validateReferences = (obj, path = '') => {
      for (const [key, value] of Object.entries(obj)) {
        const currentPath = path ? `${path}.${key}` : key;

        if (value.$value && typeof value.$value === 'string') {
          // Check if it's a reference
          if (value.$value.startsWith('{') && value.$value.endsWith('}')) {
            const refPath = value.$value.slice(1, -1);
            const referenced = getNestedToken(tokens, refPath);
            expect(referenced).toBeDefined(
              `Token ${currentPath} references non-existent ${refPath}`
            );
          }
        } else if (typeof value === 'object') {
          validateReferences(value, currentPath);
        }
      }
    };

    validateReferences(tokens);
  });

  it('no circular references exist', () => {
    const checkCircular = (tokenPath, visited = new Set()) => {
      if (visited.has(tokenPath)) {
        throw new Error(`Circular reference detected: ${[...visited, tokenPath].join(' → ')}`);
      }

      visited.add(tokenPath);
      const token = getNestedToken(tokens, tokenPath);

      if (token.$value?.startsWith('{')) {
        const refPath = token.$value.slice(1, -1);
        checkCircular(refPath, new Set(visited));
      }
    };

    // Test all tokens
    Object.keys(tokens).forEach(collection => {
      checkCircular(collection);
    });
  });

  it('all colors are valid hex codes', () => {
    const hexRegex = /^#[0-9A-Fa-f]{6}$/;
    // ... check all color tokens match hex format
  });
});

// Example performance tests
import { measurePerformance } from './test-utils';

describe('Design System Performance', () => {
  it('CSS bundle size is under 50KB (gzipped)', async () => {
    const bundleSize = await getBundleSize('./dist/tokens.css');
    expect(bundleSize.gzipped).toBeLessThan(50 * 1024);
  });

  it('component library loads in under 200ms', async () => {
    const loadTime = await measurePerformance(() => {
      require('@/components/ui/button');
      require('@/components/ui/input');
      require('@/components/ui/card');
    });
    expect(loadTime).toBeLessThan(200);
  });
});

# .github/workflows/design-system-tests.yml
name: Design System Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install dependencies
        run: npm ci

      - name: Run token validation
        run: npm run test:tokens

      - name: Run component tests
        run: npm run test:components

      - name: Run accessibility tests
        run: npm run test:a11y

      - name: Visual regression tests
        run: npm run test:visual
        env:
          CHROMATIC_PROJECT_TOKEN: ${{ secrets.CHROMATIC_TOKEN }}

      - name: Check bundle size
        run: npm run test:size