buoy audit

Generate a comprehensive health report for your design system. Shows unique values found, compares against expected counts, identifies worst offender files, and calculates an overall score.

Usage

buoy audit [options]

Options

Example Output

$ buoy audit

Design System Health Report
───────────────────────────

Overall Score: 34/100 (Poor)

Colors
  Found: 47 unique values
  Expected: ~12
  Drift: +35 extra colors
  Most common:
    #3b82f6  (23 usages)
    #ef4444  (15 usages)
    #10b981  (12 usages)

Spacing
  Found: 31 unique values
  Expected: ~8
  Drift: +23 extra values
  Most common:
    16px  (45 usages)
    8px   (38 usages)
    24px  (22 usages)

Possible Typos
  ⚠ #3b83f6 → close to #3b82f6
  ⚠ #ef4445 → close to #ef4444

Worst Offenders
   47 issues  src/pages/Dashboard.tsx
   38 issues  src/components/Card.tsx
   29 issues  src/components/Table.tsx

──────────────────────────────────────────────────
Total unique values: 89
Total usages: 234
Files affected: 23

Health Score

The score (0-100) is calculated based on:

• Unique value count — Penalty for exceeding expected counts
• Close matches — Penalty for likely typos
• File concentration — Penalty for files with many issues

Typo Detection

With --tokens, Buoy finds values that are "close" to your design tokens:

buoy audit --tokens design-tokens.json

This catches common mistakes like #3b83f6 (typo) vs #3b82f6 (correct token).

JSON Output

buoy audit --json

{
  "score": 34,
  "categories": {
    "color": {
      "uniqueCount": 47,
      "totalUsages": 156,
      "mostCommon": [
        { "value": "#3b82f6", "count": 23 }
      ]
    }
  },
  "worstFiles": [
    { "file": "src/pages/Dashboard.tsx", "issueCount": 47 }
  ],
  "totals": {
    "uniqueValues": 89,
    "totalUsages": 234,
    "filesAffected": 23
  }
}

Related Commands

• buoy drift — Detailed drift signals with locations
• buoy compare — Compare against design token file
• buoy ci — CI-optimized output