buoy

Buoy

リリース前にデザインのずれを検出します。

AI コーディングツールは高速ですが、デザインシステムを把握していません。--color-primary があるのに #3b82f6 を記述したり、スペーシングの単位が 4 の倍数なのに padding: 17px を使ったりします。

Buoy はこうした問題を検出し、修正を支援します。

src/components/Button.tsx:24
  hardcoded-value: #3b82f6 → var(--color-primary) (92% match)

コードファーストのシステム可視化

リリース済みのコードが、デザインシステムの信頼できる情報源です。自社で管理するパッケージを宣言すると、Buoy で採用状況、管理されていない UI の範囲、コンポーネントやトークンを変更した場合の影響範囲を把握できます。Figma などのデザインツールは任意の入力として引き続き使用できますが、システムマップに必須ではありません。

# .buoy.yaml
project:
  name: acme

system:
  components:
    - packages/ui/src/**
  tokens:
    - packages/tokens/src/**
  owners:
    - name: Checkout
      paths:
        - apps/checkout/**

buoy system map                 # Canonical system vs unmanaged surface area
buoy system impact Button       # Consumers and migration risk for a change
buoy system impact color-primary --kind token

これを基盤として、クラウドでの採用傾向、廃止計画、AI 支援による反復作業のレポートを作成できます。すべての結果はコードから導き出され、リポジトリ内のパスと所有者に関連付けられます。

クイックスタート

# See your design system immediately (zero config)
npx ahoybuoy show all

# Add project configuration and local integrations when ready
npx ahoybuoy dock

設定は不要です。Buoy がフレームワークを自動検出し、すぐに動作を開始します。

検出する問題

問題	例
ハードコードされた色	var(--color-primary) ではなく #ff0000
任意のスペーシング	デザインスケールではなく padding: 17px
Tailwind の回避策	p-4 ではなく p-[13px]
命名の不整合	ButtonNew、ButtonV2、ButtonOld
未使用のコンポーネント	定義されているが、インポートもレンダリングもされていない
セマンティクスの不一致	同じプロパティの型が、一方では string、もう一方では number
パターンの繰り返し	同じ Tailwind クラスが 5 回以上コピー＆ペーストされている
フレームワークの乱立	同じコードベースで React、Vue、jQuery を併用
切り離されたコンポーネント	メインコンポーネントのないインスタンス

コマンド

buoy
├── show                    # Read design system info (for AI agents)
│   ├── components          # Components in codebase
│   ├── tokens              # Design tokens found
│   ├── drift               # Design system violations
│   ├── health              # Health score
│   ├── history             # Scan history
│   ├── config              # Current .buoy.yaml configuration
│   ├── skills              # AI agent skill files
│   ├── agents              # Configured AI agents
│   ├── context             # Design system context in CLAUDE.md
│   ├── hooks               # Configured hooks
│   ├── commands            # Installed slash commands
│   ├── graph               # Knowledge graph stats
│   ├── plugins             # Available scanners
│   └── all                 # Everything combined
├── drift                   # Drift detection and fixing
│   ├── scan                # Scan codebase for components/tokens
│   ├── check               # Pre-commit drift check
│   ├── fix                 # Suggest/apply fixes
│   └── ignore              # Ignore existing drift
│       ├── all             # Ignore all current drift (requires --reason)
│       ├── show            # View ignored drift signals
│       ├── add             # Add new drift to ignore list (requires --reason)
│       └── clear           # Remove ignore list
├── rescue                  # Complete measure → repair → guard → prove journey
│   ├── plan                # Build a local baseline and repair plan
│   ├── apply               # Apply reviewed safe fixes on a new branch
│   ├── verify              # Run detected typecheck/test scripts
│   ├── guard               # Record reviewed legacy drift with reasons
│   ├── report              # Generate JSON, Markdown, and HTML evidence
│   └── rollback            # Restore local pre-Rescue backups
├── dock                    # Dock tools into your project
│   ├── config              # Create .buoy.yaml
│   ├── skills              # Create AI agent skills
│   ├── agents              # Set up AI agents
│   ├── context             # Generate CLAUDE.md context
│   ├── hooks               # Set up hooks (--claude for self-validating AI)
│   ├── commands            # Install Claude slash commands
│   ├── plugins             # Show available scanners
│   ├── tokens              # Generate/export design tokens
│   │   ├── compare         # Compare token sources
│   │   └── import          # Import tokens from Figma/CSS
│   └── graph               # Build design system knowledge graph
│       └── learn           # Learn patterns from codebase
└── ahoy                    # Cloud features
    ├── login               # Authenticate
    ├── logout              # Sign out
    ├── status              # Account + bot + sync status
    ├── github              # Set up GitHub PR bot
    ├── gitlab              # Set up GitLab PR bot (soon)
    ├── billing             # Manage subscription
    └── plans               # Compare pricing

AI エージェント向け

コーディングエージェントが値をハードコードするのは、トークンファイルを読み取らないためです。Buoy を MCP サーバーとして利用させましょう。

npx @buoy-design/cli mcp install claude   # or cursor, codex, windsurf, all

Claude Code（およびあらゆる MCP クライアント）は、4 つのツールを利用できます。list_design_tokens、find_token_for_value（#1a73e8 → --color-primary）、check_ui_against_design_system（トークンと正確な行編集を含む、行単位のチェック）、design_system_context です。また Claude Code には、編集するすべてのスタイルファイルをチェックし、次の作業に進む前に修正内容を返す PostToolUse フックも用意されています。詳しくはdocs/integrations/mcpをご覧ください。

Claude Code では、プラグインにすべてが含まれています。/plugin marketplace add ahoybuoy/buoy を実行してから、/plugin install buoy@buoy を実行してください。

すべてのプルリクエストも確認するには、無料の GitHub App をインストールしてください。Buoy アカウントは不要です。

show コマンドは、AI エージェントが利用できる JSON を出力します。

# Get everything an AI agent needs
buoy show all --json

# Just drift signals
buoy show drift --json

# Components inventory
buoy show components --json

出力例：

{
  "components": [...],
  "tokens": [...],
  "drift": {
    "signals": [...],
    "summary": { "total": 12, "critical": 2, "warning": 7, "info": 3 }
  },
  "health": { "score": 78 }
}

はじめに

Rescue の一連の手順を完了する

buoy rescue plan
# Review .buoy/rescue/runs/<run-id>/report.html
buoy rescue apply --run <run-id> --approve
buoy rescue guard --run <run-id> --reason "Reviewed legacy baseline" --actor "Design systems team"
buoy rescue report --run <run-id>

Rescue では、判断が難しい検出結果はレビューのみとし、確信度の高い変更を適用した後に、検出されたプロジェクトのチェックを実行します。また、ロールバックに備えてローカルバックアップを保持します。コミット、プッシュ、プルリクエストの作成、ソースコードのアップロードは行いません。ワークフローの詳細はdocs/rescue.mdをご覧ください。

プロジェクトを設定する

buoy dock

次の項目を設定するスマートなガイドです。

1. .buoy.yaml — プロジェクトの設定
2. AI エージェントのスキル — Claude Code、Copilot など向け
3. CLAUDE.md のコンテキスト — デザインシステムのドキュメント
4. Git フック — コミット前のずれチェック

ずれの種類ごとに重大度を設定する

# .buoy.yaml
project:
  name: my-app

drift:
  severity:
    hardcoded-value: critical
    naming-inconsistency: warning

  # Ignore specific drift (filter by type, file, component, token, value, severity)
  ignore:
    - type: hardcoded-value
      file: "src/legacy/**"
    - severity: info

  # Promote matching drift to a higher severity
  promote:
    - type: hardcoded-value
      file: "src/components/**"
      to: critical
      reason: "Design system components must use tokens"

  # Enforce — always treat matching drift as critical
  enforce:
    - type: naming-inconsistency
      component: "^Button"
      reason: "Button naming is standardized"

health:
  # CI gate — exit code 1 if health score falls below threshold
  failBelow: 70

ずれの検出

クイックチェック

buoy drift check

高速で、コミット前フックに適しています。ずれが見つかった場合は、エラーコードで終了します。

詳細な分析

buoy show drift

{
  "drifts": [
    {
      "type": "hardcoded-value",
      "severity": "warning",
      "file": "src/components/Button.tsx",
      "line": 24,
      "message": "#3b82f6 should use var(--color-primary)",
      "suggestion": "var(--color-primary)"
    }
  ]
}

問題を修正する

buoy drift fix                    # Interactive fix suggestions
buoy drift fix --dry-run          # Preview changes
buoy drift fix --apply            # Apply reviewed high-confidence fixes

既存のドリフトを無視する

ブラウンフィールドプロジェクトでは、既存の問題は無視し、新たな問題のみを指摘します。

buoy drift ignore all -r "Legacy code before design system"     # Ignore all current drift with reason
buoy drift ignore add -r "Third-party components"               # Add new drift to ignore list
buoy drift ignore show                                          # View ignored drift with reasons
buoy drift check                                                # Only fails on new drift

ドリフトを無視する場合は、説明を必須とすることで、説明責任を維持します。

CI との統合

GitHub Actions

name: Design System Check
on: [pull_request]

jobs:
  buoy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
      - run: npx ahoybuoy drift check

デザイン健全性バッジ

Buoy Cloud によるスキャンを受けたリポジトリでは、README にリアルタイムのスコアバッジを表示できます。

[![design health](https://api.buoy.design/badges/OWNER/REPO.svg)](https://buoy.design)

80 以上は緑、60 以上は黄色、60 未満は赤で表示されます。スキャン後、5 分以内に更新されます。

Buoy Cloud による PR コメント

# Set up GitHub PR bot
buoy ahoy login
buoy ahoy github

GitHub ボットがドリフト分析を PR に自動でコメントします。

AI ガードレール

AI コーディングアシスタント（Copilot、Claude、Cursor）をデザインシステムに準拠させます。

# Set up AI agents with design system context
buoy dock agents

作成されるもの：

• AI スキル — Claude Code 向けのデザインシステムの知識
• Claude Hooks — セッション開始時にコンテキストを自動で挿入
• CLAUDE.md — プロジェクト固有の AI 向け指示

自己検証エージェント（Claude Code）

Claude Code を自己修正するエージェントにします。Claude がコンポーネントを作成すると、Buoy がチェックし、修正内容を自動でフィードバックします。

buoy mcp install claude     # MCP server + line-level hook (recommended)
buoy dock hooks --claude    # hook only, component-level

次の処理を行う PostToolUse フックをインストールします。

1. Claude がコンポーネントファイルを作成／編集する
2. フックが変更されたファイルに対して buoy drift check を実行する
3. ドリフトが検出された場合、フィードバックが Claude に返される
4. Claude がプロンプトなしで自己修正する

Claude に返されるフィードバックの例：

⚠️ Design drift detected in Button.tsx:

• hardcoded-value: Component "Button" has 3 hardcoded colors: #3b82f6, #ffffff, #1e40af

Run `buoy show drift` for full details.

React、Vue、Svelte、Angular のコンポーネントに対応しています。テストファイルと設定ファイルはスキップします。

設定

設定なしで動作しますが、設定を保存することもできます。

buoy dock config

.buoy.yaml を作成します。

project:
  name: my-app

sources:
  react:
    enabled: true
    include:
      - src/**/*.tsx
    exclude:
      - "**/*.test.*"
  tokens:
    enabled: true
    files:
      - design-tokens.css

Buoy Cloud

ドリフト検出をクラウドで実行します。

buoy ahoy login             # Authenticate
buoy ahoy status            # View account, bot, sync status
buoy ahoy github            # Set up GitHub PR bot
buoy ahoy billing           # Manage subscription

機能：

• PR ボット — プルリクエストに自動でコメント
• ダッシュボード — ドリフトの推移を時系列で確認
• チーム同期 — チームメンバー間で結果を共有

対応フレームワーク

コンポーネント： React、Vue、Svelte、Angular、Lit、Stencil、Alpine、HTMX

テンプレート： Blade、ERB、Twig、Razor、Jinja、Handlebars、EJS、Pug

トークン： CSS 変数、SCSS、Tailwind の設定、JSON、Style Dictionary

デザインツール： Figma（プラグイン＋API 統合）

考え方

デフォルトでは通知し、選択に応じてブロックします。

Buoy は、作業の妨げにならずに状況を示します。チームは準備ができた段階で、適用を開始できます。

buoy show drift             # Just show me
buoy drift check            # Pre-commit check (fails on critical)
buoy drift check --fail-on warning    # Fail on warning or above
buoy drift check --fail-on none       # Never fail (report only)
buoy drift check --staged             # Only check staged files

開発

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run tests
pnpm test

# Run CLI locally
node apps/cli/dist/bin.js show all

パッケージ

パッケージ	説明
@buoy-design/cli	コマンドラインインターフェース
@buoy-design/core	ドメインモデルとドリフト検出エンジン
@buoy-design/scanners	フレームワーク固有のコードスキャナー
ahoybuoy	CLI ラッパー（npx ahoybuoy）
buoy-design	CLI ラッパー（npx buoy-design）

ライセンス

MIT