# AGENTS.md · design-system.ai

Rules for any agent that writes code or copy for this repository. Served publicly at `/AGENTS.md`.

## Authority

When two files disagree, the higher one wins:

1. `AGENTS.md` (this file)
2. `DECISIONS.md`, generated from `data/decisions.json` (the register)
3. `components/*/README.md`
4. skills
5. generated catalogs

Skills apply rules and never make them. A missing rule is a proposal in `proposals/`, never an addition to a skill.

## Facts

1. Write no figure into content. Reference a claim by id: `{{claim:id}}` or `{{claim:id|display text}}`. Add a new figure to `data/claims.json` with a base, a source, a date and a confidence first. `check:claims` fails on an unknown id or a missing base or source.
2. Facts come from the brief, the owner, or a source that is opened and cited. A missing fact is written `[DOPLNIT]`. Never fill it with a plausible value.
3. Mark a forecast "Judgment:". Call a bet a bet.

## Naming

4. Name the 2026 work only in its neutral wording: "a banking software vendor", "a bank" or "a banking pilot app", "a design validator", "a design-system foundation", "a B2B car-loan platform". This holds for text, file names, URLs, alt text and commit messages. `check:blocklist` reads a private list that is not in this repository.
5. Name no person at any client or employer. No client logos and no client screenshots.

## Tokens and components

6. Tokens are DTCG 2025.10 files in `tokens/`, with one resolver and two modifiers, `brand` (`index`, `kiln`) and `mode` (`light`, `dark`). Terrazzo builds them. Never edit `tokens.css`; it is generated.
7. Use tokens only. Never write a hex, `rgb()`, named colour, pixel size, radius or font family in a component. `check:raw-values` fails on one.
8. Text in `ink` or `ink-muted` on `bg` or `surface`. Links in `accent`. One primary button per view in `accent-fill` with `on-accent`.
9. Status by lightness, glyph and word: danger `danger-fill` + ✕, warning `warn-fill` + `warn-border` + !, success `ok-border` outline + ✓.
10. Headings `--font-d`, body `--font-t`, ids, dates, hashes and code `--font-m`. Sizes `--size-*` only.
11. Every page uses `SpecSheet`: the 12-column hairline grid, a margin column with `§n` and one word, sections numbered from `§0`.
12. Cards carry their rule on top, never on the left.
13. Targets are at least 24 px (WCAG 2.2 AA). 44 px is AAA; do not call it the AA minimum.

## Do not

| Do not write | Write instead |
|---|---|
| a hex value such as `#0ca678` | `var(--accent)` |
| `font-family: Inter` | `var(--font-t)` |
| `Modal` | `Dialog` |
| `Chip`, `Tag`, `Pill` | `Badge` |
| `Stat`, `KPI`, `Metric` | `Claim` with an id |
| `ThemeToggle` | `BrandSwitch` |
| a left-border callout | `Alert` |
| "W3C standard" for DTCG | "DTCG 2025.10, a Final Community Group Report" |
| a maturity or quality score | the ladder level and the first gap |
| "obsolete", "deprecated", "shut down" for Claude Design | "moving into Claude" |
| "LangChain agent layer" | "skills, hooks, sub-agents and deterministic scripts" |
| core, global, base tokens | primitive tokens |
| decision, system tokens | semantic tokens |

## Copy

14. Follow `.voice-and-tone/CONTEXT.md`. In short: first person singular, never "we"; short sentences, one fact each; the limit before the claim; no em dash, no exclamation mark, no contractions, no serial comma, no emoji. `check:voice` fails on the mechanical ones.

## Privacy

15. No cookies, no local storage for preferences, no third-party requests. Brand and mode live in the URL. Fonts are self-hosted. `check:third-party` fails on an external request in built HTML.

## Generated files

16. A generated file starts with a marker naming its script and the words "do not edit". Change the source and rerun the script. Generated: `tokens.css`, the footer line, `llms.txt`, the Markdown twins, `DECISIONS.md`, `seed.json`.
