Skip to content

Black Friday: up to 61% off our packs until November 30.

See the packs

Brandrail vs Brandrails vs Modern Web Guidance: AI UI Code Guardrails for Your Design System

Brandrail, Brandrails and Modern Web Guidance each guard a different rail of AI-generated UI: brand conformance, design tokens and agent rules, and modern web platform code. This guide introduces the Three-Rail Model, maps which tool catches which drift, shows how to gate them in CI, and sets out what the evidence does and does not show.

Teams that ship UI with Claude Code, Cursor, Copilot or Codex end up with screens that work but don't look like one product. The code underneath also tends to be older in style than what a senior frontend engineer would write today.

The Three-Rail Model: three tools, three layers of AI UI drift

The Brandrail project puts the core problem plainly: AI coding tools don't know your design system, so every screen comes out with different colours, buttons and spacing. We split that drift into what we call the Three-Rail Model: a brand rail, a token rail and a platform rail. Each tool here concentrates on one.

Brand rail. Brandrail (brandrail-app/brandrail) is an MCP server. It hands the agent your Brand Kit and components before it writes UI, then checks the result and returns fixes so the agent can correct itself.

Token rail. Brandrails (matejholek/brandrails) is a separate tool whose always-loaded agent files, such as AGENTS.md and the Copilot instructions, list only token names and point to design/tokens.md, so a big design system doesn't eat the context window.

Platform rail. Modern Web Guidance goes after a different failure. Its maintainers point out that coding agents often fall back on older patterns because LLM training data contains vast amounts of legacy code. A button can match your brand perfectly and still use a pattern the web platform replaced years ago.

A note on names: Brandrail and Brandrails are easy to confuse, so we suggest installing each from its exact repository URL.

ToolRailWhen it actsWhere it runsLicence or stewardship
Brandrail (brandrail-app/brandrail)Brand: Brand Kit and componentsBefore generation (context) and after (validation)Local MCP server over stdio and a CLI checker, plus a hosted account serviceMIT, according to third-party coverage from Tech Bytes
Brandrails (matejholek/brandrails)Tokens and lean agent instruction filesBefore generation (agent files)In your repositoryCheck the repository before adopting
Modern Web GuidanceModern, standards-based web codeBefore generation (agent guidance)In the agent's working contextStewarded by the Chrome, Edge, Firefox and MDN teams with the community

Which rail catches which drift

The matrix below is our own reading of each project's stated focus, not a measured comparison. No column fully covers accessibility or cross-browser behaviour, so we suggest keeping those checks with people.

Drift typeBrand rail (Brandrail)Token rail (Brandrails)Platform rail (Modern Web Guidance)
Off-brand colours, type or componentsPrimaryPartialNo
Hard-coded values instead of tokensPartialPartial (agents pointed to tokens)No
Agent never sees your rulesPartial (MCP context)Primary (lean always-loaded files)No
Legacy patterns, such as custom JavaScript tooltipsNoNoPrimary
Semantics, forms and accessibilityNoNoPartial
Cross-browser behaviourNoNoNot reliable

Brandrail: brand context in, brand score out

Brandrail runs as a loop. Before generation, its MCP server sends the agent your Brand Kit and components as context, so the first draft starts from your rules rather than the model's defaults. After generation, validation goes through a tool called validate_snippet. Its published description says it returns a brand score and lists each violation alongside its fix.

The intended usage is specific: call it once after writing UI, pass in every changed file, and fix every error and warning before finishing. An agent that only passes the last file it touched will get a flattering score. We suggest treating the brand score as one signal among several, with separate checks for accessibility, layout and code quality.

On packaging, third-party coverage from Tech Bytes reports that Brandrail ships an MIT-licensed package with a local MCP server, a standalone CLI checker and a pure TypeScript rules engine with no runtime dependencies. The CLI checker matters because an MCP tool only runs when the agent decides to call it, while a CLI step in CI runs on every pull request.

What Brandrail keeps local and what touches its hosted service

Security, legal and procurement will all ask where the code goes. On the checking path, Brandrail's repository is clear: the server runs locally over stdio, and code is checked on your machine and never uploaded.

Brandrail also runs a hosted service with accounts and API keys. Its security page describes that side:

  • API keys: only a SHA-256 hash is stored. Keys are scoped, expire after 90 days and show when they were last used, and revoking one takes effect immediately.
  • Encryption: data in transit uses TLS 1.2 or higher everywhere, with HSTS on. Brandrail's database provider encrypts data at rest with AES-256.
  • Certification: asked about formal certification, Brandrail answers 'Not yet.' It offers to complete security questionnaires and can sign a data processing agreement.

Use the questionnaire and data processing agreement offer to get written confirmation of how hosted account and Brand Kit data is handled. Then verify the local-only claim yourself by watching network traffic during a local check, the same diligence you would apply to any developer tool.

Brandrails: lean agent files that point to your tokens

Brandrails keeps always-loaded files small: AGENTS.md and the Copilot instructions list only token names and point to design/tokens.md. That way, a large design system doesn't crowd out the rest of the agent's context.

For the token file itself, teams may find a shared format useful. The Design Tokens W3C Community Group describes itself as a community of designers, developers and tooling vendors standardising how design tokens are defined and exchanged. We suggest checking how Brandrails expects tokens to be structured before you settle on a format, and preferring a standard format where your tools allow it, so the same file can feed other tooling.

We also suggest adding a token drift check at pull request time that flags hard-coded values that should have been tokens. Lean agent files guide the agent before generation, and a CI check backs that guidance up with a step the agent cannot skip.

DesignSystems.one states that Claude Code does not read AGENTS.md and calls this the most common wrong assumption in the category. DesignSystems.one also says the narrative that AGENTS.md has displaced CLAUDE.md is not supported by file counts, and that CLAUDE.md is ahead. With both conventions in wide use, we suggest supporting both as the default.

Modern Web Guidance: stopping agents from writing legacy web code

Modern Web Guidance is stewarded by the Google Chrome, Microsoft Edge, Mozilla Firefox and MDN teams, alongside the web development community. The evaluation figures and adopter results below come from Chrome's documentation and blog, so we treat them as vendor-reported, with Search Engine Journal as the main independent check.

On Chrome's eval dashboard, guided agents reach a 91% pass rate against about 51% for unguided frontier models. When Search Engine Journal looked at the dashboard, it recorded 88% guided against 56% unguided.

The Chrome blog also features three adopters:

  • note inc.: the pass rate on modern web checks rose from 61% to 94% across 180 runs. The gains came from steering agents toward native HTML and CSS features instead of custom JavaScript for scroll animations, tooltips and accordions.
  • WeTV: debugging and resolution time fell by 87%, from four hours to 30 minutes. The agent reportedly diagnoses and fixes 90% of failed performance checks automatically, and the four-hours-to-30-minutes figure includes manual evaluation.
  • MetaMask: a review bot reviewed about 480 PRs, commented on 64 and saw 43 findings fixed. Most findings were accessibility, HTML semantics and forms issues that linters don't catch, with a median of 15 minutes from comment to fix.

Search Engine Journal separately reported that the MetaMask bot flagged 102 issues across 57 feature and fix PRs in its first five weeks.

LogRocket's test shows the kind of mistake the pack targets, using a filtering interaction in React where memoisation looks like the obvious fix. As LogRocket explains, useMemo avoids unnecessary recalculation across renders, but it doesn't make the filtering work non-blocking, and that is what matters for Interaction to Next Paint (INP). We suggest reading the LogRocket example as an illustration of the failure rather than as evidence of the fix.

How to combine the three tools: a design-ops playbook

The model works best when each rail has one job and one owner, and when enforcement doesn't rely on the agent remembering its instructions.

Step 1: make the token file the source of truth

Define or export tokens in a single file, ideally in a standard format such as DTCG, and commit them with a named owner. Point lean agent files at that file, the pattern Brandrails uses. Confirm before the pilot whether Brandrail can import your token file directly. If it can't, update the Brand Kit in the same change as the tokens and make the token owner responsible for both.

Step 2: keep agent files lean and cover every agent

Always-loaded files should hold token names plus a pointer to the full token reference, the pattern Brandrails uses. Because Claude Code does not read AGENTS.md, pair the lean AGENTS.md with a CLAUDE.md that imports it. Every agent then works from the same rules.

Step 3: add platform guidance

Install Modern Web Guidance for each agent in use, so agents prefer native HTML and CSS over custom JavaScript for common patterns like tooltips, accordions and scroll animations.

Step 4: close the generation loop

Connect Brandrail's local MCP server so the agent gets the Brand Kit first, and make validate_snippet part of the definition of done: one call, every changed file, every error and warning fixed.

Step 5: gate at the pull request

Run the checkers in CI to take enforcement out of the agent's hands, but don't make everything blocking on day one.

  • Token drift check: blocking. A value either matches a token or it doesn't. We suggest enforcing it on changed lines from the start, using whatever token linting your stack supports.
  • Brandrail CLI checker: advisory first. During the pilot, log brand scores per PR without blocking. Once you have a baseline, block on errors and leave warnings advisory. Set any minimum brand score from your own pilot data.
  • False positives. Allow exceptions only with a written reason and a named approver. If one rule keeps misfiring, fix the token or the rule rather than suppressing it again.
  • Review bot: advisory. A bot like MetaMask's can flag semantics, forms and accessibility issues while people decide what to fix.

Step 6: keep people on accessibility

Step 7: measure cost and latency

Runs with Modern Web Guidance enabled were usually slower and used more tokens. Measure token use and run time before and after the pilot.

Common mistakes with AI UI code guardrails

Treating an agent-ready design system as a guarantee. DesignSystems.one reports that Meta's own Astryx design system scored 87 overall on Meta's nightly benchmark, below a plain shadcn/ui baseline. Read the result as direction rather than magnitude, and keep CI gates on generated UI even when a design system is described as agent-ready.

Confusing brand conformance with accessibility. A study reported as appearing at CHI 2026 found 541 issues across 300 generated interfaces, about 1.8 per UI, led by generic button labels, vague link text and poor alt text, followed by ARIA and form label problems. We couldn't confirm the paper's title or authors, which makes the figures indicative rather than definitive, and none of these issue types falls within what a brand score checks.

Caveats: what the evidence does and does not show

Most Modern Web Guidance figures come from Chrome. The 91% headline comes from Chrome's dashboard, and the adopter results come from companies Chrome chose to feature. Search Engine Journal's separate snapshot, covered above, showed a narrower gap. Both point the same way, but the size of the effect depends on when and how you measure, which is why benchmark scores need a stated evaluation protocol before you compare them.

Guidance does not replace testing. In a published review, accessibility consultant Adrian Roselli found that output from the preview version did not comply with WCAG and that its animation didn't work in Firefox.

Treat Brandrail and Brandrails claims as untested until you test them. What this article says about both projects comes from project documentation and third-party write-ups, so we suggest validating their behaviour on your own codebase during the pilot.

Instruction files and names differ between agents and projects. According to DesignSystems.one, Claude Code does not read AGENTS.md. Before you standardise, re-check which instruction files each of your agents loads and confirm every repository URL.

Key Takeaways

  1. The Three-Rail Model splits AI UI drift into brand, tokens and rules, and platform. Brandrail, Brandrails and Modern Web Guidance each focus on one rail.
  2. Make a single token file the source of truth and derive Brandrail's Brand Kit from it, which keeps the checks from flagging conflicting violations.
  3. Make a token drift check blocking early, and run the Brandrail CLI checker as advisory until pilot data gives you a baseline brand score.
  4. Brandrail says code is checked locally and never uploaded. It is not yet certified, so confirm in writing how hosted account and Brand Kit data is handled.
  5. Claude Code does not read AGENTS.md natively. Pair a lean AGENTS.md with a CLAUDE.md that imports it.
  6. Chrome reports 91% guided against about 51% unguided. Search Engine Journal's separate snapshot showed 88% against 56%, a narrower gap.
  7. No rail covers accessibility or cross-browser behaviour on its own, and guided runs usually cost more tokens and time.

Conclusion

For a first pilot, pick one product area and give each rail one owner. Record the exact repository URLs for Brandrail and Brandrails, make a single token file the source of truth, and keep always-loaded agent files lean, with a CLAUDE.md alongside the lean AGENTS.md. Make a token drift check blocking on changed lines, run the Brandrail CLI checker as advisory until you have a baseline, and verify Brandrail's data boundary with a network check during a local run. Measure token spend and run time before and after enabling Modern Web Guidance, and treat vendor-reported figures as a hypothesis to test on your own codebase. Keep accessibility and cross-browser review with people throughout.

Related reading on Optijara: Playwright and axe across real UI states and OpenTelemetry GenAI tracing for agent runs.

Frequently Asked Questions

What are AI UI code guardrails?

They are tools and checks that keep UI generated by coding agents such as Claude Code, Cursor, Copilot or Codex consistent with your design system and current web practice. In the Three-Rail Model used here, Brandrail covers the brand rail, Brandrails covers design tokens and lean agent instruction files, and Modern Web Guidance covers the platform rail.

Are Brandrail and Brandrails the same project?

No. Brandrail (github.com/brandrail-app/brandrail) is an MCP server and checker that gives agents your Brand Kit and returns a brand score. Brandrails (github.com/matejholek/brandrails) is a separate tool whose always-loaded agent files list only token names and point to a fuller token reference. Always refer to and install from the exact repository URL.

If Brandrail and Brandrails disagree, which one wins?

Decide that before the pilot. A practical rule is that the token file in your repository is the source of truth and Brandrail's Brand Kit is derived from it. If the Brand Kit can't be generated from the tokens, update it in the same change and give one owner responsibility for both.

Does Brandrail upload my source code?

Brandrail states that its MCP server runs locally over stdio and that code is checked on your machine and never uploaded. The hosted account service is a separate question. See the section on what Brandrail keeps local for what to confirm in writing and how to verify the boundary with a network check.

Does Claude Code read AGENTS.md, or do I need a CLAUDE.md as well?

Claude Code does not read AGENTS.md natively. You need a CLAUDE.md that imports or mirrors those rules. DesignSystems.one reports that file counts do not support the idea that AGENTS.md has displaced CLAUDE.md, so we suggest supporting both as the default.

Do I need all three tools, or which one should a team start with?

Start with the rail where your drift comes from. If generated screens ignore your colours and spacing, start with the token rail (Brandrails) or the brand rail (Brandrail). If the code works but relies on outdated patterns, start with Modern Web Guidance. Many teams will end up combining them, but piloting one rail first makes the effect easier to measure.

Does Modern Web Guidance make AI-generated UI accessible and cross-browser by itself?

No. It raises the baseline of generated code, but accessibility and cross-browser support still have to be tested. An independent review of the preview version found problems in both areas. Keep automated accessibility tests and human cross-browser review in the pipeline.

Sources

  1. https://github.com/brandrail-app/brandrail
  2. https://www.brandrail.com.au/security
  3. https://glama.ai/mcp/connectors/au.com.brandrail/brandrail/tools/validate_snippet
  4. https://techbytes.app/posts/brandrail-make-claude-code-and-cursor-follow-your-design-system/
  5. https://github.com/matejholek/brandrails
  6. https://www.designtokens.org/
  7. https://www.designsystems.one/ai-ready/agent-files
  8. https://developer.chrome.com/docs/modern-web-guidance
  9. https://developer.chrome.com/blog/modern-web-guidance-v1
  10. https://github.com/GoogleChrome/modern-web-guidance
  11. https://blog.logrocket.com/chromes-modern-web-guidance-prevent-ai-coding-agents/
  12. https://www.searchenginejournal.com/google-releases-modern-web-guidance-1-0-for-ai-coding-agents/596495/

Share this article

Hamza Diaz

Written by

Hamza Diaz

Hamza Diaz is the founder of Optijara, where he builds practical AI agents, automation systems, and Copilot workflows for service businesses. He writes about AI operations, agent strategy, and real-world implementation for teams that want usable systems instead of hype.

All articles

Next step

Have something to build?

Tell us what you need. We reply with a clear scope and a fixed quote.