---
title: "Writing rules"
description: "Learn the UI Rules rule model and how to write clear, well-weighted rules that AI tools follow."
label: "Writing rules"
date: "2026-06-25"
---

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](/docs/rules/organizing) 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.

<Callout type="info">
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.
</Callout>

## 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.

<Steps>
<Step>
### Make it about one thing

Keep each rule to a single guideline. If you find yourself writing "and," consider splitting it into two rules.
</Step>
<Step>
### 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."
</Step>
<Step>
### 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."
</Step>
<Step>
### Set the right Importance

Match Importance to how strict the rule really is. Promote it to Required only when breaking it would be wrong.
</Step>
</Steps>

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](/docs/rules/ai-enhance).