Figma / Tokens Studio

Connect Buoy to Figma to compare your codebase directly against your design file. Works with native Figma styles or Tokens Studio exports.

Quick Start

Option 1: Tokens Studio Export

Export your tokens from Tokens Studio and compare locally:

  1. In Figma, open Tokens Studio plugin
  2. Export as JSON (Settings → Export → JSON)
  3. Save as design-tokens.json in your project
  4. Run: buoy compare design-tokens.json

Option 2: Figma API (Live Sync)

Connect directly to Figma for always-current tokens:

  1. Generate a Figma access token
  2. Add to your environment
  3. Configure in buoy.config.mjs

Getting a Figma Token

  1. Go to Figma Settings → Account
  2. Scroll to Personal access tokens
  3. Click Generate new token
  4. Give it a name like "Buoy"
  5. Copy the token (you won't see it again)

Configuration

// buoy.config.mjs
export default {
  tokens: {
    figma: {
      fileId: 'your-figma-file-id',
      accessToken: process.env.FIGMA_TOKEN,
    },
  },
}

Finding Your File ID

The file ID is in your Figma URL:

https://www.figma.com/file/abc123xyz/Design-System
                           ↑↑↑↑↑↑↑↑↑↑↑
                           This is your file ID

Environment Variable

Set FIGMA_TOKEN in your environment:

# .env (local development)
FIGMA_TOKEN=figd_xxxxxxxxxxxxxxxxxxxxx

# GitHub Actions
env:
  FIGMA_TOKEN: ${{ secrets.FIGMA_TOKEN }}

What Buoy Extracts

From Figma files, Buoy extracts:

Category What's Extracted
Colors Color styles, fill colors, stroke colors
Typography Text styles, font families, sizes, weights
Spacing Auto-layout gaps, padding values
Border radius Corner radius values
Effects Shadows, blur values

Tokens Studio Support

If you use Tokens Studio, Buoy supports its JSON format directly:

{
  "colors": {
    "primary": {
      "500": { "value": "#3b82f6", "type": "color" }
    }
  },
  "spacing": {
    "sm": { "value": "8px", "type": "spacing" },
    "md": { "value": "16px", "type": "spacing" }
  }
}

Comparison Output

$ buoy compare --figma

Comparing against Figma file "Design System"...

Last synced: 2 hours ago

Token Coverage
──────────────

Colors (24 Figma styles)
  ✓ 20 matched in code
  ✗ 4 not used in code
  âš  5 in code but not in Figma:
      #f9fafb  (3 usages)
      #3b83f6  (1 usage) → close to primary/500

Typography (8 Figma styles)
  ✓ 7 matched
  ✗ 1 not used

Coverage: 82%

Filtering Pages/Frames

Only extract tokens from specific pages:

tokens: {
  figma: {
    fileId: 'abc123xyz',
    accessToken: process.env.FIGMA_TOKEN,
    pages: ['Design Tokens', 'Colors'],  // Only these pages
  },
}

CI Integration

Add Figma sync to your CI pipeline:

- name: Run Buoy with Figma
  run: npx @buoy-design/cli ci --threshold 70
  env:
    FIGMA_TOKEN: ${{ secrets.FIGMA_TOKEN }}

Troubleshooting

403 Forbidden

Your token may have expired or lack permissions. Generate a new one.

No Tokens Found

Ensure your Figma file has published styles. Draft styles aren't included.

Rate Limiting

Figma has API limits. Use local token exports for frequent runs.

Related