T3.2 - C3/S5: one source of truth for colour; page sheets alias only

theme-light.css is now the only file in html/ that contains a colour literal.
The five page stylesheets and all four inline <style> blocks declare names and
nothing else.

  theme-light.css                 191 declarations, 175 with a literal value
  console.css                      28 declarations,   0
  work-package-suite-styles.css    16 declarations,   0
  wp-chrome.css                    14 declarations,   0
  wp-creation-styles.css           24 declarations,   0
  wp-sidenav.css                    0 declarations,   0

#0f62fe is declared in one sheet, down from five. The eleven occurrences left
inside theme-light.css are Carbon's own v10-to-v11 alias layer, which the
inventory records as deliberate and not the S5 defect.

Names were kept, because 111 var() references live in .js files across 23 token
names and a rename there fails silently - no build error, no console warning,
just an unstyled element.

The rule the refactor was built on: consolidation is not unification. Where two
sheets declared the same value, they collapse. Where they declared DIFFERENT
values for one role - the two shadows, the eight status borders doing four jobs,
the three mono stacks - each value got its own canonical name and the pair is
recorded for T3.5. Picking a winner between two near-identical greys is a
rendered change, which this task forbids. The console's zebra stripe is the one
that would have bitten: #fafafa is six points from #f4f4f4, and merging them
erases the striping on the nine-column user table.

Collecting the one-offs in one place made two things countable that were not
before: twelve distinct shadows, and a ninth amber (#8a6d00 on the field view,
four points from #8e6a00 and doing the same job - BL-009).

VERIFICATION - the screenshot done-when could not do the job, so it was replaced.

Captured against wave 2, 11 of 14 shots were pixel-identical and 3 were not.
Capturing wave 2 against ITSELF produced the same 3 differences at the same
bounding box, so those shots cannot distinguish a regression from the clock.
Trap 2 in the brief is half wrong: users.html is stable at both widths; the
unstable third is the creator at 1440px, and admin's captured page height varies
by ~600px between runs (BL-012).

So tests/token_check.py was added. It checks what wave 3 actually claims: that
every custom property resolves to the same literal, and every element computes
the same colours, shadows and type. That is stronger than a screenshot - it
covers the hover, focus and disabled rules a screenshot never exercises, and it
is deterministic.

  wave 2 vs T3.2, all 7 pages:
  178/178 wave-2 token names resolve identically, +213 new
  3,500 elements compute identically, zero added, zero removed
  16 tokens differ in notation only (#fff -> #ffffff), which is the duplicate
  class this task existed to collapse

Two detours worth not repeating: the element walk was first keyed by sibling
index and reported 55 phantom differences on the SOP page, where three
JS-injected overlays append in whichever order their async work finishes
(BL-011); and the comparator now normalises notation before reporting, because
otherwise it fails on its own success.

f_items 5 FIXED / F6 REPRODUCES as expected. browser_check 71/71.

ONE DONE-WHEN NOT MET, recorded rather than skipped: "no page stylesheet
declares a raw color, spacing or type value". The colour half is met in full.
483 raw spacing values, 281 font-sizes and 65 radii remain inside rules, 492 of
them in the creator. That is arithmetic, not effort: the creator's spacing is
every integer from 1px to 14px, so no token exists that padding:9px 11px maps to
without changing one of the numbers - and this task forbids changing a rendered
value. The two requirements are mutually exclusive. Logged as BL-010 for T5.x
and T7.1, where those pages are re-laid-out and the values get chosen again.

New backlog: BL-009 (ninth amber), BL-010 (raw spacing/type in rules),
BL-011 (overlay append race), BL-012 (unstable screenshot targets).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-08-15 18:50:30 -05:00
parent 0e40e967a0
commit 9ab7b48de2
14 changed files with 964 additions and 266 deletions

View File

@@ -180,3 +180,59 @@ deliberately deferred.
- **Why not now:** swapping it changes a rendered fill, which `T3.2` forbids. It is the same
conversation as the green action buttons.
- **Suggested wave or follow-up:** `T3.5`, with `A5`. See `docs/reference/tokens.md` §8-E.
### BL-009 — A ninth amber, four points from the eighth
- **Found during:** T3.2
- **Where:** `html/field.html:35` (`.pill.warn`)
- **What:** the field view's warn pill uses `#8a6d00`; every other warning text in the app is
`#8e6a00`. Four points apart, doing the same job, on the surface that is read through a
face shield. Almost certainly a typo rather than a decision — `field.html`'s inline `<style>`
was missed by the `T3.1` inventory, which is why it survived this long.
- **Why not now:** merging it moves a rendered colour, which `T3.2` forbids. `T3.2` named it
`--wp-status-warning-text-alt` so it is visible rather than hidden in a hex.
- **Suggested wave or follow-up:** `T3.5`. See `docs/reference/tokens.md` §8-K.
### BL-010 — 829 raw spacing, type and radius values remain inside rules
- **Found during:** T3.2
- **Where:** all five page stylesheets; 492 of them in `html/wp-creation-styles.css`
- **What:** `T3.2` removed every raw **colour** from the page sheets, but 483 spacing values,
281 font-sizes and 65 radii are still written literally in rules. The token *declarations*
are aliased — `--s1`…`--s6`, `--ctl`, `--radius`, `--mono`, `--sans` all resolve from
`theme-light.css` — but the rules that should consume them do not.
- **Why not now:** not effort — arithmetic. The creator's spacing is every integer from 1px to
14px, which is a histogram rather than a scale, so there is no token `padding: 9px 11px` maps
to without changing one of the two numbers. `T3.2` forbids changing a rendered value, so
tokenising these and honouring that constraint are mutually exclusive. This is the one `T3.2`
done-when not met, and it is recorded as not met rather than quietly skipped.
- **Suggested wave or follow-up:** `T5.x` and `T7.1`, where these pages are re-laid-out and the
values are being chosen again anyway. See `docs/reference/tokens.md` §6b and §11.
### BL-011 — Three JS-injected overlays race to append on the SOP page
- **Found during:** T3.2
- **Where:** `html/work-package-suite.html` — `#wp-sync-badge`, `.wp-navscrim`, `#wp-sidenav`
- **What:** the sync badge, the drawer scrim and the drawer are appended to `<body>` by three
different scripts after async work, so their DOM order varies run to run. Nothing is painted
differently — all three are `position: fixed` with their own `z-index` — but any test that
keys elements by sibling index sees dozens of phantom differences on this page. It cost real
time in `T3.2` before the cause was found, and `tests/token_check.py` now keys by identity
to avoid it.
- **Why not now:** invisible to users, and the fix is ordering in three separate scripts, which
is a change with no observable benefit while `T7.1` is still going to move this code.
- **Suggested wave or follow-up:** wave 9, if it is still true after `T7.1`.
### BL-012 — `admin.html` and the creator at 1440px are not stable enough to screenshot-diff
- **Found during:** T3.2
- **Where:** `tests/baseline_shots.py` output for `admin-390`, `admin-1440`, `creator-1440`
- **What:** the task brief's trap 2 says `admin.html` and `users.html` are not byte-stable.
Measured by capturing wave 2 against itself: **`users` is stable at both widths**, and the
unstable third is the **creator at 1440px** (344,272 px differ, bbox 288,14→1439,4924).
`admin` is worse than "live timestamps" suggests — its captured page *height* varies by about
600px between runs, so the two images cannot even be compared pixel-for-pixel.
- **Why not now:** the screenshots are a review aid, not a gate; `tests/token_check.py` now
covers what the diff was being asked to prove, and covers it better.
- **Suggested wave or follow-up:** wave 9, alongside `C2`. Either freeze the clock in the
fixture or exclude the live regions from capture — otherwise every later wave re-learns this.