Why AI coding tools ignore your design system

Your team adopted Claude Code, Cursor or Copilot, and UI work got faster almost overnight. A settings page that took a day now takes an hour. Then someone puts three of those new screens side by side, and they don't look like they came from the same company.

The buttons are slightly different shades of blue. One form uses your TextField component, another uses a raw <input>. The padding is 13px here and 15px there. Nobody did anything wrong: the AI simply doesn't know your design system exists.

This post explains why that happens, the new vocabulary you'll need to fix it, what it costs a company, and how to fix it, first by hand and then with Brandrail.

What brand drift looks like

Ask an AI coding tool for "a settings page with a save button" in a repo that has a design system, and you'll often get something like this:

<div style={{ padding: 13 }}>
  <input className="border rounded px-3 py-2" placeholder="Email" />
  <button className="bg-blue-500 hover:bg-blue-600 text-white rounded-md px-4 py-2">
    Save
  </button>
</div>

It works, and it passes review because it looks fine on its own. But your team has a Button component with a primary variant, a TextField with a label and error states, a spacing scale of 4, 8, 12, 16 and 24, and a brand colour that isn't Tailwind's blue-500. What you wanted was:

<Stack gap="md">
  <TextField label="Email" name="email" />
  <Button variant="primary" onClick={save}>Save</Button>
</Stack>

Each screen that drifts is a small thing. Hundreds of them, written by every developer's AI tool across every repo, is how a design system quietly stops being the system.

Why it happens

The model has never seen your design system

AI coding tools learned from public code. They know Material UI, Bootstrap and Tailwind's default palette extremely well, because those are everywhere. Your company's components and tokens are not in that training data, so the tool falls back to what it knows.

Your design system isn't where the AI looks

Tokens live in Figma. Usage rules live in a documentation site. Components live in a package the AI can see the name of, but not the intent of: which variant is for primary actions, which props are required, what replaces a raw <select>. An agent working on one file rarely goes looking for any of that.

Rules files help, but nothing checks them

Most tools now read an instructions file from the repo: CLAUDE.md for Claude Code, .cursor/rules for Cursor, .github/copilot-instructions.md for Copilot. Writing "always use our Button component" there helps. But it's prose, it goes stale as the design system changes, it has to be copied into every repo and every tool's format, and nothing verifies the AI actually followed it.

Most companies have more than one stack

A React app, an Angular app from a few years ago, a Vue admin, server-rendered templates in PHP. AI tools default to React examples, so the Angular and template code drifts fastest.

Review can't keep up

When AI tools multiply how much UI a team ships, code review becomes brand review. Reviewers catch some hard-coded colours, miss others, and stop commenting on spacing altogether.

New words you'll keep hearing

The vocabulary moved fast this year. Here's what matters for design systems:

• Agentic coding: the AI doesn't just autocomplete a line; it plans a change, edits several files and runs commands. Claude Code, Cursor's agent and Codex all work this way.
• Rules files: instructions the AI reads automatically in a repo, such as CLAUDE.md, AGENTS.md, .cursor/rules/*.mdc and .github/copilot-instructions.md.
• MCP (Model Context Protocol): an open standard that lets AI tools call external tools while they work. Instead of guessing, the AI can ask "which component should I use for a date picker?" and get a real answer.
• MCP server: a small program that provides those tools. It can run on the developer's own machine, so nothing leaves it.
• Design tokens: your design decisions as named values (color.brand.primary, space.md) that code uses instead of raw hex values and pixel numbers.
• Brand drift: the gap between your design system and what actually ships. AI tools make it grow faster.

What it costs a company

• Inconsistent product. Customers notice when screens don't match, even if they can't say why.
• Accessibility regressions. Invented colours fail contrast; raw elements skip the labels and states your components handle.
• Slower review. Senior people spend review time on colours and spacing instead of logic.
• Rework and migration debt. Every off-system screen is one more thing to fix later, on top of the Material or Bootstrap code you were already migrating away from.
• A design system that stops paying off. The value of a design system is reuse. If AI tools route around it, the investment erodes.

How to fix it yourself

You can get a long way without any new tool:

1. Make tokens real code. Export your tokens as CSS variables with meaningful names (--color-brand-primary, not --blue-500) and import them once at the app entry.
2. Write a rules file for each AI tool. List your components, their import paths and what each replaces ("use Button instead of <button>"), plus your spacing scale and colour tokens. Keep it short: the AI reads it on every request.
3. Give the AI the props. Agents invent props. Paste each component's real props, required ones marked, into the rules file or a doc the AI can read.
4. Lint for the obvious. A lint rule or CI check that fails on hex colours and arbitrary spacing in UI files catches a lot.
5. Check before merge. Add "uses design-system components and tokens" to your pull request checklist.

Where this breaks down is scale: keeping rules files in sync across every repo and five AI tools as the design system changes, keeping props accurate, and checking what the AI actually wrote rather than hoping it read the instructions.

How Brandrail fixes it

Brandrail connects your design system to every AI coding tool your team uses, and checks the result.

One command per repo. npx brandrail connect writes the rules files for Claude Code, Codex, Cursor, Copilot, Windsurf and Gemini, your tokens as CSS variables, and the MCP server config. Commit them and the whole team gets the same setup.

The AI asks before it writes. Brandrail's MCP server gives the AI your design system on demand: get_guidelines for the rules, get_design_tokens for colours and spacing, find_component and get_component_docs for the right component with its real props, and get_template for whole pages built from your components.

The AI checks itself. After writing UI, it calls validate_snippet, which runs the Brandrail checker and returns each violation with the fix: hard-coded colours, palette classes, off-scale spacing and radius, raw HTML where you have a component, other UI libraries, and props your components don't take. The AI fixes them before you see the code.

Every pull request gets a brand score. The same checker runs in the CLI, a GitHub Action and the GitHub App, with inline fixes on only the lines that changed.

Any framework. React, Angular, Vue, Web Components and plain HTML, plus PHP, Twig, Handlebars and Liquid templates. Each repo gets your components in its own framework.

Your code stays on your machine. The MCP server runs locally over stdio, and the CLI, MCP server and checker are open source under MIT.

One source of truth. Import your tokens from Figma or Tokens Studio, publish the Brand Kit, and Brandrail opens a sync pull request in every connected repo.

Try it

In any repo, with no account:

npx -y brandrail mcp

adds the MCP server with starter tokens. To use your own design system:

npx brandrail connect

There's a free plan for one repo and three people, and Team has a 14-day free trial. If you lead a design system and want to see it working on yours, email hello@brandrail.com.au and I'll connect it with you in a free 20-minute session.