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 suggestions

Severity Levels

Level Description Examples
High Likely bugs or significant deviation Typos (close matches), completely wrong values
Medium Hardcoded values that should use tokens Inline styles, raw hex colors
Low Minor inconsistencies Naming variations, deprecated but functional

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