Configuration

Buoy uses a .buoy.yaml file in your project root. Most settings are auto-detected, but you can customize everything.

Quick Start

npx ahoybuoy dock config

This generates a config based on your detected frameworks.

Config File

# .buoy.yaml

# Source scanning
sources:
  react:
    enabled: true
  vue:
    enabled: false
  svelte:
    enabled: false
  angular:
    enabled: false
  tailwind:
    enabled: true

# File patterns
include:
  - "src/**/*.{tsx,jsx,vue,svelte,css,scss}"
exclude:
  - "node_modules"
  - "dist"
  - "build"
  - "**/*.test.*"

# Design tokens reference
tokens:
  file: "design-tokens.json"   # Local file
  # OR
  figma:
    fileId: "your-figma-file-id"
    accessToken: $FIGMA_TOKEN

# Health thresholds
thresholds:
  minScore: 70                  # Minimum passing score
  maxHardcoded: 10              # Max allowed hardcoded values

# Severity rules
drift:
  promote:
    - type: hardcoded-color
      file: "src/checkout/**"
      severity: warning
      to: critical
      reason: "Checkout must use tokens"
  enforce:
    - type: close-match
      reason: "Typos are always critical"

# Health gate
health:
  failBelow: 70                   # Exit code 1 below this score

# Output settings
output:
  format: table                 # table | json | markdown

Source Options

React

sources:
  react:
    enabled: true
    include:
      - "src/**/*.tsx"
      - "src/**/*.jsx"
    extractInlineStyles: true
    extractStyledComponents: true

Tailwind

sources:
  tailwind:
    enabled: true
    config: "tailwind.config.js"      # Path to config
    detectArbitrary: true             # Flag arbitrary values like [#fff]

Vue / Svelte / Angular

sources:
  vue:
    enabled: true
    include:
      - "src/**/*.vue"
    extractScopedStyles: true
  svelte:
    enabled: true
    include:
      - "src/**/*.svelte"
  angular:
    enabled: true
    include:
      - "src/**/*.component.ts"

Token Configuration

Local Token File

tokens:
  file: "design-tokens.json"

Supports JSON (W3C format), CSS, and SCSS files.

Figma Integration

tokens:
  figma:
    fileId: "abc123xyz"
    accessToken: $FIGMA_TOKEN
    # Optional: specific pages/frames
    pages:
      - "Design Tokens"

See Token Configuration for setup.

Threshold Configuration

thresholds:
  minScore: 70               # CI fails below this score
  maxHardcoded: 10           # Max hardcoded values allowed
  maxCloseMatches: 0         # Zero tolerance for typos

Severity Rules: promote

Promote drift severity conditionally based on filters. When a drift signal matches a promote rule, its severity is elevated from one level to another. 

drift:
  promote:
    - type: hardcoded-color
      file: "src/checkout/**"
      severity: warning
      to: critical
      reason: "Checkout UI must use design tokens"

    - file: "src/components/shared/**"
      severity: warning
      to: critical
      reason: "Shared components set the standard"

Filter Fields

Field Type Description
type string Drift type (e.g. hardcoded-color, close-match)
severity string Current severity to match (warning, info)
file glob File path pattern (e.g. src/checkout/**)
component regex Component name pattern (e.g. Legacy.*)
token regex Token name pattern (e.g. color-primary)
value regex Hardcoded value pattern (e.g. #3b82f6)
to string Target severity (critical, warning)
reason string Explanation shown in output

Multiple fields in one rule combine with AND logic. Multiple rules use first-match-wins.

Severity Rules: enforce

Enforce rules set matching drift to critical unconditionally. Unlike promote, enforce rules have no severity filter and no to field — the result is always critical. 

drift:
  enforce:
    - type: close-match
      reason: "Typos must be fixed before merge"

    - file: "packages/design-system/**"
      reason: "The design system must be clean"

Enforce uses the same filter fields as promote except severity and to. In the severity pipeline, enforce runs after promote and overrides it.

Health Gate

Set a minimum health score threshold. When buoy drift check runs, it exits with code 1 if the score drops below the configured value. 

health:
  failBelow: 70    # Exit code 1 if health score < 70

This is config-based — no CLI flags required. Pairs well with --fail-on for layered CI gating. The --json output includes a health object with score, threshold, and passed fields when configured.

Environment Variables

Variable Description
FIGMA_TOKEN Figma API access token
GITHUB_TOKEN GitHub token for PR comments
BUOY_STRICT Enable strict mode (1 = enabled)

Ignoring Files

Add patterns to exclude:

exclude:
  - "node_modules"
  - "dist"
  - "build"
  - "**/*.test.*"
  - "**/*.stories.*"
  - "src/legacy/**"          # Ignore legacy code

Inline Ignores

Ignore specific lines in your code:

// buoy-ignore-next-line
const specialColor = '#custom123';

/* buoy-ignore */
const legacyStyles = {
  padding: '13px',
  color: '#abc123',
};

Related