Buoy

Buoy

[GitHub App]

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)

Code-first System Observability

Your shipped code is the design-system source of truth. Declare the packages you own, then use Buoy to map adoption, unmanaged UI surface area, and the blast radius of a component or token change. Figma and other design tools can remain optional inputs; they are not required for the system map.

# .buoy.yamlproject:  name: acme
system:  components:    - packages/ui/src/**  tokens:    - packages/tokens/src/**  owners:    - name: Checkout      paths:        - apps/checkout/**

buoy system map                 # Canonical system vs unmanaged surface areabuoy system impact Button       # Consumers and migration risk for a changebuoy system impact color-primary --kind token

This is the foundation for cloud adoption trends, deprecation planning, and AI-assisted iteration reporting: every result is derived from code and can be attributed to a repository path and owner.

Quick Start

# See your design system immediately (zero config)npx ahoybuoy show all
# Add project configuration and local integrations when readynpx ahoybuoy dock

No config needed. Buoy auto-detects your framework and starts working immediately.

What It Catches

Commands

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├── rescue                  # Complete measure → repair → guard → prove journey│   ├── plan                # Build a local baseline and repair plan│   ├── apply               # Apply reviewed safe fixes on a new branch│   ├── verify              # Run detected typecheck/test scripts│   ├── guard               # Record reviewed legacy drift with reasons│   ├── report              # Generate JSON, Markdown, and HTML evidence│   └── rollback            # Restore local pre-Rescue backups├── 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

For AI Agents

Coding agents hardcode values because they never read your token file. Give them Buoy as an MCP server:

npx @buoy-design/cli mcp install claude   # or cursor, codex, windsurf, all

Claude Code (and any MCP client) gets four tools: list_design_tokens, find_token_for_value (#1a73e8 → --color-primary), check_ui_against_design_system (line-level, with the token and an exact line edit) and design_system_context. Claude Code also gets a PostToolUse hook that checks every style file it edits and hands the fixes back before it moves on. See docs/integrations/mcp.

In Claude Code, the plugin bundles all of it: /plugin marketplace add ahoybuoy/buoy, then /plugin install buoy@buoy.

To review every pull request as well, install the free GitHub App; no Buoy account is needed.

The show command outputs JSON for AI agents to consume:

# Get everything an AI agent needsbuoy show all --json
# Just drift signalsbuoy show drift --json
# Components inventorybuoy show components --json

Example output:

{  "components": [...],  "tokens": [...],  "drift": {    "signals": [...],    "summary": { "total": 12, "critical": 2, "warning": 7, "info": 3 }  },  "health": { "score": 78 }}

Getting Started

Complete a Rescue journey

buoy rescue plan# Review .buoy/rescue/runs/<run-id>/report.htmlbuoy rescue apply --run <run-id> --approvebuoy rescue guard --run <run-id> --reason "Reviewed legacy baseline" --actor "Design systems team"buoy rescue report --run <run-id>

Rescue keeps ambiguous findings review-only, runs detected project checks after applying high-confidence changes, and retains local backups for rollback. It does not commit, push, open a pull request, or upload source code. See docs/rescue.md for the complete workflow.

Configure Your Project

buoy dock

Smart walkthrough that sets up:

1. .buoy.yaml — Project configuration
2. AI agent skills — For Claude Code, Copilot, etc.
3. CLAUDE.md context — Design system documentation
4. Git hooks — Pre-commit drift checking

Configure severities per drift type

# .buoy.yamlproject:  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: 70

Drift Detection

Quick Check

buoy drift check

Fast pre-commit hook friendly. Exits with error code if drift found.

Detailed Analysis

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)"    }  ]}

Fix Issues

buoy drift fix                    # Interactive fix suggestionsbuoy drift fix --dry-run          # Preview changesbuoy drift fix --apply            # Apply reviewed high-confidence fixes

Ignore Existing Drift

For 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 reasonbuoy drift ignore add -r "Third-party components"               # Add new drift to ignore listbuoy drift ignore show                                          # View ignored drift with reasonsbuoy drift check                                                # Only fails on new drift

A reason is required when ignoring drift to maintain accountability.

CI Integration

GitHub Actions

name: Design System Checkon: [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

Design health badge

Repos scanned by Buoy Cloud get a live score badge for the README:

[![design health](https://api.buoy.design/badges/OWNER/REPO.svg)](https://buoy.design)

Green at 80+, yellow at 60+, red below. It updates within five minutes of each scan.

PR Comments with Buoy Cloud

# Set up GitHub PR botbuoy ahoy loginbuoy ahoy github

The GitHub bot automatically comments on PRs with drift analysis.

AI Guardrails

Keep AI coding assistants (Copilot, Claude, Cursor) aligned with your design system:

# Set up AI agents with design system contextbuoy dock agents

Creates:

• AI Skills — Design system knowledge for Claude Code
• Claude Hooks — Auto-inject context at session start
• CLAUDE.md — Project-specific AI instructions

Self-Validating Agents (Claude Code)

Turn Claude Code into a self-correcting agent. When Claude writes a component, Buoy checks it and feeds corrections back automatically:

buoy mcp install claude     # MCP server + line-level hook (recommended)buoy dock hooks --claude    # hook only, component-level

This installs a PostToolUse hook that:

1. Claude writes/edits a component file
2. Hook runs buoy drift check on the modified file
3. If drift detected, feedback returns to Claude
4. 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.

Configuration

Works without config, but you can save settings:

buoy dock config

Creates .buoy.yaml:

project:  name: my-app
sources:  react:    enabled: true    include:      - src/**/*.tsx    exclude:      - "**/*.test.*"  tokens:    enabled: true    files:      - design-tokens.css

Buoy Cloud

Ship your drift detection to the cloud:

buoy ahoy login             # Authenticatebuoy ahoy status            # View account, bot, sync statusbuoy ahoy github            # Set up GitHub PR botbuoy ahoy billing           # Manage subscription

Features:

• PR Bot — Automatic comments on pull requests
• Dashboard — View drift trends over time
• Team sync — Share results across team members

Supported Frameworks

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)

Philosophy

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 mebuoy drift check            # Pre-commit check (fails on critical)buoy drift check --fail-on warning    # Fail on warning or abovebuoy drift check --fail-on none       # Never fail (report only)buoy drift check --staged             # Only check staged files

Development

# Install dependenciespnpm install
# Build all packagespnpm build
# Run testspnpm test
# Run CLI locallynode apps/cli/dist/bin.js show all

Packages

License

MIT