Token Comparison

Buoy compares values in your codebase against your design tokens to find mismatches. This helps ensure your implementation matches your design system source of truth.

How It Works

  1. Load tokens — From JSON, CSS, or Figma
  2. Scan code — Extract all style values from your codebase
  3. Match — Compare each value against your token set
  4. Report — Show matched, unmatched, and close matches

Supported Token Formats

W3C Design Tokens (JSON)

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

Tokens Studio Format

{
  "colors": {
    "blue": {
      "500": "#3b82f6",
      "600": "#2563eb"
    }
  },
  "spacing": {
    "4": "16px",
    "8": "32px"
  }
}

CSS Custom Properties

:root {
  --color-primary: #3b82f6;
  --color-secondary: #64748b;
  --spacing-sm: 8px;
  --spacing-md: 16px;
}

SCSS Variables

$color-primary: #3b82f6;
$color-secondary: #64748b;
$spacing-sm: 8px;
$spacing-md: 16px;

Comparison Output

$ buoy compare design-tokens.json

Token Coverage Report
─────────────────────

Colors (18 tokens defined)
  ✓ 15 matched
  ✗ 3 unmatched:
      #f9fafb  (3 usages)
      #374151  (2 usages)
      #3b83f6  (1 usage) → close to #3b82f6

Spacing (8 tokens defined)
  ✓ 6 matched
  ✗ 2 unmatched:
      15px  (4 usages) → close to 16px
      13px  (1 usage)

Coverage: 84%

Close Match Detection

Buoy identifies values that are "close" to your tokens, which are often typos:

Found Token Likely Issue
#3b83f6 #3b82f6 Typo (one digit off)
15px 16px Off-by-one
rgb(59,130,246) #3b82f6 Same color, different format

Value Normalization

Buoy normalizes values for accurate comparison:

  • Colors: rgb(), hsl(), hex are normalized
  • Spacing: px, rem, em are compared
  • Case: #FFF matches #fff

Usage

# Compare against local file
buoy compare design-tokens.json

# Compare against Figma
buoy compare --figma

# With strict mode (fail on any unmatched)
buoy compare tokens.json --strict

Related