buoy compare

Compare your codebase values against a design tokens file. Identifies which values in your code don't match any defined tokens.

Usage

buoy compare <tokens-file> [options]

Arguments

Argument Description
<tokens-file> Path to design tokens file (JSON, CSS, or SCSS)

Options

Option Description
--json Output as JSON for scripting
--strict Fail if any unmatched values found

Supported Token Formats

Design Tokens JSON (W3C format)

{
  "color": {
    "primary": { "$value": "#3b82f6" },
    "secondary": { "$value": "#64748b" }
  },
  "spacing": {
    "sm": { "$value": "8px" },
    "md": { "$value": "16px" }
  }
}

Tokens Studio / Figma Export

{
  "colors": {
    "blue-500": "#3b82f6",
    "gray-500": "#64748b"
  }
}

CSS Custom Properties

:root {
  --color-primary: #3b82f6;
  --spacing-md: 16px;
}

Example Output

$ buoy compare design-tokens.json

Comparing against design-tokens.json...

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

Colors
  ✓ 18 values match tokens
  ✗ 5 values not in tokens:
      #f9fafb (used 3 times)
      #374151 (used 2 times)
      #3b83f6 (used 1 time) ← close to #3b82f6

Spacing
  ✓ 12 values match tokens
  ✗ 2 values not in tokens:
      15px (used 4 times) ← close to 16px
      13px (used 1 time)

Summary
───────
Token coverage: 87%
Unmatched values: 7
Close matches (possible typos): 2

With Figma Integration

If you have Figma connected, you can compare directly against your Figma file: 

# After running `buoy init` with Figma
buoy compare --figma

See Figma Integration for setup instructions.

JSON Output

buoy compare tokens.json --json
{
  "coverage": 87,
  "matched": 30,
  "unmatched": 7,
  "categories": {
    "color": {
      "matched": 18,
      "unmatched": [
        { "value": "#f9fafb", "count": 3 },
        { "value": "#3b83f6", "count": 1, "closeTo": "#3b82f6" }
      ]
    }
  }
}

Related Commands