Drift Detection

Buoy detects when code diverges from your design system. This happens gradually as developers (and AI tools) introduce hardcoded values, typos, and inconsistent patterns.

What is Design Drift?

Design drift is the accumulation of small inconsistencies that erode your design system over time:

  • A developer eyeballs a color: #3b83f6 instead of #3b82f6
  • AI generates padding: 15px instead of your 16px spacing token
  • Someone copy-pastes a button with hardcoded styles
  • A new team member uses gray-600 when your system uses slate-600

After months, you end up with 47 shades of "blue" and inconsistent spacing everywhere.

Types of Drift

Hardcoded Values

Raw values used instead of design tokens:

// Drift: hardcoded color
<div style={{ color: '#3b82f6' }}>

// Should be:
<div style={{ color: theme.colors.blue[500] }}>

Close Matches (Typos)

Values that are almost—but not quite—a design token:

// Typo: #3b83f6 (wrong digit)
// Token: #3b82f6

// Typo: 15px (off-by-one)
// Token: 16px

Naming Inconsistencies

Components or classes that don't follow naming conventions:

// Inconsistent: PrimaryBtn, primary_button, PrimaryButton
// Convention: PrimaryButton

Deprecated Patterns

Using old patterns that have been replaced:

// Deprecated: inline styles
<div style="padding: 16px">

// Current: utility classes
<div class="p-4">

How Detection Works

  1. Scan — Buoy parses your source files to extract all style values
  2. Normalize — Values are normalized (e.g., rgb() to hex)
  3. Compare — Each value is compared against your design tokens
  4. Classify — Mismatches are classified by type and severity
  5. Report — Results show location, context, and fix suggestions

Fix Column: Token Match vs Suggestion

When Buoy reports drift in a PR comment, the Fix column distinguishes between verified token matches and suggested new tokens:

Indicator Meaning Example
🎯 Verified match The fix maps to an existing design token in your system 🎯 var(--color-primary)
💡 Suggested token Buoy suggests a new token name that doesn't exist yet 💡 --spacing-card

This distinction helps teams prioritize: verified matches (🎯) are safe to apply immediately, while suggestions (💡) indicate values that should be extracted into new tokens.

Severity Levels

Level Description Examples
Error Likely bugs or significant deviation Typos (close matches), completely wrong values
Warning Hardcoded values that should use tokens Inline styles, raw hex colors, arbitrary Tailwind values
Info Minor inconsistencies and suggestions Naming variations, deprecated but functional, suggested new tokens

AI-Specific Detection

AI code generation tools (Copilot, Claude, etc.) often introduce drift because they:

  • Don't have access to your design tokens
  • Generate "reasonable" values from training data
  • Copy patterns from similar but different projects

Buoy is designed to catch these issues before they're committed, making it ideal for teams using AI-assisted development.

Related