buoy drift
Detect design drift in your codebase. Scan for issues, inspect each drift signal, apply fixes, and manage ignore rules for intentional exceptions.
Usage
terminal
$ buoy drift <command> [options]
Commands
scan Scan your codebase for design system usage and drift signals check Show detailed drift signals with severity and type fix Suggest and apply fixes for drift issues ignore Ignore specific drift signals by file, type, component, or value buoy drift scan
Scan your codebase for design system usage. Zero-config auto-detection finds components, tokens, and patterns. Results are cached for fast repeat runs.
terminal
$ buoy drift scan [options]
Options
-s, --source <path> Source directory to scan (default: auto-detected) --json Output as JSON for scripting -v, --verbose Show detailed scan progress and per-file results --no-persist Don't save results to scan history --no-cache Bypass cache and force a full re-scan --clear-cache Clear the scan cache before running Examples
Basic scan
terminal
$ buoy drift scan
Scanning project...
Auto-detected:
Framework: React
Styling: Tailwind CSS
Source: src/
Scanned 84 files in 1.2s
Results
───────
Components: 42 detected
Tokens: 67 resolved
Drift signals: 23
Health score: 72/100
Cache: saved to .buoy/cache.json (next scan will be faster)
Scan a specific directory
terminal
$ buoy drift scan -s packages/ui/src
Scanning packages/ui/src...
Scanned 28 files in 0.6s
Results
───────
Components: 15 detected
Tokens: 34 resolved
Drift signals: 8
Health score: 81/100
Verbose output
terminal
$ buoy drift scan -v
Scanning project...
Auto-detected:
Framework: React
Styling: Tailwind CSS
Source: src/
✓ src/components/Button.tsx 8 tokens, 0 drift
✓ src/components/Card.tsx 6 tokens, 2 drift
✓ src/components/Badge.tsx 4 tokens, 1 drift
✓ src/components/Modal.tsx 5 tokens, 0 drift
...80 more files
Scanned 84 files in 1.4s
Results
───────
Components: 42 detected
Tokens: 67 resolved
Drift signals: 23
Health score: 72/100
Auto-detection
buoy drift scan works with zero configuration. It auto-detects your framework,
styling approach, and source directory. Supported frameworks include React, Vue,
Svelte, Angular, and vanilla HTML/CSS.
buoy drift check
Show detailed information about each instance where code diverges from your design system. Use in CI pipelines for automated drift detection.
terminal
$ buoy drift check [options]
Options
--type <type> Filter by drift type (color, spacing, typography) --severity <level> Filter by severity (high, medium, low) --file <path> Check specific file only --json Output as JSON for scripting --include <glob> Include additional file patterns --exclude <glob> Exclude file patterns Example Output
terminal
$ buoy drift check
Drift Analysis
──────────────
~ Hardcoded Value
Component: Card
Location: src/components/Card.tsx:14
Issue: backgroundColor: #f9fafb (not a design token)
Actions:
1. Replace with design token
2. Example: var(--color-gray-50) or theme.colors.gray[50]
~ Close Match (Possible Typo)
Component: Button
Location: src/components/Button.tsx:28
Issue: color: #3b83f6 (close to #3b82f6)
Actions:
1. Verify if this is intentional
2. If typo, replace with #3b82f6
──────────────────────────────────────
Total: 47 drift signals found
High severity: 12
Medium severity: 23
Low severity: 12
Filtering Examples
<div class=""># Only color issues</div><div class="">buoy drift check --type color</div><div class=""></div><div class=""># Only high severity</div><div class="">buoy drift check --severity high</div><div class=""></div><div class=""># Specific file</div><div class="">buoy drift check --file src/components/Card.tsx</div><div class=""></div><div class=""># Combine filters</div><div class="">buoy drift check --type spacing --severity high</div>What It Scans
React Components, props, inline styles Vue Components, scoped styles Svelte Components, style blocks Angular Components, stylesheets Tailwind Config tokens, arbitrary values CSS/SCSS Custom properties, values buoy drift fix
Automatically fix design drift issues in your codebase. Replaces hardcoded values with design tokens and applies other safe transformations.
terminal
$ buoy drift fix [options]
Options
--apply Apply fixes to source files --dry-run Show detailed diff without applying changes -c, --confidence <level> Minimum confidence level: exact, high, medium, low (default: high) -t, --type <types> Fix types to include (comma-separated: hardcoded-color, hardcoded-spacing) -f, --file <patterns> File glob patterns to include (comma-separated) --exclude <patterns> File glob patterns to exclude (comma-separated) --backup Create .bak backup files before modifying --json Output as JSON --force Skip safety checks Examples
Preview fixes (dry run)
terminal
$ buoy drift fix --dry-run
Found 18 auto-fixable issues
Button.tsx:12
- color: '#3b82f6'
+ color: 'var(--color-primary)'
Card.tsx:8
- padding: '16px'
+ padding: 'var(--spacing-md)'
Run with --apply to apply these changes.
Apply fixes
terminal
$ buoy drift fix --apply
Applying 18 fixes...
✓ Button.tsx: 3 fixes applied
✓ Card.tsx: 2 fixes applied
✓ Modal.tsx: 5 fixes applied
... and 8 more files
18 issues fixed. 5 need manual review.
Fix only color issues
terminal
$ buoy drift fix --apply --type hardcoded-color
Fix specific files
terminal
$ buoy drift fix --apply --file "src/components/**/*.tsx"
Confidence Levels
Each fix suggestion includes a confidence score indicating how safe it is to apply:
exact 100% — Value exactly matches a design token — safest to auto-apply high 95-99% — Very close match, safe to auto-apply medium 70-94% — Close match, review recommended low <70% — Ambiguous, manual review required By default, --apply only applies high and exact confidence fixes.
buoy drift ignore
Ignore specific drift signals so they don't appear in checks or affect your health score. More targeted than baselines — filter by file path, drift type, component name, or specific value.
terminal
$ buoy drift ignore <command> [options]
Commands
all Ignore all current drift signals add Add current drift signals to the ignore list show View all ignored signals and their filters clear Remove the ignore list entirely Options
These flags work with all and add to target specific signals:
--file <glob> Ignore drift in matching files or folders (e.g. "src/legacy/**") --type <type> Ignore a specific drift type (e.g. hardcoded-color) --component <name> Ignore drift from a specific component (e.g. "LegacyCard") --value <value> Ignore a specific hardcoded value (e.g. "#ff0000") Examples
Ignore all drift in legacy code
terminal
$ buoy drift ignore add --file "src/legacy/**"
Added ignore rule: files matching "src/legacy/**"
14 drift signals will be hidden.
Ignore a specific drift type
terminal
$ buoy drift ignore add --type hardcoded-color
Added ignore rule: type hardcoded-color
9 drift signals will be hidden.
Ignore drift from a single component
terminal
$ buoy drift ignore add --component "LegacyCard"
Added ignore rule: component "LegacyCard"
3 drift signals will be hidden.
Ignore a specific value
terminal
$ buoy drift ignore add --value "#ff0000"
Added ignore rule: value "#ff0000"
2 drift signals will be hidden.
Combine filters
<div class=""># Ignore hardcoded colors in legacy files</div><div class="">buoy drift ignore add --file "src/legacy/**" --type hardcoded-color</div><div class=""></div><div class=""># Ignore a specific value in a specific component</div><div class="">buoy drift ignore add --component "OldButton" --value "#333"</div>View ignored signals
terminal
$ buoy drift ignore show
Ignore Rules
────────────
1. files matching "src/legacy/**" (14 signals)
2. type: hardcoded-color (9 signals)
3. component: "LegacyCard" (3 signals)
Total: 26 signals ignored
Clear all ignore rules
terminal
$ buoy drift ignore clear
Ignore list removed. All drift signals will be shown.
Severity Pipeline
When buoy drift check runs, severity rules from .buoy.yaml are applied
in a fixed order before results are displayed:
1. Promote Conditional severity upgrades. Matches drift by type, file, component, token, or value and elevates severity (e.g. warning → critical). 2. Enforce Unconditional critical. Overrides any promote result. If enforce matches, the drift is critical — no negotiation. 3. Ignore The escape hatch. Ignored drift is excluded entirely, even if promoted or enforced.
Configure these in your .buoy.yaml under drift.promote, drift.enforce,
and drift.ignore. See Configuration for full details.
Health gate
When health.failBelow is configured, buoy drift check also exits with code 1
if the health score drops below the threshold. The --json output includes a health object:
<div class="">{</div><div class=""> "drifts": [...],</div><div class=""> "health": {</div><div class=""> "score": 68,</div><div class=""> "threshold": 70,</div><div class=""> "passed": false</div><div class=""> }</div><div class="">}</div>Drift Types
hardcoded-value Raw values instead of design tokens close-match Values near tokens (likely typos) naming-inconsistency Component names that don't follow conventions deprecated-pattern Usage of deprecated design patterns