Introduction to Buoy

Buoy is a design drift detection tool for AI-generated code. It scans your codebase to catch when developers (especially AI tools like Copilot and Claude) diverge from design system patterns before code ships.

The Missing Feedback Loop

In development, we have robust feedback mechanisms: tests catch bugs, linters enforce style, type checkers prevent errors. These tools give developers immediate signals when something is wrong.

Design systems have no equivalent. When AI generates padding: 15px instead of your 16px token, nothing breaks. No test fails. No error appears. The code ships, and your design system slowly erodes.

Buoy is that missing feedback loop. It's the linter for your design system—a source of truth that tells AI and developers alike: "This doesn't match the system."

What is Design Drift?

Design drift happens when code gradually diverges from your design system. It's the accumulation of small inconsistencies that add up over time:

  • A developer eyeballs a color and types #3b83f6 instead of #3b82f6
  • AI generates a component with padding: 15px instead of your 16px spacing token
  • Someone copy-pastes a button with hardcoded styles instead of using the design system component

After 6 months, you end up with 47 shades of "blue" and 12 different spacing values. Buoy catches this drift before it ships.

Quick Example

$ npx @buoy-design/cli audit

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

Overall Score: 34/100 (Poor)

Colors
  Found: 47 unique values
  Expected: ~12
  Drift: +35 extra colors

Spacing
  Found: 31 unique values
  Expected: ~8
  Drift: +23 extra values

Worst Files
  src/pages/Dashboard.tsx     47 issues
  src/components/Card.tsx     38 issues

Key Features

  • Zero Config — Auto-detects React, Vue, Svelte, Angular, Tailwind
  • Health Scoring — 0-100 score showing your design system health
  • Token Comparison — Compare against Figma/Tokens Studio exports
  • CI Integration — Catch drift in pull requests before merge
  • Typo Detection — Finds values that are "close" to tokens (likely mistakes)

Next Steps