Catch design drift before it ships.
AI coding tools are fast—but they don't know your design system. They'll write #3b82f6 when you have --color-primary. They'll use padding: 17px when your spacing scale is multiples of 4.
Buoy watches for these issues and helps you fix them.
src/components/Button.tsx:24
hardcoded-value: #3b82f6 → var(--color-primary) (92% match)
# Interactive setup wizard
npx ahoybuoy begin
# Or see your design system immediately (zero config!)
npx ahoybuoy show allNo config needed. Buoy auto-detects your framework and starts working immediately.
| Issue | Example |
|---|---|
| Hardcoded colors | #ff0000 instead of var(--color-primary) |
| Arbitrary spacing | padding: 17px instead of design scale |
| Tailwind escape hatches | p-[13px] instead of p-4 |
| Naming inconsistencies | ButtonNew, ButtonV2, ButtonOld |
| Unused components | Defined but never imported or rendered |
| Semantic mismatches | Same prop typed string in one, number in another |
| Repeated patterns | Same Tailwind classes copy-pasted 5+ times |
| Framework sprawl | React + Vue + jQuery in same codebase |
| Detached components | Instances without main component |
buoy
├── show # Read design system info (for AI agents)
│ ├── components # Components in codebase
│ ├── tokens # Design tokens found
│ ├── drift # Design system violations
│ ├── health # Health score
│ ├── history # Scan history
│ ├── config # Current .buoy.yaml configuration
│ ├── skills # AI agent skill files
│ ├── agents # Configured AI agents
│ ├── context # Design system context in CLAUDE.md
│ ├── hooks # Configured hooks
│ ├── commands # Installed slash commands
│ ├── graph # Knowledge graph stats
│ ├── plugins # Available scanners
│ └── all # Everything combined
├── drift # Drift detection and fixing
│ ├── scan # Scan codebase for components/tokens
│ ├── check # Pre-commit drift check
│ ├── fix # Suggest/apply fixes
│ └── ignore # Ignore existing drift
│ ├── all # Ignore all current drift (requires --reason)
│ ├── show # View ignored drift signals
│ ├── add # Add new drift to ignore list (requires --reason)
│ └── clear # Remove ignore list
├── begin # Interactive wizard
├── dock # Dock tools into your project
│ ├── config # Create .buoy.yaml
│ ├── skills # Create AI agent skills
│ ├── agents # Set up AI agents
│ ├── context # Generate CLAUDE.md context
│ ├── hooks # Set up hooks (--claude for self-validating AI)
│ ├── commands # Install Claude slash commands
│ ├── plugins # Show available scanners
│ ├── tokens # Generate/export design tokens
│ │ ├── compare # Compare token sources
│ │ └── import # Import tokens from Figma/CSS
│ └── graph # Build design system knowledge graph
│ └── learn # Learn patterns from codebase
└── ahoy # Cloud features
├── login # Authenticate
├── logout # Sign out
├── status # Account + bot + sync status
├── github # Set up GitHub PR bot
├── gitlab # Set up GitLab PR bot (soon)
├── billing # Manage subscription
└── plans # Compare pricing
The show command outputs JSON for AI agents to consume:
# Get everything an AI agent needs
buoy show all --json
# Just drift signals
buoy show drift --json
# Components inventory
buoy show components --jsonExample output:
{
"components": [...],
"tokens": [...],
"drift": {
"signals": [...],
"summary": { "total": 12, "critical": 2, "warning": 7, "info": 3 }
},
"health": { "score": 78 }
}buoy beginWalks you through:
- Framework detection — Confirms what Buoy found
- Token discovery — Shows your design tokens
- Quick scan — Immediate drift report
- CI setup — GitHub Actions configuration
- Figma connection — Link your design files
buoy dockSmart walkthrough that sets up:
.buoy.yaml— Project configuration- AI agent skills — For Claude Code, Copilot, etc.
- CLAUDE.md context — Design system documentation
- Git hooks — Pre-commit drift checking
# .buoy.yaml
project:
name: my-app
drift:
severity:
hardcoded-value: critical
naming-inconsistency: warning
# Ignore specific drift (filter by type, file, component, token, value, severity)
ignore:
- type: hardcoded-value
file: "src/legacy/**"
- severity: info
# Promote matching drift to a higher severity
promote:
- type: hardcoded-value
file: "src/components/**"
to: critical
reason: "Design system components must use tokens"
# Enforce — always treat matching drift as critical
enforce:
- type: naming-inconsistency
component: "^Button"
reason: "Button naming is standardized"
health:
# CI gate — exit code 1 if health score falls below threshold
failBelow: 70buoy drift checkFast pre-commit hook friendly. Exits with error code if drift found.
buoy show drift{
"drifts": [
{
"type": "hardcoded-value",
"severity": "warning",
"file": "src/components/Button.tsx",
"line": 24,
"message": "#3b82f6 should use var(--color-primary)",
"suggestion": "var(--color-primary)"
}
]
}buoy drift fix # Interactive fix suggestions
buoy drift fix --dry-run # Preview changes
buoy drift fix --auto # Auto-apply safe fixesFor brownfield projects, ignore existing issues and only flag new ones:
buoy drift ignore all -r "Legacy code before design system" # Ignore all current drift with reason
buoy drift ignore add -r "Third-party components" # Add new drift to ignore list
buoy drift ignore show # View ignored drift with reasons
buoy drift check # Only fails on new driftA reason is required when ignoring drift to maintain accountability.
name: Design System Check
on: [pull_request]
jobs:
buoy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: "20"
- run: npx ahoybuoy drift check# Set up GitHub PR bot
buoy ahoy login
buoy ahoy githubThe GitHub bot automatically comments on PRs with drift analysis.
Keep AI coding assistants (Copilot, Claude, Cursor) aligned with your design system:
# Set up AI agents with design system context
buoy dock agentsCreates:
- AI Skills — Design system knowledge for Claude Code
- Claude Hooks — Auto-inject context at session start
- CLAUDE.md — Project-specific AI instructions
Turn Claude Code into a self-correcting agent. When Claude writes a component, Buoy checks it and feeds corrections back automatically:
buoy dock hooks --claudeThis installs a PostToolUse hook that:
- Claude writes/edits a component file
- Hook runs
buoy drift checkon the modified file - If drift detected, feedback returns to Claude
- Claude self-corrects without prompting
Example feedback Claude receives:
⚠️ Design drift detected in Button.tsx:
• hardcoded-value: Component "Button" has 3 hardcoded colors: #3b82f6, #ffffff, #1e40af
Run `buoy show drift` for full details.
Works with React, Vue, Svelte, and Angular components. Skips test files and configs.
Works without config, but you can save settings:
buoy dock configCreates .buoy.yaml:
project:
name: my-app
sources:
react:
enabled: true
include:
- src/**/*.tsx
exclude:
- "**/*.test.*"
tokens:
enabled: true
files:
- design-tokens.cssShip your drift detection to the cloud:
buoy ahoy login # Authenticate
buoy ahoy status # View account, bot, sync status
buoy ahoy github # Set up GitHub PR bot
buoy ahoy billing # Manage subscriptionFeatures:
- PR Bot — Automatic comments on pull requests
- Dashboard — View drift trends over time
- Team sync — Share results across team members
Components: React, Vue, Svelte, Angular, Lit, Stencil, Alpine, HTMX
Templates: Blade, ERB, Twig, Razor, Jinja, Handlebars, EJS, Pug
Tokens: CSS variables, SCSS, Tailwind config, JSON, Style Dictionary
Design Tools: Figma (plugin + API integration)
Inform by default, block by choice.
Buoy shows you what's happening without getting in your way. Teams adopt enforcement when they're ready:
buoy show drift # Just show me
buoy drift check # Pre-commit check (fails on critical)
buoy drift check --fail-on warning # Fail on warning or above
buoy drift check --fail-on none # Never fail (report only)
buoy drift check --staged # Only check staged files# Install dependencies
pnpm install
# Build all packages
pnpm build
# Run tests
pnpm test
# Run CLI locally
node apps/cli/dist/bin.js show all| Package | Description |
|---|---|
@buoy-design/cli |
Command-line interface |
@buoy-design/core |
Domain models and drift detection engine |
@buoy-design/scanners |
Framework-specific code scanners |
ahoybuoy |
CLI wrapper (npx ahoybuoy) |
buoy-design |
CLI wrapper (npx buoy-design) |
MIT