← All posts

Keep AI-generated UI on brand with commit and PR checks

Context helps AI tools follow your design system; checks catch what slips. Set up Stylelint, ESLint and CI checks for AI-written UI, step by step.

Thiago Baptistella · · 5 min read

Giving your AI coding tool your design system is half the job. Put your tokens in a file it can read, write the rules into CLAUDE.md or your Cursor rules, connect an MCP server, and Claude Code or Cursor will get it right most of the time.

Most of the time isn't every time. A long session drifts from its instructions, a new developer skips the setup, someone pastes a snippet from an old project. Context reduces drift. It doesn't stop it.

The other half of the job is a check that runs on every commit and every pull request, whoever (or whatever) wrote the code. This guide sets one up with tools you probably already have, then shows the shortcut.

Step 1: Turn "on brand" into rules a machine can check

"Follow the design system" can't be checked. These can:

  • No hard-coded colours: every colour comes from a token.
  • Spacing and corner radius only from your scale.
  • Only the fonts in your brand.
  • Your <Button> instead of a raw <button>.
  • No imports from UI libraries you've ruled out.
  • Every image has alt text.

Write your list down before you configure anything. Each item becomes a lint rule, and the same list becomes the rules section of your CLAUDE.md, so the AI and the check agree on what "right" means.

Step 2: Check your CSS with Stylelint

Stylelint's built-in rules cover colours and scales. color-no-hex bans hex values, color-named bans red and friends, and declaration-property-value-allowed-list limits a property to the values you allow:

{
  "ignoreFiles": ["src/tokens.css"],
  "rules": {
    "color-no-hex": true,
    "color-named": "never",
    "declaration-property-value-allowed-list": {
      "/^(padding|margin|gap)$/": ["/^var\\(--space-/", "0", "auto"],
      "border-radius": ["/^var\\(--radius-/", "0", "50%"]
    }
  }
}

Your tokens file is the one place hex values belong, so it's ignored. Shorthand values with several parts, like padding: 0 var(--space-4), need looser patterns, and that's where this starts to get fiddly.

Run it with npx stylelint "src/**/*.css".

Step 3: Make the wrong Tailwind classes disappear

If you use Tailwind v4, the simplest check is to make off-brand classes not exist. Reset the colour namespace in @theme and define only your own colours:

@import "tailwindcss";

@theme {
  --color-*: initial;
  --color-primary: #2563eb;
  --color-surface: #ffffff;
  --color-text: #111827;
}

Now bg-blue-500 generates nothing and only bg-primary works. Tailwind doesn't fail the build on an unknown class, so the AI's mistake shows up as an unstyled button rather than an error. A reviewer will notice, but nothing stops the merge.

Step 4: Check components and imports with ESLint

Two built-in ESLint rules go a long way: no-restricted-imports for libraries you've ruled out, and no-restricted-syntax for patterns like raw buttons and hex strings:

// eslint.config.js
export default [
  {
    files: ["src/**/*.{jsx,tsx}"],
    rules: {
      "no-restricted-imports": ["error", {
        paths: [{ name: "@mui/material", message: "Use @acme/ui instead." }],
      }],
      "no-restricted-syntax": ["error",
        {
          selector: "JSXOpeningElement[name.name='button']",
          message: "Use <Button> from @acme/ui.",
        },
        {
          selector: "Literal[value=/^#[0-9a-fA-F]{3,8}$/]",
          message: "Use a colour token, not a hex value.",
        },
      ],
    },
  },
];

Add this to your existing config, alongside your TypeScript parser setup. For alt text, eslint-plugin-jsx-a11y has an alt-text rule.

Step 5: Run the checks on every commit and pull request

Before each commit, run the linters on staged files with lint-staged (and Husky to install the hook):

{
  "lint-staged": {
    "*.css": "stylelint",
    "*.{jsx,tsx}": "eslint"
  }
}

On every pull request, run them in CI:

# .github/workflows/ui-checks.yml
name: UI checks
on: [pull_request]
jobs:
  ui:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - run: npx stylelint "src/**/*.css"
      - run: npx eslint src

Then make the job a required status check in your branch protection settings, so a failing check blocks the merge.

Finally, tell the AI to run the checks itself. Add one line to CLAUDE.md or your Cursor rules:

After changing UI, run `npx eslint` and `npx stylelint` on the files you changed and fix every error before finishing.

Claude Code and Cursor's agent can run terminal commands, so they'll catch most of their own mistakes before you see the code.

Where the do-it-yourself setup runs out

This works well for one React repo. It gets harder when:

  • Not everything is JSX. Angular templates, Vue templates, PHP, Twig and Liquid each need their own tooling, and inline styles in templates slip past Stylelint.
  • Old code fails on day one. Turn these rules on in an existing repo and you'll get hundreds of errors. You want to check only the lines a change touches, which linters don't do out of the box.
  • The error doesn't say which token to use. "Unexpected hex colour" leaves the developer, or the AI, guessing again.
  • Component props aren't checked. ESLint knows <Button> exists, not that variant="primary-large" doesn't.
  • Rules drift between repos. Ten repos means ten copies of the config. Change a token and you update every one by hand.

The same loop with Brandrail

Brandrail runs these checks from your Brand Kit, in all of those template languages, and keeps every repo in sync.

npx brandrail connect                            # rule files + MCP server for Claude Code, Cursor, Copilot, Codex
npx brandrail hook install                       # check staged lines before every commit
npx brandrail check --changed --fail-below 80    # only lines changed vs origin/main
  • While the AI writes: the MCP server's validate_snippet tool scores the code it just wrote and returns the fix for each problem, so it corrects itself first.
  • Before each commit: the hook checks staged lines on the developer's machine. Errors stop the commit with the fix shown. Nothing is uploaded.
  • On each pull request: the GitHub App posts a brand score out of 100, notes on the changed lines and one comment with the fixes. Repos start in advisory mode. When the score is steady, turn on a merge gate at the score you choose.

The 12 rules cover hard-coded colours, Tailwind palette classes, spacing and radius scales, fonts, raw HTML where your component exists, forbidden imports, legacy libraries, component props, deprecated tokens and components, and alt text. They read JSX, Angular, Vue, Svelte, HTML, CSS, PHP, Twig, Mustache, Handlebars, Nunjucks and Liquid. Only changed lines are scored, so existing code never blocks a pull request.

When the Brand Kit changes, Brandrail opens a pull request in every connected repo with the new tokens and rules. No copying config by hand.

Try it

In any repo, without an account:

npx brandrail init
npx brandrail check

init sets up starter tokens and rule files for your AI tools, and check gives you a brand score for the code you have today. To use your own Brand Kit, run npx brandrail connect. The CLI checks and GitHub Action are on the free plan; pull request checks through the GitHub App are on Team, with a 14-day free trial.