docs(rules): document the token-gap marker

Companion to da790de. The previous wording said 'report the gap and
stop', which agents read as 'report the gap and substitute'. Name the
near-miss substitution explicitly and point at the marker instead.
This commit is contained in:
Marcos Paulo
2026-09-05 07:17:37 +00:00
parent da790de20d
commit 723abeafb5
2 changed files with 31 additions and 11 deletions
+5 -3
View File
@@ -28,9 +28,11 @@ You may not edit `tokens.css`, `verify.mjs`, `astro.config.mjs`, or
- No raw hex, no px font sizes, no ad-hoc breakpoints. Tokens only.
- **Never reshape CSS to slip past `check-tokens.mjs`** — e.g. the `font:`
shorthand to hide a px size it would catch as `font-size:`. If the token you
need does not exist, report the gap and stop; you may not add it yourself. See
`.agents/rules/gates.md`.
shorthand to hide a px size it would catch as `font-size:` — and never point a
legacy value at the nearest token that happens to exist. Both are silent
redesigns. Keep the true value and mark it
`/* token-gap: <reason>; owner design-system-keeper */`, which waives the
finding and queues it. You may not add tokens. See `.agents/rules/gates.md`.
- No `client:*` unless genuinely interactive, with written justification.
- Every ARIA attribute from the markup you replace survives. `verify.mjs`
asserts several by name.