Introduction to Buoy

Buoy is an open-source design drift scanner (CLI) and a GitHub App that catches drift on every PR. 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 ahoybuoy drift

🛟 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

ACCESSIBILITY (2)
├─ Button.tsx:12 Missing aria-label
└─ Modal.tsx:45 Focus trap not implemented

Key Features

  • Zero Config — Auto-detects React, Vue, Svelte, Angular, Next.js, Tailwind, and 50+ frameworks
  • Drift Detection — Finds hardcoded colors, spacing, typography, arbitrary Tailwind, inline styles with error/warning/info severity levels
  • Smart Fix Column — Shows 🎯 for exact token matches, ≈ for the nearest token when the value differs, and 💡 for suggested new tokens, so you know what's safe to apply
  • Token Regressions — Flags a PR that replaces a token reference with its literal value, with a one-click fix that restores the token
  • Auto-Fix — Suggests and applies token replacements with buoy drift fix --apply
  • Health Scoring — 0-100 score from a single source of truth (the scanner), showing your design system health via buoy show health
  • Token Detection — Auto-detects tokens from CSS custom properties, JS theme objects, and Tailwind config
  • Coding Agents — An MCP server and Claude Code plugin give agents your tokens while they write and check each edit for drift
  • Ignore Rules — Ignore existing drift from CLI or dashboard so you only see new issues

Next Steps