How to Build UI Rules Claude Can Reuse Across Routes

Why does Claude lose UI consistency across routes?

Claude loses UI consistency when stable product decisions remain trapped in one conversation, one screenshot, or one developer's memory instead of living in project instructions and reusable interface rules.

A model can produce a coherent local answer without preserving the complete product system. If the next task says “add a billing page,” it may choose another heading scale, a slightly different button height, or a new muted color because those constraints were never made durable. Each choice can be reasonable in isolation while the full product becomes visibly inconsistent.

Anthropic documents project memory through files such as CLAUDE.md, which can hold shared project architecture, coding standards, and workflows. The important opportunity is not to paste a style manifesto into that file. It is to keep the small number of rules Claude must repeatedly retrieve, with links to deeper source files where needed.

Write a direct project instruction such as: “Use the UI contract in docs/ui-system.md. Do not create raw spacing, color, radius, or control-height values when an approved role exists. If the requested state is absent, return a design hold instead of inventing one.” That instruction tells the agent where truth lives and what to do when truth is missing.

What belongs in a reusable UI rules file?

A reusable UI rules file should contain product-level decisions that recur across routes: visual roles, component behavior, responsive boundaries, accessibility signals, implementation limits, and the evidence required for approval.

Do not record every CSS declaration. Record the decisions that prevent future disagreement. A useful rule explains what the value does, where it applies, and how a reviewer can recognize a violation. “Blue 600” is a value. “Action primary” is a role. The role can later change color without forcing the model to rediscover its meaning.

Keep evidence and preference separate. “The checkout primary action is 44 pixels tall in the approved fixture” is observed evidence. “All primary actions should be 44 pixels tall” is a proposed rule until the owner approves it. Marking that difference prevents an agent from converting one screenshot into an accidental universal standard.

How should design tokens be written for an AI agent?

Write design tokens as semantic roles with types, values, descriptions, and valid uses, then tell the agent to reuse roles before proposing new tokens.

The Design Tokens Community Group publishes a format for exchanging token definitions between tools. Its stable format describes tokens, groups, types, values, descriptions, references, and extensions. The specification is a Community Group report, not a W3C Recommendation, so treat it as a useful interoperable format rather than a universal compliance requirement.

For an AI-built interface, the naming discipline matters more than the amount of tooling. Group tokens by purpose. Use color.action.primary, color.text.muted, space.section.compact, and radius.control. Add a plain-language description. If the product has only one control radius, do not create six options because a design-system template had six.

Tell Claude what not to do: no raw hex colors inside components, no new spacing values without an approved role, no alias that changes semantic meaning, and no automatic replacement of an existing token merely because another value looks cleaner. New token proposals should name the unmet role, affected routes, and migration cost.

What is a component contract?

A component contract states what a reusable interface element is for, which variants and states are allowed, what content it accepts, how it responds, and which behaviors must remain unchanged.

A component library is most useful when another person can understand the boundaries without reading its implementation. Storybook's documentation system is designed to turn component stories into usage documentation and design-system pages. You do not need Storybook to write a contract, but the model is helpful: show the component in representative states and document the intended usage beside it.

For a primary button, record purpose, anatomy, allowed sizes, icon rules, label length, state behavior, minimum target size, and responsive exceptions. Then record prohibited uses. For example: the primary action appears once per decision surface; loading keeps the label width stable; disabled state is not used as a substitute for explaining validation; focus remains visibly distinct; links do not impersonate buttons unless they perform an action.

Claude now has a bounded decision. If the new screen needs a destructive action, it should use the documented destructive variant or raise a hold. It should not restyle the primary button red and silently create a new variant.

How do you stop responsive behavior from being reinvented?

Stop responsive behavior from being reinvented by declaring content priority, stacking order, minimum readable sizes, overflow behavior, and test widths for each reusable layout pattern.

Breakpoints alone are not a responsive contract. “At 768 pixels, switch to one column” says what the layout does, but not why. Record the priority rule: the decision copy stays before supporting proof; the primary action remains visible after the explanation; filters collapse into a disclosure; comparison tables may scroll inside a labeled region, while the page itself must not scroll in two directions.

WCAG 2.2 includes requirements related to reflow, focus visibility, text contrast, and controls. These are not satisfied by writing a rules file. The rules file should name the intended signal and the check. For example: body text targets the approved contrast threshold; keyboard focus remains visible and unobscured; no essential content depends only on hover; text can resize without losing the action; the route is inspected at a narrow 320 CSS pixel equivalent where applicable.

Use a small viewport matrix that matches the product. Desktop, 390 pixels, and 320 pixels may be enough for a narrow launch surface. A dense application may need tablet and intermediate boundaries. More screenshots are not automatically better. Every condition should answer a known risk.

Why does the UI need a state matrix?

The UI needs a state matrix because AI agents often polish the default screen while loading, empty, error, focus, disabled, and success states keep unrelated visual decisions.

Create a table with components on one axis and relevant states on the other. Mark each cell observed, specified, inferred, not applicable, or not tested. This forces a useful conversation before implementation. If the design contains no error behavior for an upload, the agent should not invent copy, color, and recovery logic in the same patch.

State coverage also protects the customer experience. A route can look premium in the screenshot and fail the moment the network is slow. The loading state changes layout height, the error uses a different red, the retry action has no focus style, and the empty state introduces another card pattern. Those are product problems, not decorative edge cases.

Give Claude the matrix and the current evidence. Ask it to implement only approved cells. Unspecified cells stay on a hold list for human decision. That makes missing context visible instead of allowing confidence to hide it.

How should Claude Code receive the UI contract?

Claude Code should receive a short project-level instruction that points to the canonical UI contract, names the implementation order, forbids unsupported invention, and requires verification before completion.

Keep the top-level instruction compact. Point to the full UI rules file and the state matrix. Name the common commands for build, test, and browser verification. Explain which directories own tokens and components. State that shared foundations are fixed before local overrides. Require the agent to report affected routes and evidence.

A useful instruction sequence is: inspect the current rendered route; read the UI contract; list observed holds; propose the smallest shared rule; wait for approval if the rule is new; implement the bounded patch; run the declared checks; inspect desktop and narrow screens; report pass, hold, and not tested. Never translate “the tests passed” into “the UI is good.”

Project memory can improve consistency, but it is still input to a probabilistic system. Review the loaded instructions, keep them current, and remove stale rules. A wrong durable rule can spread drift more efficiently than a one-off prompt.

How do you prove the reusable rules worked?

Prove the reusable rules worked by rendering the affected routes, capturing the same named states and viewports, comparing them with the approved baseline, and recording human-reviewed results.

Playwright supports screenshot comparisons through toHaveScreenshot(). Its documentation also warns that browser rendering varies by environment. Baselines should be generated and compared under consistent operating-system, browser, font, and rendering conditions. A changed pixel is evidence of a difference, not automatic evidence of a defect.

Use visual checks for stable surfaces and targeted regions. Mask truly dynamic content only when the mask cannot hide the behavior under review. Keep textual and functional assertions for behavior. Review each screenshot difference as intended, unintended, or inconclusive. Save the owner decision with the evidence.

The final receipt should name the route, state, viewport, rules version, code version, environment, checks, result, and exclusions. It should never claim accessibility certification, security, conversion lift, or client approval unless those were separate validated processes.