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 ahoybuoy dock

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

Step 1: Run a Drift Scan

From your project root, run:

npx ahoybuoy drift

Buoy will scan your codebase and show drift issues:

🛟 Scanning for design drift...

Found 23 issues in 142 files

HARDCODED VALUES (8)
├─ Card.tsx:8 #ffffff → use var(--bg-surface)
├─ Badge.tsx:3 8px → use var(--spacing-sm)
└─ ... and 6 more

INLINE STYLES (5)
├─ Modal.tsx:12 inline padding → use spacing token
└─ ... and 4 more

Step 2: Get a Health Report

For a broader view, run the health report:

npx ahoybuoy show health

This shows your overall design system health score and worst offenders.

Step 3: Fix Drift Automatically

See what Buoy can fix for you:

# Preview fixes (dry run)
buoy drift fix --dry-run

# Apply fixes to files
buoy drift fix --apply

Buoy replaces hardcoded values with matching design tokens, with configurable confidence levels.

Step 4: Set Up Config (Optional)

For ongoing use, dock Buoy into your project:

buoy dock config

This creates a .buoy.yaml config file with auto-detected settings for your project.

Common Commands

Command Purpose
buoy dock Interactive setup wizard
buoy drift Detect design drift issues
buoy drift check Fast check for CI / pre-commit hooks
buoy drift fix Suggest and apply token replacements
buoy show health Health report with score
buoy show all Show components, tokens, drift, health
buoy dock tokens Extract and generate design tokens
buoy dock tokens compare tokens.json Compare codebase against token file

Next Steps