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
+26 -8
View File
@@ -66,16 +66,34 @@ worse than failing, because failure is visible and this is not.
`font:` shorthand passes it. Task 07 did exactly that, in **two** components,
with a comment saying so. Both hardcoded values survived into a "green" branch.
When a token you need does not exist:
### Do not substitute a near-miss token either
1. Stop. Do not invent a value, and do not reshape the syntax to hide one.
2. Write the gap in your task report: the selector, the legacy value(s) it comes
from, and which file owns the token.
3. If your task cannot proceed without it, say so and stop. A blocked task is a
finding. A silently-passing one is a defect that ships.
The second way to break this is subtler, and both tasks 10 and 11 did it: keep
the gate happy by pointing a legacy value at the closest token that already
exists. `#e5eeeb` became `var(--paper)`. Diff-**added** green became
`var(--accent)` — purple. `12px` and `14px` both became `var(--step-1)`, 15px.
`tokens.css` has a single owner (`design-system-keeper`) precisely so that "add
a token" is a decision, not a side effect.
That is a silent redesign, and it is _worse_ than leaving the raw value in,
because a raw hex is at least honest about being unresolved.
### What to do instead: mark the gap
`tokens.css` has one owner (`design-system-keeper`) so that "add a token" is a
decision, not a side effect. You may not add one. You **can** keep the true
value and stay green — mark it:
```css
/* token-gap: no --step-* covers 12px; owner design-system-keeper */
font-size: 12px;
```
The marker waives that one finding. It needs a real reason after the colon; a
bare `token-gap:` is rejected. Every marked value is listed on each run, so the
debt stays visible rather than disappearing.
Write it in your task report as well: selector, legacy value, owning file.
Marking a gap is not resolving it — it keeps the site truthful until whoever
owns the token layer decides.
## Parallelism