buoy — Claude Code MCP server: keep the agent inside your design system
Gives a coding agent your tokens and component rules, then flags hardcoded colors and off-scale spacing with a line-level fix.
claude mcp add buoy -- npx -y @buoy-design/cliWhat buoy does
Your agent never reads the token file, so it writes #3b82f6 where the project expects var(--color-primary), or sets 17px padding against a scale of fours. Buoy reports that mismatch and hands back the token plus the exact line edit. It runs as an MCP server with four tools: list_design_tokens, find_token_for_value, check_ui_against_design_system and design_system_context.
Nothing to configure at the start. npx ahoybuoy show all dumps detected components, tokens and drift; npx ahoybuoy dock writes .buoy.yaml and wires the local pieces. That YAML lists paths for components, tokens and owning teams, and buoy system map plus buoy system impact read from it. In Claude the package also registers a PostToolUse hook: every style file the agent touches gets checked before it continues.
Scans, fixes and the system map work without an account; the hosted PR bot and sync sit behind buoy ahoy login. Bring it in early. buoy rescue can plan repairs, land reviewed fixes on a branch and produce an evidence report, but the debt it works through is the debt already in the tree.
What it helps with
- replace hardcoded colors with design tokens
- catch padding values outside the spacing scale
- map the design system against unmanaged UI surface
- see who consumes a component before changing it
- run a style check before committing
Example prompts for the agent
- Connect buoy and check
src/components/Button.tsxfor hardcoded colors - Use buoy to find the token behind
#1a73e8 - Run
buoy system impact Buttonand list the consumers
How to install buoy
Platform CLI
claude mcp add buoy -- npx -y @buoy-design/cliPlatform CLI
codex mcp add buoy -- npx -y @buoy-design/cliConfig file
{
"mcpServers": {
"buoy": {
"command": "npx",
"args": [
"-y",
"@buoy-design/cli"
]
}
}
}Config file
{
"servers": {
"buoy": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@buoy-design/cli"
]
}
}
}Platform CLI
gemini mcp add buoy npx -y @buoy-design/cliStep by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about buoy
How do I install buoy in Claude Code?
Run claude mcp add buoy -- npx -y @buoy-design/cli. The agent then gets the design system tools. For the hook, use npx ahoybuoy dock hooks --claude.
What does buoy do?
It compares your code against declared tokens and components, catching fixed values, arbitrary spacing and components nothing imports. Each hit comes with the matching token and the line to change.
Does buoy require Figma or a paid account?
No. Shipped code is the source of truth and Figma stays optional. Local scans and fixes need no account; buoy ahoy login is for the hosted PR bot and sync.
