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 会自动检测你的框架并立即开始工作。

它能发现的问题

问题	示例
硬编码颜色	#ff0000，而非 var(--color-primary)
任意间距	padding: 17px，而非设计刻度
Tailwind 逃生通道	p-[13px]，而非 p-4
命名不一致	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 Agent

编码 Agent 会硬编码值，因为它们从不读取你的令牌文件。将 Buoy 作为 MCP 服务提供给它们：

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

Claude Code（以及任何 MCP 客户端）可使用四种工具：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 Agent 使用的 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 Agent 技能 — 适用于 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 为红色。每次扫描后五分钟内更新。

使用 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 Skills — 为 Claude Code 提供设计系统知识
• Claude Hooks — 在会话开始时自动注入上下文
• CLAUDE.md — 项目专属的 AI 指令

自我验证 Agent（Claude Code）

将 Claude Code 变成能自我纠正的 Agent。Claude 编写组件时，Buoy 会检查组件并自动将修正意见反馈给 Claude：

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

这会安装一个 PostToolUse hook，用于：

1. Claude 编写或编辑组件文件
2. Hook 对修改后的文件运行 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