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 dock tokens 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 token file
buoy dock tokens compare design-tokens.json

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

# With verbose output
buoy dock tokens compare tokens.json --verbose

Related