Writing rules
A rule is a single guideline that tells AI tools how your brand builds UI. Every rule has its text, a Guidance marker, and an Importance. Together these shape both what the rule says and how strongly an AI tool weighs it.
The rule model
Each rule combines five parts, two of them optional.
- Rule. The guideline itself, written in plain language. This is the only part you must fill in. It accepts Markdown, and what you write is what your tools receive.
- Heading. An optional short title for the rule.
- Guidance. Whether the rule is a Do, a Don't, a Caution, or Info.
- Importance. How much weight the rule carries: Required, Recommended, or Optional.
- Rationale. An optional note on why the rule exists.
You author rules in the composer, and rules live in named groups so related guidance stays together. See Organizing rules for how groups work.
Guidance
Guidance says what the rule is asking of whoever reads it. Every rule carries one, and a new rule starts on Info until you pick another.
- Do. The pattern to reach for. "Use sentence case for all button labels."
- Don't. The wrong answer here. "Do not use drop shadows on flat surfaces."
- Caution. This works, but it has trade-offs worth knowing first. "Gradient fills are fine on marketing pages, but they cost contrast in dark mode."
- Info. Context that helps someone decide, with nothing to obey. "The primary color is reserved for the main call to action on a screen."
Pick the Guidance that matches how you would naturally phrase the rule. A Do tends to be clearer than the equivalent Don't, so prefer a Do when both work.
Importance
Importance tells AI tools how strongly to weigh a rule when it conflicts with other guidance or with the model's own defaults. Unlike Guidance, it is optional: the picker offers Unset as a fourth choice, and a rule left there says nothing about how much it matters.
- Required. Follow this every time. Treat an exception as a bug.
- Recommended. Follow this unless you have a specific reason not to, and say what it was.
- Optional. A fine choice when it fits. Nothing is wrong without it.
Reserve Required for rules that must never be broken, such as accessibility minimums or non-negotiable brand constraints. If everything is Required, nothing stands out when rules conflict.
How to write a good rule
Strong rules are specific and self-contained, because the AI tool reads them without the context you have in your head.
Make it about one thing
Keep each rule to a single guideline. If you find yourself writing "and," consider splitting it into two rules.
Be specific
Name the exact token, component, or behavior. "Use the --radius-sm token for input fields" is easier to follow than "keep corners subtle."
Lead with the outcome
Say what should happen, then why if the reason helps. "Use oklch values for all color tokens so light and dark stay in sync."
Set the right Importance
Match Importance to how strict the rule really is. Promote it to Required only when breaking it would be wrong.
If a rule reads roughly but you want it tightened, AI Enhance rewrites it into a precise version while you keep control of the wording, Guidance, and Importance. See AI Enhance.
