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:
+26
-8
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user