Quick Start

Get a design system health report in under 2 minutes.

Interactive Setup (Recommended)

The easiest way to get started is with the interactive wizard:

npx @buoy-design/cli begin

This runs a scan, shows your results, and guides you through configuration. Learn more about buoy begin.

Step 1: Run the Audit

From your project root, run:

npx @buoy-design/cli audit

Buoy will scan your codebase and show a health report:

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

Overall Score: 67/100 (Fair)

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

Spacing
  Found: 14 unique values
  Expected: ~8
  Drift: +6 extra values

Worst Offenders
   47 issues  src/pages/Dashboard.tsx
   23 issues  src/components/Card.tsx
   18 issues  src/components/Button.tsx

Step 2: Check Specific Drift

Get detailed information about each issue:

npx @buoy-design/cli drift check

This shows exactly where hardcoded values appear:

Drift Analysis
──────────────

~ Hardcoded Value
  Component: Card
  Location:  src/components/Card.tsx:14
  Issue:     backgroundColor: #f9fafb (not a design token)

  Actions:
    1. Replace with design token
    2. Example: var(--color-gray-50) or theme.colors.gray[50]

Step 3: Initialize Config (Optional)

For ongoing use, generate a config file:

npx @buoy-design/cli init

This creates buoy.config.mjs with auto-detected settings:

export default {
  sources: {
    react: { enabled: true },
    tailwind: { enabled: true },
  }
}

Common Commands

Command Purpose
buoy begin Interactive setup wizard
buoy audit Health report with score
buoy drift check Detailed drift signals
buoy status Visual coverage grid
buoy compare tokens.json Compare against design file
buoy ci CI output with exit codes

Next Steps