AI Guardrails

Development has tests. Design systems need the same thing. Buoy provides the missing feedback loop that keeps AI-generated code aligned with your design system.

The Problem with AI Code Generation

AI tools like Copilot, Claude, and ChatGPT are incredibly productive. They can scaffold components in seconds. But they have a fundamental limitation: they don't know your design system.

When you ask AI to "create a card component," it generates something reasonable:

// AI-generated code
.card {
  padding: 15px;
  border-radius: 6px;
  background-color: #f8f9fa;
  box-shadow: 0 2px 4px rgba(0,0,0,0.1);
}

This code works. It looks fine. But every value is wrong:

  • 15px padding → your system uses 16px
  • 6px radius → your system uses 8px
  • #f8f9fa → your gray is #f9fafb
  • Hardcoded shadow → you have a shadow-sm token

None of this triggers an error. The component renders. The PR gets approved. Your design system just got a little more fragmented.

Development Has Solved This

In code, we have layers of automated feedback:

Tool What It Catches When
TypeScript Type errors, missing properties As you type
ESLint Code style, bad patterns On save / in CI
Tests Broken functionality On commit / in CI
Build Import errors, syntax issues On deploy

If AI generates code with a type error, TypeScript catches it immediately. If it uses a deprecated API, ESLint flags it. If it breaks a feature, tests fail.

Design systems have none of this. Until now.

Buoy: The Missing Layer

Buoy adds design system validation to your feedback loop:

Tool What It Catches When
TypeScript Type errors As you type
ESLint Code patterns On save
Buoy Design drift On commit / in CI
Tests Functionality On commit

Now when AI generates padding: 15px, Buoy catches it: 

$ buoy ci

Design System Check Failed

~ Hardcoded Value
  File: src/components/Card.tsx:3
  Found: padding: 15px
  Expected: 16px (--spacing-4)

Exit code: 1

Source of Truth for AI

The key insight: AI needs boundaries, not just examples.

Giving AI your component library helps, but it's not enough. AI will still improvise values when it doesn't find an exact match. It will still generate "close enough" colors and spacing.

Buoy provides the boundary. It's the automated check that says "this value doesn't exist in the design system" before code ships.

How Teams Use This

1. Set a Health Threshold

buoy ci --threshold 70

PRs must maintain at least 70% design system health to merge.

2. Block on New Drift

buoy ci --strict

Zero tolerance: any new hardcoded value fails the build.

3. Get PR Comments

buoy ci --github-comment

Buoy comments on PRs showing exactly what drifted and how to fix it.

Buoy in Agent Workflows

AI agents like Claude Code, Cursor, and Copilot Workspace don't just suggest code—they write entire features autonomously. This changes everything about how we maintain design systems.

The Agent Loop

Modern AI agents work in a loop: write code, run tests, fix errors, repeat until the tests pass. Buoy plugs directly into this loop: 

Agent writes component
       ↓
   Tests pass ✓
       ↓
   Buoy runs ✗  ←  "padding: 15px not in design system"
       ↓
Agent fixes drift
       ↓
   Buoy runs ✓
       ↓
   Code ships

Without Buoy, the agent has no signal that the design is wrong. Tests pass, types check, the code works—so the agent moves on. Drift accumulates silently.

Teaching Agents Your System

Buoy's output is designed to be actionable for both humans and agents: 

~ Hardcoded Value
  File: src/components/Card.tsx:3
  Found: padding: 15px
  Expected: 16px (--spacing-4)

  Suggestion: Replace with var(--spacing-4) or theme.spacing[4]

When an agent sees this output, it knows exactly what to fix. The agent doesn't need to understand your entire design system—it just needs to follow Buoy's suggestions.

Pre-commit Hooks

Add Buoy to your pre-commit workflow so agents get feedback before pushing: 

# .husky/pre-commit
buoy ci --strict

Now when an agent runs git commit, Buoy blocks the commit if there's drift. The agent sees the error, fixes it, and tries again.

Agent Instructions

Add Buoy to your agent's system prompt or project instructions: 

# CLAUDE.md / .cursorrules / copilot-instructions.md

## Design System

Before committing UI changes, run `buoy ci` to check for design drift.
If Buoy reports issues, fix them before committing.

Our design tokens:
- Spacing: 4px, 8px, 16px, 24px, 32px
- Colors: Use CSS variables from tokens.css
- Radii: 4px, 8px, 16px

This gives agents context about your system AND a tool to verify their work.

The AI-Era Design System

AI is writing more of our code every day. That's not going to change. What needs to change is how we validate that code.

A modern design system needs:

  • Tokens — The design decisions (you have this)
  • Components — The implementation (you have this)
  • Validation — Automated enforcement (this is Buoy)

Without validation, your tokens and components are suggestions. With Buoy, they become requirements.

Related