AI guardrails for Claude Code, Cursor, and Codex

Start from the system

Treat the project's existing tokens and components as an allowlist before writing new UI.

• Inspect the project for its design tokens, component library, type scale, spacing scale, radii, and shadows before styling.
• Reuse an existing component when it already serves the interaction. Do not recreate a design-system component locally.
• Use semantic tokens and approved variants. Do not invent raw colors, arbitrary spacing, one-off radii, or one-off shadows.
• If the project has no visual system, establish one before polishing individual screens.

Make hierarchy and spacing explain the screen

Use purpose, priority, type, and proximity to make the reading order obvious.

• Give each screen one primary purpose and one visually dominant action. Keep secondary actions quieter.
• Use values from the spacing scale. Keep spacing tighter within a group and noticeably larger between groups.
• Keep body text between roughly 45 and 75 characters per line and use balanced wrapping for headings.
• Make distinct type roles visibly distinct. Aim for about a 25 percent size jump between adjacent roles.

Use durable interaction patterns

Prefer native behavior, explicit outcomes, and controls that work with keyboard, touch, and pointer input.

• Use links for navigation, buttons for actions, real forms for submission, and native elements before ARIA workarounds.
• Keep every flow keyboard-operable with a visible focus indicator and logical focus order.
• Use at least 44 by 44 pixel hit areas on touch surfaces and at least 24 by 24 pixels for pointer input.
• Gate hover-only styling behind hover and fine-pointer media queries. Never hide a required action behind hover.
• Give every control a clear accessible name and every call to action a defined outcome.

Design every reachable state

A production component handles empty, loading, error, and success states instead of only the happy path.

• Implement empty, loading, error, and success states for every component that loads or changes data.
• Keep loading feedback next to the action that caused it and preserve useful content while background work runs.
• Make errors answer what happened, why when useful, and what the user can do next.
• Do not turn a failed request into a false empty state, expose internal errors, or discard user input silently.
• During form submission, keep the original action label visible, disable repeat submission, and surface field errors beside their fields.

Build accessibility and responsiveness in

Treat contrast, focus, reflow, zoom, and reduced motion as implementation requirements.

• Meet WCAG AA contrast floors: 4.5 to 1 for normal text and 3 to 1 for large text and non-text interface elements.
• Never use color as the only signal. Pair it with text, shape, position, or an icon.
• Build mobile-first and reflow instead of shrinking. The page must work at 320 pixels without page-level horizontal scrolling.
• Do not disable browser zoom. Verify the layout with larger text and at 200 percent zoom.
• Respect reduced-motion preferences while preserving the same content, state, and task completion path.

Review evidence before calling the UI complete

Verify the rendered interface, not only the source code or a successful build.

• Check the rendered interface at a narrow width and a representative desktop width.
• Complete the primary flow with keyboard only and inspect every focus indicator.
• Test empty, loading, error, success, long-content, and reduced-motion states that the change can reach.
• Run the project's type, lint, test, and build checks that cover the changed surface.
• When Better Design MCP tools are available, load the relevant UI and UX principles before implementation, then run get-review-rules and check-comprehension before presenting the result.

What are AI guardrails for UI?

They are durable project instructions that constrain an agent to the product's approved tokens, components, interaction patterns, accessibility requirements, and review workflow.

Do instruction files enforce the rules automatically?

No. They guide agent behavior, but they are not a policy engine. Use lint rules, tests, hooks, visual checks, and code review when a requirement must be enforced mechanically.

Can the same guardrails work with Claude Code, Cursor, and Codex?

Yes. The core rules are shared. Better Design renders them into each tool's current project-instruction format so the content stays aligned while the file location and frontmatter differ.

Where do the rules come from?

The rules are distilled from Better Design's UI and UX principle docs, including component architecture, spacing, typography, accessibility, forms, errors, navigation, responsive behavior, and microcopy.