Catching Agent-Written Tailwind Mistakes in CI
How Node lint helpers, pnpm workspaces, and git worktrees keep AI-assisted frontend delivery fast without sacrificing design system consistency.
AI coding agents are remarkably good at scaffolding React components, forms, and layouts in seconds. They are much worse at respecting the unwritten boundaries of your design system.
Across 10 teams sharing a React design system at BDO, we quickly noticed a recurring failure mode: an agent would generate clean TypeScript logic, then reach for a plausible-sounding Tailwind class (bg-surface-card or text-slate-600) that did not exist in our token theme, or quietly bypass our semantic palette altogether.
Why Docs and Code Review Don't Scale
When only one or two engineers write a component, PR review catches stray utility classes. When 70+ developers (increasingly assisted by coding agents) are shipping features concurrently, manual review turns into whack-a-mole:
- An unknown custom Tailwind token compiles silently to nothing in CSS unless validated.
- Arbitrary colour classes break dark/light theme parity or contrast standards.
- Agents copy patterns from older files, amplifying legacy drift across PRs.
Encoding Token Rules into Node Lint Helpers
Instead of writing longer prompt instructions and hoping models follow them, we moved enforcement into the build and lint pipeline.
By writing lightweight Node helper scripts that run as part of our lint checks, any invalid Tailwind design token written by an agent (or a developer) fails fast locally and in CI with an actionable message pointing to the valid semantic token.
// Conceptual flow of our CI token check:
// 1. Load the canonical design token keys exported by the design system
// 2. Scan changed TSX/CSS files for theme-scoped Tailwind utility prefixes
// 3. Reject unknown or raw palette tokens before code review
const SEMANTIC_PREFIXES = ["bg-surface-", "text-content-", "border-stroke-"];
export function findInvalidTokenClasses(
classTokens: string[],
allowedTokens: ReadonlySet<string>,
): string[] {
return classTokens.filter((token) => {
const isScoped = SEMANTIC_PREFIXES.some((prefix) => token.startsWith(prefix));
return isScoped && !allowedTokens.has(token);
});
}Pairing Guardrails with pnpm and Git Worktrees
Static checks solve correctness; workspace tooling solves concurrency.
To run multiple AI-assisted tasks in parallel without branches colliding or waiting minutes on node_modules installs, we migrated projects to pnpm and leaned heavily on git worktree:
pnpmcontent-addressable store: Creating a fresh worktree for a feature or bugfix links dependencies almost instantaneously rather than duplicating hundreds of megabytes per branch.- Isolated verification: Each agent worktree can run Vite builds, Vitest unit suites, and Playwright checks independently without invalidating the main working tree.
- Predictable merge surface: Combined with our design system lint checks and TypeScript strictness, concurrent agent branches stay small, focused, and safe to review.
Takeaway
Treat AI coding agents the same way you treat a fast-moving 70-person engineering org: don't rely on willpower or longer READMEs. Put fast lint guardrails, strict TypeScript boundaries, and isolated worktree workflows in the loop so speed and quality reinforce each other.