Writing rules

Your rules live in the DESIGN.mdyou already keep. Two parts are checked; everything else stays prose for people and agents to read. A rule should be something you’d correct in review every time, said once.

Words

A table headed Say | Not, anywhere in the file. Each row is the word to use and the words it replaces, separated by commas.

## Words| Say | Not || --- | --- || order | purchase, transaction || customer | user, client (in UI copy) || sign in | log in, login || `Acme` | `acme` || field | column (except when talking about a file) |

Plurals and case follow what was written: Purchases becomes Orders.
A note in parentheses is for people, and is ignored: (in UI copy).
A word in backticks matches only in that exact case, so `acme` catches the lowercase word and leaves the name Acme alone.
A row whose note says except isn’t checked: the right word depends on context, and a check would be wrong as often as right.
In code, only text people read is checked: JSX text and strings of words, not names, classes, URLs or comments.

Colors, fonts and the rest

One fenced block tagged design-rules, holding JSON. Every field is optional.

```design-rules{  "colors": { "ink": "#18181b", "paper": "#ffffff", "blue": "#2563eb" },  "allowColors": { "#107c41": "Excel's mark, in the file list" },  "fonts": ["Inter", "JetBrains Mono"],  "banned": [{ "text": "seamless", "why": "Say what it does instead." }],  "maxSentenceWords": 24,  "ignore": { "src/generated/**": "Generated code" }}```

Field	What it checks
`colors`	The palette, by name. Any other literal color in code (#hex) is a finding, fixed to the nearest palette color.
`allowColors`	Colors allowed outside the palette, each with why: a partner's logo, a file type's mark.
`fonts`	The only font families. Generic fallbacks (sans-serif, system-ui) and var(--…) are always fine.
`banned`	Words and phrases never to use, each with what to do instead. Their other forms count: seamlessly, unlocking.
`maxSentenceWords`	The longest sentence, in words. Checked in copy, not in code.
`ignore`	Paths the rules don't cover, each with why: generated types, an API's own names, legal text.