# 1. Export Figma Variables → tokens.json (using Figma REST API)
curl -s -H "X-Figma-Token: $FIGMA_TOKEN" \
  "https://api.figma.com/v1/files/$FILE_KEY/variables/local" \
  | node scripts/figma-to-w3c-tokens.js > tokens/figma-raw.json

# 2. Transform with Style Dictionary
npx style-dictionary build --config sd.config.js

# 3. 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: ... } }

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

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

┌─────────────┐     ┌──────────────┐     ┌───────────────┐
│  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)│
└─────────────┘     └──────────────┘     └───────────────┘

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

/* Using margin instead of gap, wrong sizing */
.card-list {
  display: flex;
}
.card-list > * {
  margin-right: 16px;    /* Use gap instead */
  width: 33.33%;         /* Ignores Figma's Fill/Hug/Fixed */
}
.card-list > *:last-child {
  margin-right: 0;       /* Gap handles this automatically */
}

/* Direct mapping from Auto Layout properties */
.card-list {
  display: flex;
  flex-direction: row;          /* Direction: Horizontal */
  gap: 16px;                    /* Item spacing: 16 */
  padding: 24px;                /* Padding: 24 (all sides) */
  align-items: flex-start;      /* Align items: Top */
  flex-wrap: wrap;              /* Wrap enabled */
}
.card-list > .card {
  flex: 1 1 0%;                /* Sizing: Fill container */
  min-width: 280px;            /* Min width constraint */
}

Auto Layout Property        → CSS Property
──────────────────────────────────────────────────────
Direction: Horizontal       → flex-direction: row
Direction: Vertical         → flex-direction: column
Gap (item spacing)          → gap: {value}px
Padding (uniform)           → padding: {value}px
Padding (per-side)          → padding: {top} {right} {bottom} {left}
Align items: Top/Left       → align-items: flex-start
Align items: Center         → align-items: center
Align items: Bottom/Right   → align-items: flex-end
Justify: Packed (start)     → justify-content: flex-start
Justify: Space between      → justify-content: space-between
Sizing: Fill container      → flex: 1 1 0%
Sizing: Hug contents        → width: fit-content  (or omit width)
Sizing: Fixed               → width: {value}px
Min/Max width               → min-width / max-width
Wrap                        → flex-wrap: wrap
Absolute position           → position: absolute + inset values

/* Grid: when Figma uses a grid layout component or 2D placement */
.dashboard {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
  gap: 24px;
  padding: 32px;
}

// Vague props guessed from a screenshot
interface ButtonProps {
  type: string;    // What values? No idea
  big: boolean;    // Naming doesn't match design
  children: any;   // No slot documentation
}

// Props derived from Figma component properties
interface ButtonProps {
  /** Figma variant: "Variant" */
  variant: 'primary' | 'secondary' | 'ghost' | 'destructive';
  /** Figma variant: "Size" */
  size: 'sm' | 'md' | 'lg';
  /** Figma boolean: "Show Icon" */
  showIcon?: boolean;
  /** Figma instance swap: "Icon" */
  icon?: React.ComponentType<{ className?: string }>;
  /** Figma text: "Label" */
  children: React.ReactNode;
  /** Figma boolean: "Disabled" */
  disabled?: boolean;
  /** Figma boolean: "Loading" */
  loading?: boolean;
}

const components = await fetch(
  `https://api.figma.com/v1/files/${fileKey}/component_sets`,
  { headers: { 'X-Figma-Token': token } }
);

// Each component set contains:
// - componentPropertyDefinitions: variant props + types
// - children: individual variant combinations
for (const [id, set] of Object.entries(components.meta.component_sets)) {
  const props = set.componentPropertyDefinitions;
  // VARIANT → union type of allowed values
  // BOOLEAN → optional boolean prop
  // TEXT → string / ReactNode prop
  // INSTANCE_SWAP → component type prop
}

/* Eyeballed from Figma canvas — wrong values */
.card {
  padding: 15px;           /* Actual: 16px (4-unit grid) */
  font-size: 13px;         /* Actual: 14px */
  font-weight: 500;        /* Actual: 600 */
  border-radius: 10px;     /* Actual: 8px */
  gap: 10px;               /* Actual: 12px */
}

/* Exact values from Dev Mode inspect panel */
.card {
  padding: var(--spacing-md);     /* 16px — from Dev Mode */
  font-size: var(--text-sm);      /* 14px — from typography section */
  font-weight: var(--font-semibold); /* 600 — from font details */
  border-radius: var(--radius-md);   /* 8px — from corner radius */
  gap: var(--spacing-sm);           /* 12px — from gap measurement */
}

## Dev Mode Inspection Checklist

### Spacing & Layout
- [ ] Read padding from the Auto Layout section (not manual measurement)
- [ ] Read gap from the Auto Layout section
- [ ] Check constraints for responsive behavior (Fill/Hug/Fixed)

### Typography
- [ ] Font family, size, weight, line height from the Type section
- [ ] Letter spacing if non-default
- [ ] Text decoration (underline, strikethrough)

### Colors
- [ ] Read fill colors — note Variable name if using Variables
- [ ] Read border/stroke colors
- [ ] Read shadow values (offset, blur, spread, color)

### Assets
- [ ] Export icons as SVG (not PNG) at 1x
- [ ] Export images at 1x, 2x for responsive
- [ ] Use "Copy as SVG" for inline icons

/* Hardcoded values copied from Figma inspector */
:root {
  --primary: #3b82f6;
  --surface: #ffffff;
  --spacing-md: 16px;
}
/* No dark mode, no semantic aliases, breaks when design updates */

{
  "color": {
    "primary": {
      "$type": "color",
      "$value": "{color.blue.600}",
      "$description": "Primary brand color from Figma Variables"
    },
    "surface": {
      "$type": "color",
      "$value": "{color.neutral.50}",
      "$extensions": {
        "mode": {
          "dark": "{color.neutral.900}"
        }
      }
    }
  },
  "spacing": {
    "md": {
      "$type": "dimension",
      "$value": "16px"
    }
  }
}

// Fetching Figma Variables via REST API
const response = await fetch(
  `https://api.figma.com/v1/files/${fileKey}/variables/local`,
  { headers: { 'X-Figma-Token': process.env.FIGMA_TOKEN } }
);
const { meta } = await response.json();

// Map Figma collections → W3C token groups
for (const collection of Object.values(meta.variableCollections)) {
  // Each collection = token group (e.g., "colors", "spacing")
  // Each mode = theme variant (e.g., "light", "dark")
}

// No visual regression — manual screenshot comparison
test('button looks right', async ({ page }) => {
  await page.goto('/components/button');
  // Developer opens Figma side-by-side and squints
  // Misses: wrong padding, slightly off color, missing focus ring
  expect(true).toBe(true); // "Looks good to me"
});

// Applitools Eyes — automated visual comparison
import { Eyes, Target, BatchInfo } from '@applitools/eyes-playwright';

test('button matches Figma design', async ({ page }) => {
  const eyes = new Eyes();
  eyes.setBatch(new BatchInfo('Design Handoff QA'));

  await eyes.open(page, 'Component Library', 'Button — All Variants');

  // Capture each variant
  for (const variant of ['primary', 'secondary', 'ghost', 'destructive']) {
    await page.goto(`/storybook/iframe.html?id=button--${variant}`);
    await eyes.check(`Button ${variant}`, Target.window().fully());
  }

  await eyes.close(); // Fails if visual diff exceeds threshold
});

// .storybook/main.ts — Chromatic captures all stories automatically
export default {
  stories: ['../src/**/*.stories.@(ts|tsx)'],
  addons: ['@chromatic-com/storybook'],
};

// CI: npx chromatic --project-token=$CHROMATIC_TOKEN
// Each story = one visual snapshot
// PR gets a Chromatic status check with diff review UI

// playwright.config.ts — Percy snapshot integration
import { percySnapshot } from '@percy/playwright';

test('homepage matches design', async ({ page }) => {
  await page.goto('/');
  await percySnapshot(page, 'Homepage', {
    widths: [375, 768, 1280], // Mobile, tablet, desktop
  });
});

// applitools.config.ts
import { Configuration } from '@applitools/eyes-playwright';

const config: Configuration = {
  apiKey: process.env.APPLITOOLS_API_KEY,
  appName: 'MyApp',
  batchName: 'Design Handoff QA',
  // Match Figma frame dimensions
  browser: [
    { width: 1440, height: 900, name: 'chrome' },
    { width: 375, height: 812, name: 'chrome' }, // Mobile
  ],
  // AI-powered matching — ignores anti-aliasing, minor rendering diffs
  matchLevel: 'Layout',
};

export default config;

import { Eyes, Target } from '@applitools/eyes-playwright';

test.describe('Figma Design Comparison', () => {
  let eyes: Eyes;

  test.beforeEach(async ({ page }) => {
    eyes = new Eyes();
    await eyes.open(page, 'MyApp', test.info().title);
  });

  test.afterEach(async () => {
    await eyes.close();
  });

  test('Homepage hero section', async ({ page }) => {
    await page.goto('/');
    await eyes.check(
      'Hero',
      Target.region('#hero-section')
        .ignoreDisplacements()  // Ignore content shifts
        .layout()               // Layout-level matching
    );
  });

  test('Button component — all variants', async ({ page }) => {
    await page.goto('/storybook/iframe.html?id=button--all-variants');
    await eyes.check('Button Variants', Target.window().fully());
  });
});

# .github/workflows/visual-qa.yml
name: Visual QA
on: [pull_request]

jobs:
  visual-regression:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - run: npx playwright test tests/visual/
        env:
          APPLITOOLS_API_KEY: ${{ secrets.APPLITOOLS_API_KEY }}
      - name: Check Applitools results
        if: always()
        run: npx @applitools/eyes-cli results --fail-on-diff

## Design Reference

- **Figma file**: [Link to Figma file]
- **Figma frame**: [Link to specific frame/component]
- **Design status**: Ready for dev / In review / Needs design update

## Implementation Checklist

- [ ] All variants implemented (list variant names)
- [ ] Spacing matches Dev Mode measurements
- [ ] Colors reference design tokens (no hardcoded hex)
- [ ] Typography uses token scale
- [ ] Responsive behavior matches constraints
- [ ] Interactive states: hover, focus, active, disabled
- [ ] Accessibility: keyboard nav, screen reader, contrast
- [ ] Storybook story added for each variant
- [ ] Visual regression snapshot captured

## Screenshots

| Figma | Implementation |
|-------|---------------|
| [screenshot] | [screenshot] |

| Component | Figma Status | Dev Status | Tokens | Visual QA |
|-----------|-------------|------------|--------|-----------|
| Button    | Ready       | Complete   | Synced | Approved  |
| Card      | Ready       | In PR      | Synced | Pending   |
| Modal     | In Review   | Not Started| —      | —         |
| Nav       | Ready       | Complete   | Synced | Failed    |

┌────────────────────────────────────────────────────────────┐
│                     DESIGN PHASE                           │
│                                                            │
│  Designer creates:                                         │
│  • Components with variants (Button: primary/secondary)    │
│  • Variables for colors, spacing, typography                │
│  • Auto Layout for all container frames                    │
│  • Modes for light/dark, compact/comfortable               │
└──────────────────────┬─────────────────────────────────────┘
                       │
                       ▼
┌────────────────────────────────────────────────────────────┐
│                    EXPORT PHASE                             │
│                                                            │
│  Automated via Figma REST API or plugin:                   │
│  • GET /v1/files/{key}/variables/local → token JSON        │
│  • GET /v1/files/{key}/component_sets → component specs    │
│  • Export assets via /v1/images/{key} → SVG/PNG            │
└──────────────────────┬─────────────────────────────────────┘
                       │
                       ▼
┌────────────────────────────────────────────────────────────┐
│                   TRANSFORM PHASE                           │
│                                                            │
│  Style Dictionary processes W3C DTCG tokens:               │
│  • Input: tokens/figma-raw.json                            │
│  • Transforms: color/oklch, size/rem, name/cti/kebab       │
│  • Output: CSS variables, Tailwind theme, iOS/Android      │
└──────────────────────┬─────────────────────────────────────┘
                       │
                       ▼
┌────────────────────────────────────────────────────────────┐
│                    BUILD PHASE                              │
│                                                            │
│  Developer implements components:                          │
│  • Map Auto Layout → CSS Flexbox/Grid                      │
│  • Apply token variables (not hardcoded values)            │
│  • Implement all variant/state combinations                │
│  • Write Storybook stories for each component              │
└──────────────────────┬─────────────────────────────────────┘
                       │
                       ▼
┌────────────────────────────────────────────────────────────┐
│                   VERIFY PHASE                              │
│                                                            │
│  Visual regression in CI:                                  │
│  • Chromatic captures Storybook story snapshots            │
│  • Applitools compares production ↔ Figma frames           │
│  • Percy captures full-page responsive screenshots         │
│  • PR blocked until visual diffs approved                  │
└────────────────────────────────────────────────────────────┘

# .github/workflows/design-sync.yml
name: Design Token Sync
on:
  schedule:
    - cron: '0 9 * * 1'  # Weekly Monday 9am
  workflow_dispatch:

jobs:
  sync-tokens:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: node scripts/figma-to-w3c-tokens.js
        env:
          FIGMA_TOKEN: ${{ secrets.FIGMA_TOKEN }}
          FIGMA_FILE_KEY: ${{ vars.FIGMA_FILE_KEY }}
      - run: npx style-dictionary build
      - uses: peter-evans/create-pull-request@v6
        with:
          title: 'chore: sync design tokens from Figma'
          branch: chore/design-token-sync