buoy dock
Dock Buoy into your project. With no arguments, runs an interactive walkthrough that configures your project, sets up agents, and installs hooks. Use subcommands to set up individual pieces.
Usage
terminal
$ buoy dock [command] [options]
Commands
(default) Run interactive walkthrough (config → agents → hooks) config Create or update .buoy.yaml configuration agents Set up AI agent files (.claude/agents/) skills Install Buoy skills (.claude/skills/) context Generate CLAUDE.md with design system context hooks Set up pre-commit and CI hooks commands Manage Claude Code slash commands plugins Manage scanners and framework plugins tokens Generate, compare, and import design tokens graph Build and query the design system knowledge graph Options
-y, --yes Accept all defaults without prompting --json Output results as JSON -f, --force Overwrite existing files Examples
Interactive walkthrough
terminal
$ buoy dock
Detecting project configuration...
Detected:
Framework: React
Styling: Tailwind CSS
Components: src/components/
Step 1/3: Configuration
✓ Created .buoy.yaml
Step 2/3: AI Agents
✓ Created .claude/agents/design-reviewer.md
✓ Created .claude/agents/drift-fixer.md
Step 3/3: Hooks
✓ Created .claude/commands/buoy-check.md
✓ Updated .claude/settings.local.json
Buoy is docked! Run 'buoy drift check' to scan your codebase.
buoy dock config
terminal
$ buoy dock config
Detecting project configuration...
Detected:
Framework: React
Styling: Tailwind CSS
Components: src/components/
✓ Created .buoy.yaml
buoy dock agents
terminal
$ buoy dock agents
✓ Created .claude/agents/design-reviewer.md
✓ Created .claude/agents/drift-fixer.md
Agents are ready. Use them in Claude Code with /agent.
buoy dock skills
terminal
$ buoy dock skills
✓ Created .claude/skills/design-system.md
✓ Created .claude/skills/drift-check.md
Skills installed. Claude Code will use them automatically.
buoy dock context
Scans your codebase for components and tokens, then generates CLAUDE.md with design system context so AI tools understand and follow your design system.
terminal
$ buoy dock context
Analyzing design system...
✓ Generated CLAUDE.md with design system rules
- 67 tokens documented
- 42 components listed
- Anti-patterns defined
AI coding tools read these files to understand your design system. When you ask "Build a card component", the AI will:
- Check your existing Card component (if any)
- Use your color tokens instead of hardcoding
#3b82f6 - Follow your spacing scale instead of arbitrary values
- Match your naming conventions
buoy dock hooks
terminal
$ buoy dock hooks
✓ Created .claude/commands/buoy-check.md
✓ Updated .claude/settings.local.json
✓ Created .git/hooks/pre-commit
Hooks installed:
Pre-commit: drift check before each commit
Claude Code: self-validating AI hooks
Non-interactive setup
terminal
$ buoy dock -y
✓ Created .buoy.yaml
✓ Created .claude/agents/design-reviewer.md
✓ Created .claude/agents/drift-fixer.md
✓ Created .claude/commands/buoy-check.md
✓ Updated .claude/settings.local.json
Buoy is docked!
Force overwrite
terminal
$ buoy dock config -f
Overwriting existing .buoy.yaml...
✓ Updated .buoy.yaml
buoy dock commands
Install Buoy's slash commands to Claude Code. These commands give you quick access to design system workflows directly from Claude Code's command palette.
terminal
$ buoy dock commands list
terminal
$ buoy dock commands install
Subcommands
list List available Buoy slash commands and installation status install Install commands to ~/.claude/commands/ Options
--dry-run Show what would be installed without writing files --json Output result as JSON Available Commands
/contribution-loop
Autonomous workflow for finding repos with design drift and generating PRs to fix them. Runs through discovery, scanning, analysis, and PR generation phases.
Phases:
- Discovery — Find repos using design systems on GitHub
- Scanning — Run Buoy to detect drift
- Analysis — Use agents to assess fixability
- Triage — Classify as slam-dunk, review, or skip
- Generation — Create PR with full context
- Review — Human approval before submission
Example Output
terminal
$ buoy dock commands list
Available Buoy Commands
/contribution-loop not installed
Run `buoy dock commands install` to install all commands
terminal
$ buoy dock commands install
✓ Installed slash commands:
/contribution-loop
Commands installed to: ~/.claude/commands/
Restart Claude Code to use them
Commands vs Skills
Commands are user-invocable — you type /contribution-loop
in Claude Code to trigger them. Skills are AI-invocable — Claude
automatically loads them when relevant.
Use buoy dock context to create skills, and buoy dock commands install
to install slash commands.
buoy dock plugins
Manage scanners and framework plugins. List built-in and installed plugins, or get suggestions based on your project's detected frameworks.
terminal
$ buoy dock plugins <command>
Subcommands
list List built-in scanners and installed plugins suggest Detect frameworks and recommend plugins List plugins
terminal
$ buoy dock plugins list
Built-in Scanners
─────────────────
Scanner Status Description
color active Detect hardcoded color values
spacing active Detect hardcoded spacing values
typography active Detect hardcoded font sizes and weights
naming active Check naming conventions
z-index active Detect arbitrary z-index values
Installed Plugins
─────────────────
Plugin Version Description
@buoy/tailwind 0.3.23 Tailwind CSS utilities and class scanning
@buoy/react 0.3.23 React component detection and JSX parsing
Suggest plugins
terminal
$ buoy dock plugins suggest
Detecting project frameworks...
Detected:
React 18.2.0
Tailwind CSS 3.4.1
Storybook 7.6.0
Recommended Plugins
───────────────────
Plugin Why
@buoy/tailwind Tailwind detected — scan utility classes for drift
@buoy/react React detected — parse JSX for component patterns
@buoy/storybook Storybook detected — validate stories against tokens
Install all recommended plugins?
buoy dock -y
buoy dock tokens
Generate design tokens from values detected in your codebase. Outputs to CSS variables, JSON, Tailwind config, or AI-friendly context.
terminal
$ buoy dock tokens [options]
Options
-o, --output <path> Output file path (auto-detected if not specified) --format <format> Output format: css, json, tailwind, ai-context (auto-detected) --dry-run Preview without writing files --prefix <prefix> Prefix for CSS custom properties (e.g., "ds-") Examples
Generate CSS variables
terminal
$ buoy dock tokens --format css
:root {
--color-primary: #3b82f6;
--color-secondary: #64748b;
--spacing-sm: 8px;
--spacing-md: 16px;
--spacing-lg: 24px;
}
Generate Tailwind extension
terminal
$ buoy dock tokens --format tailwind -o tailwind.tokens.js
Generate AI context
terminal
$ buoy dock tokens --format ai-context
Use for AI agents to understand available tokens with usage context.
Output Formats
- css - CSS custom properties (:root variables)
- json - Standard JSON token format
- tailwind - Tailwind CSS theme extension
- ai-context - Markdown with token intent and usage
Free PDF
Planning a design token migration?
Step-by-step playbook for migrating from hardcoded values to design tokens. Avoid the common pitfalls.
Check your email for the playbook!
Something went wrong. Please try again.
No spam. Unsubscribe anytime.
Compare token sources
Compare your codebase values against a design tokens file. Identifies which values in your code don't match any defined tokens.
terminal
$ buoy dock tokens compare <tokens-file> [options]
<tokens-file> Path to design tokens file (JSON, CSS, or SCSS) required --json Output as JSON for scripting -v, --verbose Show per-file breakdown and usage frequency details --strict Fail if any unmatched values found Supported Token Formats
Design Tokens JSON (W3C format)
<div class="">{</div><div class=""> "color": {</div><div class=""> "primary": { "$value": "#3b82f6" },</div><div class=""> "secondary": { "$value": "#64748b" }</div><div class=""> },</div><div class=""> "spacing": {</div><div class=""> "sm": { "$value": "8px" },</div><div class=""> "md": { "$value": "16px" }</div><div class=""> }</div><div class="">}</div>Tokens Studio / Figma Export
<div class="">{</div><div class=""> "colors": {</div><div class=""> "blue-500": "#3b82f6",</div><div class=""> "gray-500": "#64748b"</div><div class=""> }</div><div class="">}</div>CSS Custom Properties
<div class="">:root {</div><div class=""> --color-primary: #3b82f6;</div><div class=""> --spacing-md: 16px;</div><div class="">}</div>Example Output
terminal
$ buoy dock tokens compare design-tokens.json
Comparing against design-tokens.json...
Token Coverage: 87%
───────────────────
Colors (78% coverage)
✓ 18 values match tokens
✗ 5 values not in tokens:
#f9fafb (used 3 times in 2 files)
#374151 (used 2 times in 1 file)
#3b83f6 (used 1 time) ← typo? close to #3b82f6
Spacing (86% coverage)
✓ 12 values match tokens
✗ 2 values not in tokens:
15px (used 4 times in 3 files) ← close to 16px
13px (used 1 time)
Import tokens
Import design tokens from external files. Supports JSON (DTCG, Tokens Studio, Style Dictionary) and CSS formats.
terminal
$ buoy dock tokens import <file> [options]
file Token file to import (JSON, CSS) required -o, --output <path> Output file path (default: design-tokens.css) -f, --format <format> Output format: css, json, scss (default: css) --dry-run Preview import without writing files terminal
$ buoy dock tokens import tokens-studio-export.json
Importing tokens...
Found 67 tokens:
- 24 colors
- 12 spacing
- 8 typography
- 23 other
✓ Created design-tokens.css
buoy dock graph
Build and query a knowledge graph of your design system. Understand relationships between components, tokens, and patterns.
terminal
$ buoy dock graph <command> [options]
Commands
build Build the knowledge graph from the codebase (persists to .buoy/graph.json) learn Analyze drift history for repeat patterns and learnings query <question> Query the knowledge graph export Export the graph for visualization stats Show graph statistics Options
--incremental Only rebuild nodes for changed files (faster rebuilds) --json Output as JSON Examples
Build the graph
terminal
$ buoy dock graph build
Building knowledge graph...
Nodes: 156
- 42 components
- 67 tokens
- 47 patterns
Edges: 312 relationships
Graph saved to .buoy/graph.json
Query the graph
terminal
$ buoy dock graph query "What components use the primary color?"
Components using --color-primary:
- Button (3 usages)
- Link (2 usages)
- Badge (1 usage)
- Tab (1 usage)
Learn from drift history
Analyze your drift history to surface repeat patterns. Shows which mistakes you keep making so you can address the root cause.
terminal
$ buoy dock graph learn
Your Repeat Mistakes
● Hardcoded Value in Button (5x)
Files: src/Button.tsx, src/IconButton.tsx, src/LinkButton.tsx
Fix: Use var(--color-primary) instead
● Arbitrary Spacing in Card (3x)
Files: src/Card.tsx, src/CardHeader.tsx
Fix: Use spacing.4 instead
Analyzed 10 scans, 47 total drifts
Found 3 repeat patterns
Generated Files
- .buoy.yaml — Main configuration file
- .claude/skills/ — Buoy skills for Claude Code
- .claude/agents/ — AI agent definitions
- .claude/commands/ — Slash commands for Claude Code
- CLAUDE.md — Design system context for AI tools
Related
- buoy show — View what's configured
- buoy drift — Detect and fix drift
- Claude Code — AI integration details
- AI Guardrails — Full guide