/writing-ui-rules-for-agents
Interviews a designer about their product's UI and writes the short rules file a coding agent (Claude Code, Cursor, Codex) must follow, so the agent reuses existing components, tokens, and patterns instead of inventing its own buttons, colors, and spacing.
SKILL.md
---
name: writing-ui-rules-for-agents
description: Interviews a designer about their product's UI and writes the short rules file a coding agent (Claude Code, Cursor, Codex) must follow, so the agent reuses existing components, tokens, and patterns instead of inventing its own buttons, colors, and spacing. Use when the user wants a CLAUDE.md, AGENTS.md, or rules file for UI, says their agent keeps making off-brand or inconsistent UI, or wants to set up a coding agent on a design system, even if they never say "rules."
metadata:
category: design
---
# UI rules for agents
Write the rules a coding agent reads before it touches UI. Short, specific, and checkable. The goal is that the agent reaches for what already exists before it builds anything new.
## How to work
1. If you can see the codebase, look first: the component folder, the theme or token file, the global CSS, and two or three real screens. Note what exists. Do not ask the designer what you can read.
2. Then ask only what the code cannot tell you, a few questions at a time:
- Which components must always be used (button, input, card, dialog), and where do they live?
- Where do colors, spacing, type sizes and radius come from? Are raw values ever allowed?
- What does the agent get wrong most often today?
- What should it do when no component fits: stop and ask, or build and flag?
3. Write each rule as one line: what to do, then why in a few words. A rule without a reason gets bent the first time it is inconvenient.
4. Put the most-broken rules first. Agents read the top of a file most carefully.
5. End with how the agent checks its own work: the lint, type check, or visual check to run before it says done.
## Gotchas
- "Follow the design system" is not a rule. Name the folder, the file, and the component.
- Vague taste words ("clean", "modern", "on-brand") do nothing. Replace each with the token, value, or component it means.
- Keep it under about 60 lines. A long rules file gets skimmed, and the rule that mattered is on line 140.
- Say what to do instead, not only what not to do. "Never use raw hex" leaves the agent guessing; "use the color tokens in theme.css, never raw hex" does not.
## Output
A file ready to save as `CLAUDE.md` or `AGENTS.md` (or a UI section to paste into one):
# UI rules
## Always
- Use [component] from [path] for [job]. [why]
## Never
- [thing]. Use [alternative] instead. [why]
## Tokens
- Color: [where]. Spacing: [scale]. Type: [scale]. Radius: [values].
## When nothing fits
- [stop and ask / build and flag in file X]
## Before saying done
- Run [check]. Look at the screen at [widths].