AI guardrails for coding agents
AI guardrails are project instructions that give Claude Code, Cursor, or Codex approved components, spacing, interaction patterns, and review steps.
Download the rules
The three files contain the same requirements. Only the file path and format change for each agent.
Claude Code
A path-scoped Claude Code rule that loads when Claude works on interface files.
- File
- better-design.md
- Save to
- .claude/rules/better-design.md
Cursor
A project rule for Cursor Agent and inline edits on interface files.
- File
- better-design.mdc
- Save to
- .cursor/rules/better-design.mdc
Codex
Repository guidance for Codex. Merge it into an existing AGENTS.md instead of replacing project rules.
- File
- AGENTS.md
- Save to
- AGENTS.md
Instructions guide behavior, they do not enforce it
Use lint rules, tests, hooks, visual checks, and code review when a requirement must be guaranteed. For Codex, merge the downloaded section into an existing AGENTS.md instead of replacing the repository's other instructions.
What changes when the rules are present?
The agent stops improvising local styles and starts from the product's existing system, states, and review requirements. This example is illustrative, not a measured benchmark.
Before the guardrails
Repeated surfaces, competing actions, and copy that does not name the result.
After the guardrails
One component language, one primary action, and a clear outcome.
What does the code change?
The rules prefer a known component and an outcome-specific label over a one-off control with local visual decisions.
- <button className="rounded-2xl border px-5 py-3 shadow-lg">
- Continue
- </button>
+ <Button type="submit" variant="primary">
+ Save access
+ </Button>Which Better Design docs define the rules?
Each rule group points back to the UI or UX documents it was distilled from. The shared model generates every agent download.
Start from the system
Treat the project's existing tokens and components as an allowlist before writing new UI.
- Component architecture:
docs/ui/component-architecture.md - Design process:
docs/ux/design-process.md - Anti-patterns catalog:
docs/ux/anti-patterns.md
Make hierarchy and spacing explain the screen
Use purpose, priority, type, and proximity to make the reading order obvious.
- Spacing and layout:
docs/ui/layout-spacing.md - Typography:
docs/ui/typography.md - Design process:
docs/ux/design-process.md
Use durable interaction patterns
Prefer native behavior, explicit outcomes, and controls that work with keyboard, touch, and pointer input.
- Interactions and accessibility:
docs/ux/interactions.md - Form behavior:
docs/ux/forms.md - Navigation:
docs/ux/navigation.md
Design every reachable state
A production component handles empty, loading, error, and success states instead of only the happy path.
- Design process:
docs/ux/design-process.md - UI polish:
docs/ui/polish.md - Error handling and recovery:
docs/ux/errors.md - Form behavior:
docs/ux/forms.md
Build accessibility and responsiveness in
Treat contrast, focus, reflow, zoom, and reduced motion as implementation requirements.
- Accessibility:
docs/ui/accessibility.md - Color system:
docs/ui/color.md - Responsive design:
docs/ux/responsive.md - Interactions and accessibility:
docs/ux/interactions.md
Review evidence before calling the UI complete
Verify the rendered interface, not only the source code or a successful build.
- Anti-patterns catalog:
docs/ux/anti-patterns.md - Microcopy and content:
docs/ux/microcopy.md - Responsive design:
docs/ux/responsive.md - Accessibility:
docs/ui/accessibility.md
How should an agent use the guardrails?
Use the file as the persistent baseline, then load the specific design context needed for the task.
1. Add the project rule
Save the download at the path shown for your agent and commit it with the repository.
2. Load task-specific context
Use Better Design MCP to load the active design system plus the relevant UI and UX principles before implementation.
3. Verify the rendered result
Run the review rules, comprehension check, project checks, keyboard flow, and narrow-width browser review.
FAQ
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.