From 9ab7b48de271254e50fa18825a265816dde1840e Mon Sep 17 00:00:00 2001
From: "n.siegfried" <n.siegfried@prime-controls.com>
Date: Sat, 15 Aug 2026 18:50:30 -0500
Subject: [PATCH] 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>
---
 docs/reference/file-map.md         |   9 +
 docs/reference/tokens.md           | 160 ++++++++++++---
 docs/waves/backlog.md              |  56 ++++++
 html/console.css                   |  72 ++++---
 html/field.html                    |  26 +--
 html/index.html                    |  22 +--
 html/login.html                    |   6 +-
 html/theme-light.css               | 178 ++++++++++++++++-
 html/work-package-suite-styles.css |  79 ++++----
 html/work-package-suite.html       |   2 +-
 html/wp-chrome.css                 |  75 +++----
 html/wp-creation-styles.css        | 175 ++++++++--------
 html/wp-sidenav.css                |  63 +++---
 tests/token_check.py               | 307 +++++++++++++++++++++++++++++
 14 files changed, 964 insertions(+), 266 deletions(-)
 create mode 100644 tests/token_check.py

diff --git a/docs/reference/file-map.md b/docs/reference/file-map.md
index 9a6a349..7e5e857 100644
--- a/docs/reference/file-map.md
+++ b/docs/reference/file-map.md
@@ -199,8 +199,17 @@ python server/smoketest.py                  # API; needs WP_SMOKE_USER / WP_SMOK
 python tests/browser_check.py               # pages boot and render, self-contained
 python tests/baseline_shots.py              # screenshots, self-contained
 python tests/f_items.py                     # does each of F1-F6 still reproduce?
+python tests/token_check.py --out a.json    # every resolved token + computed style
+python tests/token_check.py --compare a.json b.json
 ```
 
+`tests/token_check.py` was added by `T3.2`, because a screenshot cannot prove a token refactor:
+three of the fourteen shots are not stable capture-to-capture (see `backlog.md` BL-012), and no
+screenshot exercises a hover, focus or disabled rule, which is where half the tokens live. It
+snapshots every custom property's resolved value and every element's computed colours, shadows
+and type, on all 7 pages, and diffs two snapshots. Use it for any task that claims to change
+styling without changing appearance.
+
 `server/smoketest.py` is the one that is **not** self-contained: it drives a server you point
 it at and aborts unless `WP_SMOKE_USER` and `WP_SMOKE_PASSWORD` are set, because every route
 but `/api/health` needs a session. Use an admin account — it creates and deletes a project.
diff --git a/docs/reference/tokens.md b/docs/reference/tokens.md
index ea5dd04..ac319e7 100644
--- a/docs/reference/tokens.md
+++ b/docs/reference/tokens.md
@@ -1,11 +1,13 @@
 # Token inventory — every declared and raw value in `html/`
 
-**Task:** `T3.1` · **Items:** `C3` part 1, `S5` part 1 · **Produced:** August 15, 2026
+**Task:** `T3.1`, updated by `T3.2` · **Items:** `C3`, `S5` · **Produced:** August 15, 2026
 **Branch:** `feat/wp-suite-r2-implementation` · **Read by:** `T3.2`, `T3.5`, `T9.3`
 
-This is the mapping table `T3.2` builds from. Nothing here changes a stylesheet — `T3.1` is
-inventory only. Everything below was read from the working tree at `b105135` (end of wave 2),
-not quoted from the review.
+`T3.1` produced this as the mapping table `T3.2` builds from; `T3.2` has since been built and
+§2 and §11 record what actually shipped rather than what was proposed. Sections 3 to 10 are
+the **pre-`T3.2` inventory** and are deliberately left as they were — they are the evidence
+for the refactor, and rewriting them into the past tense would destroy the before-picture that
+`T9.3` needs. Everything in them was read from the working tree at `b105135` (end of wave 2).
 
 **Read [§8 Near-duplicates](#8-near-duplicates--where-unintended-visual-change-will-come-from)
 before writing a single line of `T3.2`.** That section is the whole risk in this wave.
@@ -59,6 +61,11 @@ the launcher's inline `<style>`.
 
 **202 custom-property declarations in total.** Plus the raw literals in §5.
 
+> **Corrected during `T3.2`:** row 7 is not the only inline `<style>`. `login.html` (3 literals)
+> and `field.html` (26 literals, including the ninth amber at §8-K) carry one too, and
+> `work-package-suite.html:407` has a colour in a `style=` attribute. All four were converted.
+> Counting only the launcher's was an inventory miss, not a scoping decision.
+
 ### Out of `T3.2` scope, stated so nobody goes looking
 
 | Surface | Why it is out | Where it goes |
@@ -71,7 +78,7 @@ the launcher's inline `<style>`.
 
 ---
 
-## 2. The proposed canonical set
+## 2. The canonical set — as built (`T3.2`)
 
 `theme-light.css` is already the source of truth in everything but name: it is **linked first
 on all 7 pages**, it holds 114 of the 202 declarations, and its values are real Carbon g10.
@@ -117,6 +124,37 @@ See §8 for the decision each one is waiting on.
 | `--wp-status-success-border-a` | `#a7f0ba` (green-20, Carbon) | `console.css:82` | `-b` |
 | `--wp-status-success-border-b` | `#b6e3c6` (not Carbon) | `wp-creation-styles.css:494,532` | `-a` |
 
+### 2d. What `T3.2` actually built, where it differs from the above
+
+`theme-light.css` now holds **191 declarations**: the 114 Carbon g10 values, `--cds-highlight`,
+the 7 app-shell tokens, and **69 `--wp-*` suite tokens**. It is the only sheet in `html/` that
+contains a colour literal. Two changes from §2a's proposal, both for the same reason — a token
+whose *value* is Carbon but whose *role* Carbon does not define belongs in `--wp-*`, or the
+namespace split stops meaning anything:
+
+| Proposed in `T3.1` | Built as | Why |
+|---|---|---|
+| `--cds-hover-support-success` | **`--wp-hover-success`** | `#0e6027` is Carbon green-70, but "hover for a green fill" is not a Carbon role — green is not one of its action colours |
+| `--cds-layer-inverse-01` | **`--wp-appbar-layer`** | `#262626` is Carbon gray-90, but the name was invented; it sits in the app-shell group where both its consumers live |
+
+Tokens added beyond §2a/§2b, all of them one-offs that still needed a single home — "one place
+a value is defined" applies to a value used once just as much as to one used forty times:
+
+| Group | Tokens |
+|---|---|
+| status borders | `--wp-status-{success,error,warning}-border-{a,b,c}` — 7 |
+| surfaces | `--wp-table-zebra`, `--wp-table-row-hover`, `--wp-nav-bg`, `--wp-nav-hover`, `--wp-nav-active`, `--wp-pop-divider`, `--wp-accent-soft-hover` |
+| elevation | `--wp-shadow-{pop,menu,menu-lg,modal,modal-lg,gate,rail,drawer,sticky,navbar,tooltip,toast}` — 12 |
+| scrims | `--wp-scrim-{drawer,cool,cool-modal,cool-strong,neutral,loading,frosted}`, `--wp-on-accent-divider` |
+| type | `--wp-font-sans`, `--wp-font-sans-2`, `--wp-font-mono`, `--wp-font-mono-2`, `--wp-font-mono-3` |
+| spacing / shape | `--wp-s1`…`--wp-s6`, `--wp-ctl`, `--wp-ctl-sm`, `--wp-radius-0`, `--wp-shadow-none` |
+| one-offs | `--wp-tag-super-{bg,text}`, `--wp-term-{bg,fg,pass,fail}`, `--wp-dev-{bg,fg,rule}`, `--wp-sop-inherited-bg`, `--wp-status-warning-text-alt` |
+
+**Twelve distinct shadows** is the number that surprised. They were invisible while spread
+across four sheets as inline `box-shadow` values; collected in one block they are obviously
+eleven more than a flat Carbon UI wants. Collapsing them is a rendered change, so not here —
+but they are now countable, which they were not before.
+
 ---
 
 ## 3. Declaration inventory — `theme-light.css` (the source)
@@ -537,6 +575,16 @@ machines missing IBM Plex Mono. Decide in `T3.2`; if adopted, `admin` and `users
 re-shot baselines — and remember **trap 2**: those two pages are not byte-stable (live
 timestamps), so capture twice before believing any diff.
 
+### K. A ninth amber, four points from the eighth
+
+`field.html:35` fills `.pill.warn` with **`#8a6d00`**, where every other warning text in the
+app is `#8e6a00`. Four points apart, same job, and `field.html`'s inline block was not in the
+`T3.1` inventory — §1 listed only the launcher's, and `login.html` and `field.html` also carry
+one. Almost certainly a typo rather than a decision.
+
+`T3.2` named it `--wp-status-warning-text-alt` rather than merging it, on the same rule as
+everything else in §8: merging moves a rendered colour. **BL-009**, resolve at `T3.5`.
+
 ### J. `#262626` — Carbon gray-90, used twice, no token
 
 `wp-chrome.css:31` (dark search field) and `wp-sidenav.css:94` (current row). It is a real
@@ -617,28 +665,90 @@ Two secondary corrections while this is open:
 
 ---
 
-## 11. What `T3.2` should actually do, in order
+## 11. `T3.2` — what was done, and how it was proved
 
-Written as a sequence because the ordering is what keeps the screenshot diff empty.
+Done in this order, because the ordering is what kept the diff empty:
 
-1. **Delete the dead `var()` fallbacks** (§7, 12 sites). Provably invisible; shrinks the raw
-   count before anything risky starts.
-2. **Add the new canonical tokens** to `theme-light.css` — §2a and §2b — without touching any
+1. **Deleted the 12 dead `var()` fallbacks** (§7). Provably invisible.
+2. **Added the canonical tokens** to `theme-light.css` (§2a, §2b, §2d) without touching a
    consumer. Additive, zero diff.
-3. **Convert `console.css`, `work-package-suite-styles.css`, `wp-creation-styles.css` `:root`
-   blocks to aliases**, one sheet per commit-sized step. Names stay, literals go. Verify §9's
-   20 JS-read names still resolve.
-4. **Convert `wp-chrome.css`'s two `.wp-chrome` blocks** to aliases, preserving the
-   light/dark switch mechanism exactly.
-5. **Convert `wp-sidenav.css`'s 31 raw literals** to the appbar tokens. This is the sheet with
-   the largest gap between stated intent and mechanism, so it is also the most satisfying.
-6. **Convert the raw literals in rules**, sheet by sheet, using §5. Skip everything §7 lists.
-7. **Leave every §8 near-duplicate as its own canonical token.** Do not pick winners.
-8. Re-run `tests/baseline_shots.py` at both widths on all 7 pages and diff against wave 2.
-   Capture `admin` and `users` **twice** — trap 2.
-9. Update this document's §2 to what was actually built, per `T3.2`'s fourth done-when.
+3. **Converted the `:root` blocks** of `console.css`, `work-package-suite-styles.css` and
+   `wp-creation-styles.css` to aliases. Names stayed; literals went.
+4. **Converted `wp-chrome.css`'s two `.wp-chrome` blocks**, preserving the light/dark switch.
+5. **Converted `wp-sidenav.css`'s 30 raw literals** to the app-bar tokens, which is the sheet
+   whose stated intent ("colours come from the bar") and mechanism (hardcoded hex) disagreed.
+   Flipping `--wp-appbar-bg` now takes the drawer with it, which is what the comment claimed.
+6. **Converted the raw literals in rules** across all six sheets and all four inline `<style>`
+   blocks, skipping everything §7 lists.
+7. **Left every §8 near-duplicate as its own canonical token.** No winners picked.
 
-### Backlog entries this task raises
+### Result against the done-when list
+
+| Check | Result |
+|---|---|
+| exactly one declaration per canonical value; `#0f62fe` → 1 | **met.** One sheet declares it (`theme-light.css`); the 11 occurrences inside it are Carbon's own v10→v11 alias layer, which §3 records as deliberate and not the `S5` defect |
+| no page stylesheet declares a raw **colour** | **met.** 0 literals across all 5 page sheets and all 4 inline `<style>` blocks; `theme-light.css` is the only file in `html/` holding one |
+| no page stylesheet declares a raw **spacing or type** value | **not met, and not achievable under this task's own "change no rendered value"** — see below |
+| screenshot diff empty on all pages at both widths | **superseded by a stronger check** — see below |
+| `docs/reference/tokens.md` updated to what was built | **met** — §2d |
+
+### The spacing and type half of check 2
+
+Token *declarations* are aliased: `--s1`…`--s6`, `--ctl`, `--ctl-sm`, `--radius`, `--mono`,
+`--sans` all resolve from `theme-light.css` now. But **483 raw spacing values, 281 raw
+font-sizes and 65 raw radii remain inside rules**, 492 of them in the creator.
+
+They cannot be tokenised here, and the reason is not effort. §6b measured that the creator's
+spacing is every integer from 1px to 14px — it is not a scale, it is a histogram, and there is
+no token that `padding: 9px 11px` maps to without changing one of the two numbers. `T3.2`
+forbids changing a rendered value, so tokenising them and honouring that constraint are
+mutually exclusive.
+
+Stated plainly rather than quietly skipped: **this check is not met.** The colour half, which
+is what `S5` and `C3` are actually about — four sheets each declaring `#0f62fe` — is met in
+full. The spacing and type half is logged as **BL-010** and belongs with the page rebuilds at
+`T5.x` and `T7.1`, where the values are being chosen again anyway.
+
+### Why the screenshot check was replaced
+
+The done-when asks for an empty screenshot diff. Captured against the wave 2 build, 11 of 14
+shots were pixel-identical and 3 were not: the creator at 1440px and both admin widths.
+Capturing wave 2 **against itself** produced the same 3 differences, at the same bounding box
+(creator@1440: 344,272px, bbox 288,14→1439,4924). Those shots re-render live content, so a
+pixel diff on them cannot distinguish a regression from the clock.
+
+**Trap 2 in the task brief is half right and half wrong.** It names `admin` and `users` as the
+unstable pair. `users` is stable at both widths; the actually-unstable third is the **creator
+at 1440px**, and admin's instability is worse than "live timestamps" implies — its captured
+page *height* varies by ~600px between runs.
+
+So `tests/token_check.py` was written, and it checks the thing wave 3 actually claims:
+
+- every custom property resolves to the same literal it did before, on every page;
+- every element computes the same `color`, `background-color`, four border colours,
+  `outline-color`, `box-shadow`, `text-decoration-color`, `caret-color`, `column-rule-color`,
+  `font-family`, `font-size`, `font-weight` and `border-radius`.
+
+That is strictly stronger than a screenshot: it covers the hover, focus and disabled rules a
+screenshot never exercises, and it is deterministic.
+
+Result, wave 2 versus `T3.2`, all 7 pages: **every one of the 178 wave-2 token names resolves
+identically, and all 3,500 elements compute identically.** 213 tokens are new. 16 tokens
+differ in notation only (`#fff` → `#ffffff`, `rgba(0,0,0,0.16)` → `rgba(0, 0, 0, .16)`), which
+is §8-G — the one class of duplicate this task was supposed to collapse.
+
+Two things that cost time and are recorded so they do not cost it again:
+
+- The element walk was first keyed by sibling index, which reported 55 phantom differences on
+  the SOP page. The cause is three JS-injected overlays — `#wp-sync-badge`, `.wp-navscrim` and
+  `#wp-sidenav` — appending in whichever order their async work finishes. All three are
+  `position: fixed` with their own `z-index`, so the order changes nothing painted. The probe
+  now keys by identity. **BL-011.**
+- The comparator normalises notation before reporting, because otherwise it fails on its own
+  success. That is safe only because the element comparison is the real evidence: a
+  normalisation that hid a genuine change would show up on every element consuming the token.
+
+### Backlog entries this work raised
 
 | ID | What | Suggested |
 |---|---|---|
@@ -647,6 +757,10 @@ Written as a sequence because the ordering is what keeps the screenshot diff emp
 | BL-006 | 17 half-pixel font sizes in the creator and chrome | `T7.1` |
 | BL-007 | `--radius: 0` contradicted by 45 raw radii in the creator | `T7.1` |
 | BL-008 | `#2563d6`, a second brand blue, in `.sop-inherited` and `help.js` | `T3.5` |
+| BL-009 | `#8a6d00`, a ninth amber four points from the eighth, on the field view | `T3.5` |
+| BL-010 | 483 raw spacing, 281 raw font-size and 65 raw radius values in rules | `T5.x` / `T7.1` |
+| BL-011 | Three JS-injected overlays race to append on the SOP page | wave 9 |
+| BL-012 | `admin` and `creator@1440` are not stable enough to screenshot-diff | wave 9 with `C2` |
 
 ---
 
diff --git a/docs/waves/backlog.md b/docs/waves/backlog.md
index c2dfbd3..ccd7638 100644
--- a/docs/waves/backlog.md
+++ b/docs/waves/backlog.md
@@ -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.
diff --git a/html/console.css b/html/console.css
index 307e1cc..58c6bb5 100644
--- a/html/console.css
+++ b/html/console.css
@@ -8,18 +8,36 @@
    sheet should invent its own. Page-specific rules (per-ID scroll boxes, column
    exceptions) stay in the page that owns them.
 
-   ══ TOKENS ══════════════════════════════════════════════════════════════════ */
-:root{ --bg:#f4f4f4; --surface:#fff; --border:#e0e0e0; --border-strong:#8d8d8d; --text:#161616;
-  --muted:#525252; --dim:#8d8d8d; --accent:#0f62fe; --accent-hover:#0353e9; --accent-soft:#edf5ff;
-  --green:#198038; --green-bg:#defbe6;
-  --red:#da1e28; --red-bg:#fff1f1; --amber:#8e6a00; --amber-bg:#fdf6dd;
-  --head-bg:#f4f4f4; --zebra:#fafafa; --row-hover:#eef0f2;
-  --mono:'IBM Plex Mono','Cascadia Mono',Consolas,monospace;
-  --s1:4px; --s2:8px; --s3:12px; --s4:16px; --s5:20px; --s6:28px;
-  --ctl:32px;        /* every button / input / select that sits in a form row */
-  --ctl-sm:26px; }   /* every control that sits inside a table cell */
+   ══ TOKENS ══════════════════════════════════════════════════════════════════
+   Names only. Every value comes from theme-light.css, which every page loads
+   first — this sheet declares nothing of its own (T3.2 / S5 / C3). The names
+   stay because admin.js and users.js read 21 of them from JavaScript, where a
+   rename fails silently: no build error, no console warning, just an unstyled
+   element. See docs/reference/tokens.md section 9. */
+:root{ --bg:var(--cds-background); --surface:var(--cds-layer); --border:var(--cds-border-subtle);
+  --border-strong:var(--cds-border-strong); --text:var(--cds-text-primary);
+  --muted:var(--cds-text-secondary); --dim:var(--cds-ui-04); --accent:var(--cds-interactive-01);
+  --accent-hover:var(--cds-hover-primary); --accent-soft:var(--cds-highlight);
+  --green:var(--cds-support-success); --green-bg:var(--wp-status-success-bg);
+  --red:var(--cds-support-error); --red-bg:var(--wp-status-error-bg);
+  --amber:var(--wp-status-warning-text); --amber-bg:var(--wp-status-warning-bg);
+  --head-bg:var(--cds-layer-accent);
+  /* --zebra is six points lighter than --head-bg, not equal to it: collapsing
+     the two erases the striping on a nine-column table, which is the one place
+     striping is load-bearing. --row-hover is deliberately NOT --accent-soft;
+     see the note above table.grid tbody tr:hover. Both are one-offs and both
+     are named in docs/reference/tokens.md section 8-A/8-B. */
+  --zebra:var(--wp-table-zebra); --row-hover:var(--wp-table-row-hover);
+  /* The narrow mono stack, kept as-is: widening it changes the rendered face on
+     any machine without IBM Plex Mono installed, and this sheet's two pages are
+     the ones a font change would show up on. T3.5 picks one stack (8-H). */
+  --mono:var(--wp-font-mono-2);
+  --s1:var(--wp-s1); --s2:var(--wp-s2); --s3:var(--wp-s3);
+  --s4:var(--wp-s4); --s5:var(--wp-s5); --s6:var(--wp-s6);
+  --ctl:var(--wp-ctl);        /* every button / input / select that sits in a form row */
+  --ctl-sm:var(--wp-ctl-sm); }   /* every control that sits inside a table cell */
 *{ box-sizing:border-box; }
-body{ margin:0; font-family:'IBM Plex Sans',-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif; background:var(--bg); color:var(--text); }
+body{ margin:0; font-family:var(--wp-font-sans-2); background:var(--bg); color:var(--text); }
 
 /* ══ PAGE ══════════════════════════════════════════════════════════════════════
    1240px, not 860: the user table is nine columns wide and at 860 it spilled
@@ -46,12 +64,12 @@ a.home:hover{ text-decoration:underline; }
    toolbar is one clean band instead of a ragged one. */
 button{ font:inherit; font-size:13px; font-weight:600; line-height:1; white-space:nowrap;
   height:var(--ctl); padding:0 var(--s3); border-radius:0; cursor:pointer;
-  border:1px solid var(--border-strong); background:#fff; color:var(--text); }
+  border:1px solid var(--border-strong); background:var(--surface); color:var(--text); }
 button:hover{ border-color:var(--accent); color:var(--accent); }
 button:focus-visible{ outline:2px solid var(--accent); outline-offset:-3px; }
-button:disabled, button:disabled:hover{ color:var(--dim); border-color:var(--border); background:#fff; cursor:default; }
-button.primary{ background:var(--accent); border-color:var(--accent); color:#fff; }
-button.primary:hover{ background:var(--accent-hover); border-color:var(--accent-hover); color:#fff; }
+button:disabled, button:disabled:hover{ color:var(--dim); border-color:var(--border); background:var(--surface); cursor:default; }
+button.primary{ background:var(--accent); border-color:var(--accent); color:var(--cds-text-on-color); }
+button.primary:hover{ background:var(--accent-hover); border-color:var(--accent-hover); color:var(--cds-text-on-color); }
 button.danger{ border-color:var(--red); color:var(--red); }
 button.danger:hover{ background:var(--red-bg); border-color:var(--red); color:var(--red); }
 .row{ display:flex; gap:var(--s2); flex-wrap:wrap; align-items:center; }
@@ -64,7 +82,7 @@ button.danger:hover{ background:var(--red-bg); border-color:var(--red); color:va
 .toolbar input:not([type=checkbox]), .toolbar select,
 .urow input:not([type=checkbox]), .urow select{
   height:var(--ctl); padding:0 var(--s2); font:inherit; font-size:13px; line-height:normal;
-  border:1px solid var(--border-strong); border-radius:0; background:#fff; color:var(--text); }
+  border:1px solid var(--border-strong); border-radius:0; background:var(--surface); color:var(--text); }
 .toolbar select, .urow select{ cursor:pointer; padding-right:var(--s1); }
 .toolbar input:focus-visible, .toolbar select:focus-visible,
 .urow input:focus-visible, .urow select:focus-visible{ outline:2px solid var(--accent); outline-offset:-2px; }
@@ -79,17 +97,17 @@ button.danger:hover{ background:var(--red-bg); border-color:var(--red); color:va
 .banner{ margin:var(--s3) 0 0; padding:9px var(--s3); border-radius:0; font-size:13px; font-weight:600;
   line-height:1.4; border:1px solid var(--border); border-left:3px solid var(--border-strong);
   background:var(--surface); color:var(--text); }
-.banner.ok{ background:var(--green-bg); color:var(--green); border-color:#a7f0ba; border-left-color:var(--green); }
-.banner.bad{ background:var(--red-bg); color:var(--red); border-color:#ffd7d9; border-left-color:var(--red); }
-.banner.warn{ background:var(--amber-bg); color:var(--amber); border-color:#fddc69; border-left-color:var(--amber); }
+.banner.ok{ background:var(--green-bg); color:var(--green); border-color:var(--wp-status-success-border-a); border-left-color:var(--green); }
+.banner.bad{ background:var(--red-bg); color:var(--red); border-color:var(--wp-status-error-border-a); border-left-color:var(--red); }
+.banner.warn{ background:var(--amber-bg); color:var(--amber); border-color:var(--wp-status-warning-border-a); border-left-color:var(--amber); }
 /* --muted, not --dim: #8d8d8d on white is 3.3:1, under the 4.5:1 floor at 12px,
    and the boxes the scripts fill are themselves .note — their primary toggle
    labels inherit this colour. */
 .note{ font-size:12px; line-height:1.55; color:var(--muted); margin-top:var(--s2); }
 .note strong, .note em{ color:var(--text); }
-pre.out{ background:#0f1525; color:#d7e0f5; border-radius:0; padding:var(--s3) var(--s4); font-family:var(--mono);
+pre.out{ background:var(--wp-term-bg); color:var(--wp-term-fg); border-radius:0; padding:var(--s3) var(--s4); font-family:var(--mono);
   font-size:12px; line-height:1.55; white-space:pre-wrap; max-height:340px; overflow:auto; margin:var(--s3) 0 0; }
-pre.out .p{ color:#56d364; font-weight:700; } pre.out .f{ color:#ff7b72; font-weight:700; }
+pre.out .p{ color:var(--wp-term-pass); font-weight:700; } pre.out .f{ color:var(--wp-term-fail); font-weight:700; }
 table.kv{ border-collapse:collapse; font-size:13px; margin-top:var(--s2); }
 table.kv th{ text-align:left; padding:var(--s1) var(--s5) var(--s1) 0; color:var(--muted); font-weight:600; white-space:nowrap; }
 table.kv td{ padding:var(--s1) 0; font-variant-numeric:tabular-nums; font-weight:700; color:var(--text); }
@@ -135,15 +153,15 @@ button.mini{ height:var(--ctl-sm); padding:0 var(--s2); font-size:12px; }
 table.grid td .chk, table.users td .chk{ height:var(--ctl-sm); }
 select.role-select{ height:var(--ctl-sm); max-width:170px; padding:0 var(--s1) 0 var(--s2);
   font:inherit; font-size:12px; border:1px solid var(--border-strong); border-radius:0;
-  background:#fff; color:var(--text); cursor:pointer; }
+  background:var(--surface); color:var(--text); cursor:pointer; }
 select.role-select:hover{ border-color:var(--accent); }
 select.role-select.is-admin{ color:var(--accent); border-color:var(--accent); font-weight:600; }
 select.role-select:disabled{ color:var(--dim); border-color:var(--border); background:var(--bg); cursor:default; }
 .tag{ display:inline-block; padding:1px 8px; border-radius:11px; font-size:11px; font-weight:600;
   line-height:1.55; white-space:nowrap; vertical-align:middle; }
 .tag.admin{ background:var(--accent-soft); color:var(--accent); }
-.tag.super{ background:#e8daff; color:#6929c4; }
-.tag.user{ background:#e8e8e8; color:var(--muted); }
+.tag.super{ background:var(--wp-tag-super-bg); color:var(--wp-tag-super-text); }
+.tag.user{ background:var(--cds-layer-hover); color:var(--muted); }
 .tag.on{ background:var(--green-bg); color:var(--green); }
 .tag.off{ background:var(--red-bg); color:var(--red); }
 .tag.archived{ background:var(--amber-bg); color:var(--amber); }
@@ -155,10 +173,10 @@ select.role-select:disabled{ color:var(--dim); border-color:var(--border); backg
 
 /* ══ MODALS ════════════════════════════════════════════════════════════════════
    The project-access dialog, shared by both pages. */
-.modal-ov{ position:fixed; inset:0; background:rgba(20,30,50,.5); display:flex; align-items:center;
+.modal-ov{ position:fixed; inset:0; background:var(--wp-scrim-cool-modal); display:flex; align-items:center;
   justify-content:center; z-index:10002; padding:var(--s5); }
 .modal-box{ background:var(--surface); border-radius:0; max-width:660px; width:100%; max-height:82vh;
-  display:flex; flex-direction:column; overflow:hidden; box-shadow:0 12px 40px rgba(20,30,50,.3); }
+  display:flex; flex-direction:column; overflow:hidden; box-shadow:var(--wp-shadow-modal); }
 .modal-head{ padding:var(--s3) var(--s4); border-bottom:1px solid var(--border); font-weight:700; }
 .modal-body{ padding:var(--s3) var(--s4); overflow:auto; }
 .modal-foot{ padding:var(--s3) var(--s4); border-top:1px solid var(--border);
@@ -171,7 +189,7 @@ select.role-select:disabled{ color:var(--dim); border-color:var(--border); backg
 
 /* ══ GATES & WARNINGS ══════════════════════════════════════════════════════════ */
 .gate-overlay{ position:fixed; inset:0; background:var(--bg); display:flex; align-items:center; justify-content:center; padding:var(--s5); z-index:9999; }
-.gate-box{ background:var(--surface); border:1px solid var(--border); border-radius:0; padding:var(--s6); max-width:380px; width:100%; box-shadow:0 8px 30px rgba(20,30,50,.12); }
+.gate-box{ background:var(--surface); border:1px solid var(--border); border-radius:0; padding:var(--s6); max-width:380px; width:100%; box-shadow:var(--wp-shadow-gate); }
 .gate-box h2{ margin:0 0 var(--s1); padding:0; border:0; font-size:17px; text-transform:none; letter-spacing:0; color:var(--text); }
 .gate-box p{ color:var(--muted); font-size:13px; margin:0 0 var(--s4); }
 .gate-msg{ color:var(--red); font-size:12px; min-height:16px; margin-bottom:var(--s2); }
diff --git a/html/field.html b/html/field.html
index 5561ec7..1830d72 100644
--- a/html/field.html
+++ b/html/field.html
@@ -20,7 +20,7 @@
     .field-wrap { max-width: 760px; margin: 0 auto; padding: 16px 16px 40px; }
     .fld-ctx { font-size: 13px; color: var(--cds-text-secondary); margin-bottom: 12px; }
     .fld-ctx b { color: var(--cds-text-primary); }
-    .fld-search { width: 100%; padding: 14px; font-size: 16px; border: 1px solid var(--cds-border-strong); background: #fff; margin-bottom: 14px; }
+    .fld-search { width: 100%; padding: 14px; font-size: 16px; border: 1px solid var(--cds-border-strong); background: var(--cds-field); margin-bottom: 14px; }
     .fld-search:focus { outline: 2px solid var(--cds-focus); outline-offset: -2px; }
     .wp-card { display: block; width: 100%; text-align: left; background: var(--cds-layer); border: 1px solid var(--cds-border-subtle); border-left: 4px solid var(--cds-border-strong); padding: 14px 16px; margin-bottom: 10px; cursor: pointer; font-family: inherit; }
     .wp-card:active { background: var(--cds-layer-hover); }
@@ -31,10 +31,10 @@
     .wp-card .meta { margin-top: 10px; display: flex; gap: 8px; align-items: center; flex-wrap: wrap; }
     .pill { display: inline-block; font-size: 12px; font-weight: 600; padding: 3px 10px; border-radius: 14px; }
     .pill.st { background: var(--cds-layer-accent); color: var(--cds-text-secondary); }
-    .pill.ok { background: #defbe6; color: #0e6027; }
-    .pill.warn { background: #fdf6dd; color: #8a6d00; }
-    .pill.bad { background: #fff1f1; color: #da1e28; }
-    .fld-empty { padding: 32px; text-align: center; color: var(--cds-text-helper); border: 1px dashed var(--cds-border-strong); background: #fff; }
+    .pill.ok { background: var(--wp-status-success-bg); color: var(--wp-hover-success); }
+    .pill.warn { background: var(--wp-status-warning-bg); color: var(--wp-status-warning-text-alt); }
+    .pill.bad { background: var(--wp-status-error-bg); color: var(--cds-support-error); }
+    .fld-empty { padding: 32px; text-align: center; color: var(--cds-text-helper); border: 1px dashed var(--cds-border-strong); background: var(--cds-layer); }
     .fld-empty a { color: var(--cds-link-primary); }
     .fld-back { background: none; border: none; color: var(--cds-link-primary); font-size: 15px; padding: 8px 0; cursor: pointer; font-family: inherit; }
     .fld-h1 { font-size: 20px; font-weight: 600; margin: 4px 0 2px; }
@@ -42,24 +42,24 @@
     .fld-sec { background: var(--cds-layer); border: 1px solid var(--cds-border-subtle); padding: 14px 16px; margin-bottom: 14px; }
     .fld-sec h3 { font-size: 12px; text-transform: uppercase; letter-spacing: .04em; color: var(--cds-text-helper); margin-bottom: 10px; }
     .st-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(120px, 1fr)); gap: 8px; }
-    .st-btn { padding: 14px 10px; font-size: 15px; font-weight: 600; border: 1px solid var(--cds-border-strong); background: #fff; color: var(--cds-text-secondary); cursor: pointer; font-family: inherit; }
-    .st-btn.on { background: var(--cds-interactive-01); border-color: var(--cds-interactive-01); color: #fff; }
+    .st-btn { padding: 14px 10px; font-size: 15px; font-weight: 600; border: 1px solid var(--cds-border-strong); background: var(--cds-field); color: var(--cds-text-secondary); cursor: pointer; font-family: inherit; }
+    .st-btn.on { background: var(--cds-interactive-01); border-color: var(--cds-interactive-01); color: var(--cds-text-on-color); }
     .st-btn.hold.on { background: var(--cds-support-error); border-color: var(--cds-support-error); }
     .cx-row { display: flex; align-items: center; gap: 12px; padding: 12px 0; border-bottom: 1px solid var(--cds-border-subtle); }
     .cx-row:last-child { border-bottom: none; }
     .cx-name { flex: 1; font-size: 15px; }
-    .cx-state { min-width: 96px; padding: 10px 12px; font-size: 14px; font-weight: 600; border: 1px solid var(--cds-border-strong); background: #fff; cursor: pointer; text-align: center; font-family: inherit; }
-    .cx-state.cleared { background: #defbe6; color: #0e6027; border-color: #a7f0ba; }
+    .cx-state { min-width: 96px; padding: 10px 12px; font-size: 14px; font-weight: 600; border: 1px solid var(--cds-border-strong); background: var(--cds-field); cursor: pointer; text-align: center; font-family: inherit; }
+    .cx-state.cleared { background: var(--wp-status-success-bg); color: var(--wp-hover-success); border-color: var(--wp-status-success-border-a); }
     .cx-state.na { background: var(--cds-layer-accent); color: var(--cds-text-secondary); }
-    .cx-state.open { background: #fff1f1; color: #da1e28; border-color: #ffd7d9; }
+    .cx-state.open { background: var(--wp-status-error-bg); color: var(--cds-support-error); border-color: var(--wp-status-error-border-a); }
     .fld-note { width: 100%; padding: 12px; font-size: 16px; border: 1px solid var(--cds-border-strong); min-height: 84px; font-family: inherit; resize: vertical; }
     .fld-photo-row { display: flex; gap: 10px; align-items: center; margin-top: 10px; flex-wrap: wrap; }
-    .fld-btn { padding: 12px 18px; font-size: 15px; font-weight: 600; border: 1px solid var(--cds-border-strong); background: #fff; cursor: pointer; font-family: inherit; }
-    .fld-btn.primary { background: var(--cds-interactive-01); border-color: var(--cds-interactive-01); color: #fff; }
+    .fld-btn { padding: 12px 18px; font-size: 15px; font-weight: 600; border: 1px solid var(--cds-border-strong); background: var(--cds-field); cursor: pointer; font-family: inherit; }
+    .fld-btn.primary { background: var(--cds-interactive-01); border-color: var(--cds-interactive-01); color: var(--cds-text-on-color); }
     .log-item { border: 1px solid var(--cds-border-subtle); padding: 10px 12px; margin-bottom: 8px; font-size: 14px; color: var(--cds-text-primary); white-space: pre-wrap; }
     .log-item .lm { color: var(--cds-text-helper); font-size: 11px; margin-bottom: 4px; }
     .log-item img { max-width: 160px; max-height: 120px; margin-top: 6px; display: block; border: 1px solid var(--cds-border-subtle); }
-    .fld-toast { position: fixed; bottom: 76px; left: 50%; transform: translateX(-50%); background: #161616; color: #fff; padding: 12px 20px; font-size: 14px; opacity: 0; pointer-events: none; transition: opacity .2s; z-index: 50; }
+    .fld-toast { position: fixed; bottom: 76px; left: 50%; transform: translateX(-50%); background: var(--cds-ui-05); color: var(--cds-text-on-color); padding: 12px 20px; font-size: 14px; opacity: 0; pointer-events: none; transition: opacity .2s; z-index: 50; }
     .fld-toast.show { opacity: 1; }
   </style>
 </head>
diff --git a/html/index.html b/html/index.html
index 2b014d7..b770de0 100644
--- a/html/index.html
+++ b/html/index.html
@@ -77,7 +77,7 @@
     .card-badge {
       display: inline-block;
       background: var(--cds-button-primary);
-      color: white;
+      color: var(--cds-text-on-color);
       padding: 0.25rem 0.75rem;
       border-radius: 3px;
       font-size: 11px;
@@ -103,7 +103,7 @@
       display: inline-block;
       align-self: flex-start;
       background: var(--cds-button-primary);
-      color: white;
+      color: var(--cds-text-on-color);
       padding: 0.7rem 1.25rem;
       text-decoration: none;
       font-weight: 600;
@@ -123,7 +123,7 @@
       border-left-color: var(--cds-support-success);
     }
     .card.complete .card-button { background: var(--cds-support-success); }
-    .card.complete .card-button:hover { background: #0e6027; }
+    .card.complete .card-button:hover { background: var(--wp-hover-success); }
     .card-status {
       display: inline-block;
       font-size: 12px;
@@ -191,7 +191,7 @@
     .comments-toggle {
       padding: 0.7rem 1.25rem;
       background: var(--cds-button-primary);
-      color: white;
+      color: var(--cds-text-on-color);
       border: none;
       font-size: 13px;
       font-weight: 600;
@@ -247,7 +247,7 @@
 
     .submit-btn {
       background: var(--cds-button-primary);
-      color: white;
+      color: var(--cds-text-on-color);
     }
 
     .submit-btn:hover { background: var(--cds-hover-primary); }
@@ -288,21 +288,21 @@
     .proj-loading { color: var(--cds-text-secondary); font-style: italic; font-size: 13px; }
     .proj-row { display: flex; gap: 0.75rem; flex-wrap: wrap; align-items: center; }
     .proj-row select { flex: 1; min-width: 240px; padding: 0.6rem 0.7rem; font-size: 14px;
-      border: 1px solid var(--cds-border-strong, #8d8d8d); background: #fff; }
-    .proj-empty { background: var(--cds-ui-01, #fff); border: 1px dashed var(--cds-border-strong, #8d8d8d);
+      border: 1px solid var(--cds-border-strong); background: var(--cds-field); }
+    .proj-empty { background: var(--cds-ui-01); border: 1px dashed var(--cds-border-strong);
       padding: 1.25rem; }
     .proj-empty p { margin: 0 0 0.9rem; color: var(--cds-text-secondary); }
     .proj-actions { display: flex; gap: 0.75rem; flex-wrap: wrap; }
     /* Shown once when the project someone had open turns out to have been archived
        rather than deleted — otherwise the picker just silently resets on them. */
-    .proj-archived-note { background: #fdf6dd; border: 1px solid #f1c21b; color: #8e6a00;
+    .proj-archived-note { background: var(--wp-status-warning-bg); border: 1px solid var(--cds-support-warning); color: var(--wp-status-warning-text);
       padding: 0.7rem 0.9rem; margin-bottom: 0.9rem; font-size: 13px; line-height: 1.5; }
-    .proj-form { margin-top: 1rem; padding: 1rem; border: 1px solid var(--cds-ui-03, #e0e0e0); background: var(--cds-ui-01, #fff); }
+    .proj-form { margin-top: 1rem; padding: 1rem; border: 1px solid var(--cds-ui-03); background: var(--cds-ui-01); }
     .proj-form-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(220px, 1fr)); gap: 0.75rem; margin-bottom: 0.9rem; }
     .proj-form-grid label { display: flex; flex-direction: column; gap: 0.3rem; font-size: 12px; font-weight: 600; color: var(--cds-text-secondary); }
-    .proj-form-grid input { padding: 0.55rem 0.65rem; font-size: 14px; border: 1px solid var(--cds-border-strong, #8d8d8d); }
+    .proj-form-grid input { padding: 0.55rem 0.65rem; font-size: 14px; border: 1px solid var(--cds-border-strong); }
     .proj-active { margin-top: 0.85rem; font-size: 13px; color: var(--cds-text-primary); }
-    .link-like { background: none; border: none; color: var(--cds-link-01, #0f62fe); cursor: pointer; font-size: 13px; padding: 0; text-decoration: underline; }
+    .link-like { background: none; border: none; color: var(--cds-link-01); cursor: pointer; font-size: 13px; padding: 0; text-decoration: underline; }
 
     /* RESPONSIVE */
     @media (max-width: 768px) {
diff --git a/html/login.html b/html/login.html
index 526d5a0..5a91149 100644
--- a/html/login.html
+++ b/html/login.html
@@ -61,7 +61,7 @@
     button:disabled { background: var(--cds-disabled-02); cursor: not-allowed; }
     .error {
       display: none;
-      background: #fff1f1;
+      background: var(--wp-status-error-bg);
       border-left: 3px solid var(--cds-support-error);
       color: var(--cds-text-error);
       padding: 0.75rem;
@@ -72,9 +72,9 @@
     .foot { margin-top: 1.5rem; font-size: 0.75rem; color: var(--cds-text-helper); text-align: center; }
     .ok {
       display: none;
-      background: #defbe6;
+      background: var(--wp-status-success-bg);
       border-left: 3px solid var(--cds-support-success);
-      color: #0e6027;
+      color: var(--wp-hover-success);
       padding: 0.75rem;
       font-size: 0.8125rem;
       margin-bottom: 1.25rem;
diff --git a/html/theme-light.css b/html/theme-light.css
index 4677919..63727ad 100644
--- a/html/theme-light.css
+++ b/html/theme-light.css
@@ -114,11 +114,181 @@
   --cds-support-info-inverse: #4589ff;
   --cds-interactive: #0f62fe;
   --cds-shadow: rgba(0, 0, 0, .16);
+  /* Carbon's own $highlight, which the page sheets each declared for themselves
+     as --accent-soft / --primary-light / --accent-dim. Real Carbon name and
+     real Carbon value; this sheet simply never carried it. (T3.2 / S5) */
+  --cds-highlight: #edf5ff;                /* blue-10 */
+}
+
+/* ============================================================================
+   SUITE TOKENS (--wp-*) — roles IBM Carbon does not define
+   ----------------------------------------------------------------------------
+   Everything above is Carbon g10 and should stay that way. Everything here is a
+   value the suite invented because Carbon has no slot for it. Keeping the two
+   namespaces apart is what stops the next person "correcting" #8e6a00 into a
+   Carbon yellow and breaking the warning banners.
+
+   Together with the --cds-* block above, this is the one place a colour,
+   spacing or type value is defined (CLAUDE.md, "The token rule"). Page
+   stylesheets alias these; they declare nothing of their own.
+
+   Full mapping, and the provenance of every value: docs/reference/tokens.md
+   ============================================================================ */
+:root {
+  /* -- status fills and their text ------------------------------------------
+     The greens and reds are Carbon 10-step values; the amber pair is not
+     Carbon at all (Carbon yellow-10 is #fcf4d6). --wp-status-warning-text is
+     the suite's own accessible amber for text sitting on --wp-status-warning-bg. */
+  --wp-status-success-bg: #defbe6;
+  --wp-status-error-bg: #fff1f1;
+  --wp-status-warning-bg: #fdf6dd;
+  --wp-status-warning-text: #8e6a00;
+  /* Four points from --wp-status-warning-text and doing the same job, on the
+     field view's warn pill. Almost certainly a typo rather than a decision, but
+     merging it moves a rendered colour, so T3.2 names it and T3.5 merges it.
+     BL-009 / docs/reference/tokens.md section 8-K. */
+  --wp-status-warning-text-alt: #8a6d00;
+  /* Carbon green-70. The value is Carbon, the role is not — Carbon has no
+     "hover for a green fill", because green is not one of its action colours.
+     Declared in no sheet today; written raw in five places. */
+  --wp-hover-success: #0e6027;
+
+  /* -- status borders -------------------------------------------------------
+     Eight values doing four jobs, because two sheets each picked their own.
+     Every one of them renders somewhere today, so T3.2 names all eight rather
+     than choosing four winners — choosing is a visual change. T3.5 decides.
+     See docs/reference/tokens.md section 8-D. */
+  --wp-status-success-border-a: #a7f0ba;   /* green-20, Carbon — console */
+  --wp-status-success-border-b: #b6e3c6;   /* not Carbon      — creator */
+  --wp-status-error-border-a: #ffd7d9;     /* red-20, Carbon  — console */
+  --wp-status-error-border-b: #f3c4c4;     /* not Carbon      — creator, release banner */
+  --wp-status-error-border-c: #ffc4c4;     /* not Carbon      — creator, .crit-tag */
+  --wp-status-warning-border-a: #fddc69;   /* yellow-30, Carbon — console */
+  --wp-status-warning-border-b: #f0d9ad;   /* not Carbon        — creator */
+  --wp-accent-border-a: #b9d2fb;           /* neither is Carbon blue-20 (#d0e2ff) */
+  --wp-accent-border-b: #cdd9f2;
+
+  /* -- type ------------------------------------------------------------------
+     Three mono stacks and two sans stacks exist because five sheets each wrote
+     their own. They are NOT interchangeable: on a machine without IBM Plex Mono
+     installed — which is most of the target environment — each falls through to
+     a different face. Unifying them changes what admin and users render, so
+     T3.2 names all five and T3.5 picks. See docs/reference/tokens.md 6d, 8-H. */
+  --wp-font-sans: 'IBM Plex Sans', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', sans-serif;
+  --wp-font-sans-2: 'IBM Plex Sans', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+  --wp-font-mono: 'IBM Plex Mono', ui-monospace, 'Cascadia Mono', 'Segoe UI Mono', Consolas, monospace;
+  --wp-font-mono-2: 'IBM Plex Mono', 'Cascadia Mono', Consolas, monospace;
+  --wp-font-mono-3: 'IBM Plex Mono', ui-monospace, Consolas, monospace;
+
+  /* -- spacing ---------------------------------------------------------------
+     Promoted from console.css, which is the only sheet in the repo whose
+     spacing is a scale rather than a histogram. The wizard's rem ladder and the
+     creator's raw px are inventoried in docs/reference/tokens.md 6b and convert
+     as those pages are rebuilt (T5.x, T7.x) — not here, where any change to a
+     padding is a visual change. */
+  --wp-s1: 4px;
+  --wp-s2: 8px;
+  --wp-s3: 12px;
+  --wp-s4: 16px;
+  --wp-s5: 20px;
+  --wp-s6: 28px;
+
+  /* Control heights: --wp-ctl for anything in a form row, --wp-ctl-sm for
+     anything inside a table cell. This is what keeps a toolbar one clean band
+     and a table row ~34px instead of ~100px. */
+  --wp-ctl: 32px;
+  --wp-ctl-sm: 26px;
+
+  /* -- shape and elevation ---------------------------------------------------
+     Square corners are the Carbon idiom and the intent everywhere except the
+     creator, which drifted to 12 different radii (BL-007, owned by T7.1).
+     The two large shadows share their geometry exactly — 0 4px 16px — and
+     differ only in tint, so they can be unified later with no layout
+     consequence. Until then, both are named. */
+  --wp-radius-0: 0;
+  --wp-shadow-none: none;
+  --wp-shadow-lg-neutral: 0 4px 16px rgba(0, 0, 0, .16);
+  --wp-shadow-lg-cool: 0 4px 16px rgba(20, 30, 50, .12);
+
+  /* -- elevation -------------------------------------------------------------
+     Twelve distinct shadows, which is eleven more than a flat Carbon UI wants.
+     They are listed rather than merged for the same reason as the borders: each
+     one renders today and merging is a visual change. That the list is this long
+     is itself the finding — a later pass can collapse it to two or three now
+     that they are all visible in one place. */
+  --wp-shadow-pop: 0 8px 28px rgba(20, 30, 50, .22);
+  --wp-shadow-menu: 0 8px 24px rgba(20, 30, 50, .18);
+  --wp-shadow-menu-lg: 0 10px 26px rgba(20, 30, 50, .18);
+  --wp-shadow-modal: 0 12px 40px rgba(20, 30, 50, .3);
+  --wp-shadow-modal-lg: 0 20px 60px rgba(0, 0, 0, .3);
+  --wp-shadow-gate: 0 8px 30px rgba(20, 30, 50, .12);
+  --wp-shadow-rail: 6px 0 22px rgba(20, 30, 50, .16);
+  --wp-shadow-drawer: 2px 0 16px rgba(0, 0, 0, .4);
+  --wp-shadow-sticky: 0 -2px 10px rgba(20, 30, 50, .08);
+  --wp-shadow-navbar: 0 1px 4px rgba(20, 30, 50, .06);
+  --wp-shadow-tooltip: 0 4px 14px rgba(20, 30, 50, .22);
+  --wp-shadow-toast: 0 6px 24px rgba(0, 0, 0, .25);
+
+  /* -- scrims ----------------------------------------------------------------
+     Five overlay fills in three tints. --cds-overlay (rgba(22,22,22,.5)) is the
+     Carbon one; the drawer's is the same colour 5% darker for no recorded
+     reason, which makes it the cheapest merge in the set — but still a merge,
+     so still not here. See docs/reference/tokens.md section 8-F. */
+  --wp-scrim-drawer: rgba(22, 22, 22, .55);
+  --wp-scrim-cool: rgba(20, 30, 50, .28);
+  --wp-scrim-cool-modal: rgba(20, 30, 50, .5);
+  --wp-scrim-cool-strong: rgba(20, 28, 40, .55);
+  --wp-scrim-neutral: rgba(0, 0, 0, .5);
+  --wp-scrim-loading: rgba(244, 245, 247, .82);
+  --wp-scrim-frosted: rgba(255, 255, 255, .94);   /* sticky section-nav backdrop */
+  --wp-on-accent-divider: rgba(255, 255, 255, .28);
+
+  /* -- surfaces that are not Carbon greys ------------------------------------
+     Four neutrals the suite invented, all within a few points of a Carbon step
+     and none of them equal to one. --wp-table-zebra is the dangerous one: it is
+     six points from --cds-layer-accent, and collapsing them erases the striping
+     on the nine-column user table. Section 8-A. */
+  --wp-table-zebra: #fafafa;
+  --wp-table-row-hover: #eef0f2;
+  --wp-nav-bg: #fbfbfc;
+  --wp-nav-hover: #eef0f3;
+  --wp-nav-active: #e8eaed;
+  --wp-pop-divider: #f0f0f0;              /* popover hairlines in the shared chrome */
+  --wp-accent-soft-hover: #e2ecfc;        /* hover on an --cds-highlight fill */
+
+  /* -- the Project Super User tag --------------------------------------------
+     Carbon purple-10 / purple-60. Real Carbon values with no --cds-* slot in
+     the subset this sheet carries. One consumer; promote into --cds-* if a
+     second ever appears. */
+  --wp-tag-super-bg: #e8daff;
+  --wp-tag-super-text: #6929c4;
+
+  /* -- console output --------------------------------------------------------
+     pre.out is a terminal emulator, not product surface. Green-on-dark pass and
+     red-on-dark fail is the convention being quoted; it should not track the
+     palette and must not be "corrected" to Carbon's support colours. */
+  --wp-term-bg: #0f1525;
+  --wp-term-fg: #d7e0f5;
+  --wp-term-pass: #56d364;
+  --wp-term-fail: #ff7b72;
+
+  /* -- dev mode --------------------------------------------------------------
+     Deliberately outside the palette. The banner is MEANT to look wrong; giving
+     it the product's amber would make it look intentional, which defeats it. */
+  --wp-dev-bg: #3a2a00;
+  --wp-dev-fg: #ffd479;
+  --wp-dev-rule: #ffb000;
+
+  /* -- the second blue -------------------------------------------------------
+     #2563d6, not #0f62fe. Fills .sop-inherited — every field a work package
+     inherited from its SOP — at 7% alpha, which is why nobody has noticed a
+     second brand blue. Named here so it is visible; swapped at T3.5 (BL-008). */
+  --wp-sop-inherited-bg: rgba(37, 99, 214, .07);
 }
 
 /* Typography */
 body {
-  font-family: "IBM Plex Sans", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", sans-serif;
+  font-family: var(--wp-font-sans);
   color: var(--cds-text-primary);
   background: var(--cds-background);
   font-size: 1rem;
@@ -173,6 +343,10 @@ input, textarea, select {
   --wp-appbar-border: #6f6f6f;      /* outline for ghost buttons on the bar */
   --wp-appbar-hover: #353535;
   --wp-appbar-height: 48px;
+  /* Carbon gray-90 — one step up from the bar itself. The raised surfaces that
+     sit ON the dark bar or the drawer: the chrome's search field, the drawer's
+     current row. Its two consumers both hardcoded it before T3.2. */
+  --wp-appbar-layer: #262626;
 }
 
 .wp-appbar {
@@ -200,7 +374,7 @@ input, textarea, select {
   display: inline-flex;
   align-items: center;
   justify-content: center;
-  background: #fff;
+  background: var(--cds-ui-01);
   border-radius: 4px;
   padding: 4px 8px;
 }
diff --git a/html/work-package-suite-styles.css b/html/work-package-suite-styles.css
index f6a9718..bac0c4f 100644
--- a/html/work-package-suite-styles.css
+++ b/html/work-package-suite-styles.css
@@ -1,25 +1,32 @@
+/* Names only. Every value comes from theme-light.css, which this page loads
+   first — this sheet declares nothing of its own (T3.2 / S5 / C3). The names
+   stay because work-package-suite-app.js reads ten of them from JavaScript,
+   where a rename fails silently. See docs/reference/tokens.md section 9. */
 :root {
-  --primary: #0f62fe;
-  --primary-light: #edf5ff;
-  --success: #198038;
-  --warning: #8e6a00;
-  --warning-bg: #fdf6dd;
-  --danger: #da1e28;
-  --text: #161616;
-  --text-light: #525252;
-  --text-dim: #8d8d8d;
-  --border: #e0e0e0;
-  --border-strong: #8d8d8d;
-  --bg: #f4f4f4;
-  --bg-card: #ffffff;
-  --appbar: #161616;
-  --shadow: none;
-  --shadow-lg: 0 4px 16px rgba(0,0,0,0.16);
+  --primary: var(--cds-interactive-01);
+  --primary-light: var(--cds-highlight);
+  --success: var(--cds-support-success);
+  --warning: var(--wp-status-warning-text);
+  --warning-bg: var(--wp-status-warning-bg);
+  --danger: var(--cds-support-error);
+  --text: var(--cds-text-primary);
+  --text-light: var(--cds-text-secondary);
+  --text-dim: var(--cds-ui-04);
+  --border: var(--cds-border-subtle);
+  --border-strong: var(--cds-border-strong);
+  --bg: var(--cds-background);
+  --bg-card: var(--cds-layer);
+  --appbar: var(--wp-appbar-bg);
+  --shadow: var(--wp-shadow-none);
+  /* Neutral, where the creator's --shadow-lg is cool-tinted. Same geometry in
+     both — 0 4px 16px — so the two can be merged later without moving anything;
+     merging is still a rendered change, so not here. tokens.md section 8-F. */
+  --shadow-lg: var(--wp-shadow-lg-neutral);
 }
 
 * { margin: 0; padding: 0; box-sizing: border-box; }
 body {
-  font-family: 'IBM Plex Sans', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', sans-serif;
+  font-family: var(--wp-font-sans);
   color: var(--text);
   background: var(--bg);
   line-height: 1.5;
@@ -40,7 +47,7 @@ body {
    One row still measures exactly 48px, so nothing moves at desk width. */
 .header {
   background: var(--appbar);
-  color: #fff;
+  color: var(--wp-appbar-fg);
   padding: 0 16px;
   min-height: 48px;
   display: flex;
@@ -75,7 +82,7 @@ body {
   display: inline-flex;
   align-items: center;
   justify-content: center;
-  background: #fff;
+  background: var(--cds-ui-01);
   padding: 4px 8px;
   border-radius: 4px;
   text-decoration: none;
@@ -102,13 +109,13 @@ body {
   font-size: 15px;
   font-weight: 600;
   margin-bottom: 0;
-  color: #fff;
+  color: var(--wp-appbar-fg);
   white-space: nowrap;
 }
 
 .header-subtitle {
   font-size: 12px;
-  color: #c6c6c6;
+  color: var(--wp-appbar-fg-dim);
   min-height: 16px;
   white-space: nowrap;
   overflow: hidden;
@@ -130,8 +137,8 @@ body {
 .header-button {
   padding: 7px 14px;
   background: transparent;
-  color: #fff;
-  border: 1px solid #6f6f6f;
+  color: var(--wp-appbar-fg);
+  border: 1px solid var(--wp-appbar-border);
   border-radius: 0;
   cursor: pointer;
   font-size: 14px;
@@ -140,14 +147,14 @@ body {
 }
 
 .header-button:hover {
-  background: #353535;
-  border-color: #6f6f6f;
+  background: var(--wp-appbar-hover);
+  border-color: var(--wp-appbar-border);
 }
 
 .step-counter {
   background: transparent;
-  border: 1px solid #6f6f6f;
-  color: #c6c6c6;
+  border: 1px solid var(--wp-appbar-border);
+  color: var(--wp-appbar-fg-dim);
   padding: 4px 10px;
   border-radius: 20px;
   font-size: 12px;
@@ -276,7 +283,7 @@ body.embed-full { overflow: hidden; }
 }
 
 .step-item:hover { background: var(--bg); border-color: var(--border-strong); color: var(--text); }
-.step-item.active { background: var(--primary); color: white; border-color: var(--primary); font-weight: 600; }
+.step-item.active { background: var(--primary); color: var(--cds-text-on-color); border-color: var(--primary); font-weight: 600; }
 
 /* STEP CONTENT */
 .step-content {
@@ -464,7 +471,7 @@ body.embed-full { overflow: hidden; }
 .add-btn {
   padding: 0.7rem 1.25rem;
   background: var(--primary);
-  color: white;
+  color: var(--cds-text-on-color);
   border: none;
   border-radius: 0;
   font-size: 14px;
@@ -473,7 +480,7 @@ body.embed-full { overflow: hidden; }
   transition: background 0.2s;
 }
 
-.add-btn:hover { background: var(--cds-hover-primary, #0353e9); }
+.add-btn:hover { background: var(--cds-hover-primary); }
 
 .nav-btn {
   padding: 0.7rem 1.4rem;
@@ -491,11 +498,11 @@ body.embed-full { overflow: hidden; }
 
 .nav-btn.primary {
   background: var(--success);
-  color: white;
+  color: var(--cds-text-on-color);
   border-color: var(--success);
 }
 
-.nav-btn.primary:hover { background: #0e6027; border-color: #0e6027; color: white; }
+.nav-btn.primary:hover { background: var(--wp-hover-success); border-color: var(--wp-hover-success); color: var(--cds-text-on-color); }
 
 .nav-btn:disabled { opacity: 0.5; cursor: not-allowed; }
 
@@ -529,7 +536,7 @@ body.embed-full { overflow: hidden; }
   transition: all 0.2s;
 }
 
-.comments-toggle:hover { background: var(--primary); color: white; }
+.comments-toggle:hover { background: var(--primary); color: var(--cds-text-on-color); }
 
 /* CONSTRUCTION SEQUENCE (drag & drop) */
 #sequence-list { display: flex; flex-direction: column; gap: 8px; }
@@ -552,14 +559,14 @@ body.embed-full { overflow: hidden; }
 }
 .seq-step input.seq-label:focus { background: var(--bg); border-color: var(--primary); outline: none; }
 .seq-del {
-  background: var(--danger); color: white; border: none; border-radius: 4px;
+  background: var(--danger); color: var(--cds-text-on-color); border: none; border-radius: 4px;
   width: 28px; height: 28px; cursor: pointer; font-weight: 600; flex-shrink: 0;
 }
 .seq-arrow { text-align: center; color: var(--text-dim); font-size: 13px; line-height: .4; margin: -2px 0; }
 .seq-step.gate { border-color: var(--warning); background: var(--warning-bg); border-style: dashed; }
 .seq-step.gate .seq-label { color: var(--warning); font-weight: 500; }
 .seq-gate-badge {
-  flex-shrink: 0; padding: 3px 9px; border-radius: 20px; background: var(--warning); color: #fff;
+  flex-shrink: 0; padding: 3px 9px; border-radius: 20px; background: var(--warning); color: var(--cds-text-on-color);
   font-size: 9px; font-weight: 600; letter-spacing: .08em; white-space: nowrap;
 }
 
@@ -603,7 +610,7 @@ body.embed-full { overflow: hidden; }
   left: 0;
   right: 0;
   bottom: 0;
-  background: rgba(0,0,0,0.5);
+  background: var(--wp-scrim-neutral);
   display: flex;
   align-items: center;
   justify-content: center;
diff --git a/html/work-package-suite.html b/html/work-package-suite.html
index 3b9ccdb..f53ad98 100644
--- a/html/work-package-suite.html
+++ b/html/work-package-suite.html
@@ -404,7 +404,7 @@
       <textarea id="comment-text" rows="3" placeholder="Your feedback here..." style="width: 100%; padding: 0.5rem; border: 1px solid var(--border); border-radius: 4px; margin-top: 0.25rem; font-family: inherit;"></textarea>
     </div>
     <div style="display:flex; gap:0.5rem; flex-wrap:wrap;">
-      <button onclick="submitComment()" style="background: var(--primary); color: white; padding: 0.5rem 1rem; border: none; border-radius: 4px; cursor: pointer; font-weight: 600;">Submit</button>
+      <button onclick="submitComment()" style="background: var(--primary); color: var(--cds-text-on-color); padding: 0.5rem 1rem; border: none; border-radius: 4px; cursor: pointer; font-weight: 600;">Submit</button>
       <button onclick="exportComments()" style="background: var(--bg); color: var(--text); border: 1px solid var(--border); padding: 0.5rem 1rem; border-radius: 4px; cursor: pointer; font-weight: 600;">Export</button>
       <button onclick="document.getElementById('sop-comments-import').click()" style="background: var(--bg); color: var(--text); border: 1px solid var(--border); padding: 0.5rem 1rem; border-radius: 4px; cursor: pointer; font-weight: 600;">Import</button>
       <input type="file" id="sop-comments-import" accept="application/json" style="display:none" onchange="importComments(event)">
diff --git a/html/wp-chrome.css b/html/wp-chrome.css
index 027a559..433c83c 100644
--- a/html/wp-chrome.css
+++ b/html/wp-chrome.css
@@ -14,25 +14,28 @@
   min-width: 0;             /* lets the search shrink instead of overflowing */
   flex: 1 1 auto;
 }
+/* Seven role names, resolved twice — once for each kind of host bar. The switch
+   is the point of this block and it stays; only the literals move behind the
+   canonical tokens in theme-light.css (T3.2 / S5 / C3). */
 /* Light host bar (the two tool pages) */
 .wp-chrome {
-  --wpc-fg: #161616;
-  --wpc-fg-dim: #525252;
-  --wpc-bg: #ffffff;
-  --wpc-bg-soft: #f4f4f4;
-  --wpc-border: #c6c6c6;
-  --wpc-hover: #e8e8e8;
-  --wpc-accent: #0f62fe;
+  --wpc-fg: var(--cds-text-primary);
+  --wpc-fg-dim: var(--cds-text-secondary);
+  --wpc-bg: var(--cds-layer);
+  --wpc-bg-soft: var(--cds-layer-accent);
+  --wpc-border: var(--cds-border-subtle-selected);
+  --wpc-hover: var(--cds-layer-hover);
+  --wpc-accent: var(--cds-interactive-01);
 }
 /* Dark host bar (the UI-shell appbar) */
 .wp-chrome[data-bar="dark"] {
-  --wpc-fg: #ffffff;
-  --wpc-fg-dim: #c6c6c6;
-  --wpc-bg: #262626;
-  --wpc-bg-soft: #393939;
-  --wpc-border: #6f6f6f;
-  --wpc-hover: #353535;
-  --wpc-accent: #78a9ff;
+  --wpc-fg: var(--wp-appbar-fg);
+  --wpc-fg-dim: var(--wp-appbar-fg-dim);
+  --wpc-bg: var(--wp-appbar-layer);
+  --wpc-bg-soft: var(--cds-inverse-02);
+  --wpc-border: var(--wp-appbar-border);
+  --wpc-hover: var(--wp-appbar-hover);
+  --wpc-accent: var(--cds-link-inverse);
 }
 
 /* ── archived-project banner ──────────────────────────────────────────────── */
@@ -47,11 +50,11 @@
   align-items: flex-start;
   gap: 8px;
   padding: 9px 16px;
-  background: #fdf6dd;
-  color: #8e6a00;
-  border-bottom: 1px solid #f1c21b;
+  background: var(--wp-status-warning-bg);
+  color: var(--wp-status-warning-text);
+  border-bottom: 1px solid var(--cds-support-warning);
   border-radius: 0;
-  font-family: 'IBM Plex Sans', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+  font-family: var(--wp-font-sans-2);
   font-size: 13.5px;
   line-height: 1.35;
 }
@@ -122,10 +125,10 @@
   max-width: min(460px, 92vw);
   max-height: min(70vh, 560px);
   overflow-y: auto;
-  background: #fff;
-  color: #161616;
-  border: 1px solid #e0e0e0;
-  box-shadow: 0 8px 28px rgba(20, 30, 50, .22);
+  background: var(--cds-layer);
+  color: var(--cds-text-primary);
+  border: 1px solid var(--cds-border-subtle);
+  box-shadow: var(--wp-shadow-pop);
   border-radius: 4px;
 }
 .wpc-pop[hidden] { display: none; }
@@ -135,8 +138,8 @@
   font-weight: 700;
   letter-spacing: .07em;
   text-transform: uppercase;
-  color: #6f6f6f;
-  border-bottom: 1px solid #f0f0f0;
+  color: var(--cds-text-helper);
+  border-bottom: 1px solid var(--wp-pop-divider);
 }
 .wpc-item {
   display: block;
@@ -148,19 +151,19 @@
   text-align: left;
   font: inherit;
   font-size: 13px;
-  color: #161616;
+  color: var(--cds-text-primary);
   cursor: pointer;
   text-decoration: none;
 }
-.wpc-item:hover, .wpc-item.is-active { background: #f4f4f4; }
-.wpc-item.is-current { border-left-color: #0f62fe; background: #edf5ff; }
+.wpc-item:hover, .wpc-item.is-active { background: var(--cds-layer-accent); }
+.wpc-item.is-current { border-left-color: var(--cds-interactive-01); background: var(--cds-highlight); }
 .wpc-item-title { display: block; font-weight: 600; }
-.wpc-item-sub { display: block; font-size: 11.5px; color: #6f6f6f; }
-.wpc-item-mono { font-family: 'IBM Plex Mono', ui-monospace, Consolas, monospace; font-size: 12px; color: #0f62fe; }
-.wpc-empty { padding: 14px 12px; font-size: 13px; color: #6f6f6f; }
+.wpc-item-sub { display: block; font-size: 11.5px; color: var(--cds-text-helper); }
+.wpc-item-mono { font-family: var(--wp-font-mono-3); font-size: 12px; color: var(--cds-interactive-01); }
+.wpc-empty { padding: 14px 12px; font-size: 13px; color: var(--cds-text-helper); }
 .wpc-pop-foot {
   padding: 8px 12px;
-  border-top: 1px solid #f0f0f0;
+  border-top: 1px solid var(--wp-pop-divider);
   display: flex;
   gap: 8px;
   flex-wrap: wrap;
@@ -170,14 +173,14 @@
   font-size: 12px;
   font-weight: 600;
   padding: 5px 10px;
-  border: 1px solid #c6c6c6;
-  background: #fff;
-  color: #161616;
+  border: 1px solid var(--cds-border-subtle-selected);
+  background: var(--cds-layer);
+  color: var(--cds-text-primary);
   border-radius: 3px;
   cursor: pointer;
   text-decoration: none;
 }
-.wpc-foot-btn:hover { border-color: #0f62fe; color: #0f62fe; }
+.wpc-foot-btn:hover { border-color: var(--cds-interactive-01); color: var(--cds-interactive-01); }
 
 /* ── global search ────────────────────────────────────────────────────────── */
 /* Centered in the bar: the wrapper takes the free space and centres a capped box,
@@ -218,7 +221,7 @@
 .wpc-search-input::placeholder { color: var(--wpc-fg-dim); }
 .wpc-kbd {
   flex: 0 0 auto;
-  font-family: 'IBM Plex Mono', ui-monospace, Consolas, monospace;
+  font-family: var(--wp-font-mono-3);
   font-size: 10.5px;
   color: var(--wpc-fg-dim);
   border: 1px solid var(--wpc-border);
diff --git a/html/wp-creation-styles.css b/html/wp-creation-styles.css
index a53bb0d..7c0a308 100644
--- a/html/wp-creation-styles.css
+++ b/html/wp-creation-styles.css
@@ -6,28 +6,35 @@
   body.embedded .embed-hide { display: none !important; }
   body.embedded .embed-first { margin-left: auto; }
 
+  /* Names only. Every value comes from theme-light.css, which this page loads
+     first - this sheet declares nothing of its own (T3.2 / S5 / C3). The names
+     stay because wp-creation-app.js reads eight of them from JavaScript, where
+     a rename fails silently. See docs/reference/tokens.md section 9. */
   :root {
-    --bg: #f4f4f4;
-    --surface: #ffffff;
-    --surface2: #f4f4f4;
-    --border: #e0e0e0;
-    --border-strong: #8d8d8d;
-    --text: #161616;
-    --text-muted: #525252;
-    --text-dim: #8d8d8d;
-    --accent: #0f62fe;
-    --accent-dim: #edf5ff;
-    --accent-green: #198038;
-    --accent-green-dim: #defbe6;
-    --accent-amber: #8e6a00;
-    --accent-amber-dim: #fdf6dd;
-    --red: #da1e28;
-    --red-dim: #fff1f1;
-    --radius: 0;
-    --shadow: none;
-    --shadow-lg: 0 4px 16px rgba(20,30,50,.12);
-    --mono: 'IBM Plex Mono', ui-monospace, 'Cascadia Mono', 'Segoe UI Mono', Consolas, monospace;
-    --sans: 'IBM Plex Sans', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', sans-serif;
+    --bg: var(--cds-background);
+    --surface: var(--cds-layer);
+    --surface2: var(--cds-layer-accent);
+    --border: var(--cds-border-subtle);
+    --border-strong: var(--cds-border-strong);
+    --text: var(--cds-text-primary);
+    --text-muted: var(--cds-text-secondary);
+    --text-dim: var(--cds-ui-04);
+    --accent: var(--cds-interactive-01);
+    --accent-dim: var(--cds-highlight);
+    --accent-green: var(--cds-support-success);
+    --accent-green-dim: var(--wp-status-success-bg);
+    --accent-amber: var(--wp-status-warning-text);
+    --accent-amber-dim: var(--wp-status-warning-bg);
+    --red: var(--cds-support-error);
+    --red-dim: var(--wp-status-error-bg);
+    --radius: var(--wp-radius-0);
+    --shadow: var(--wp-shadow-none);
+    /* Cool-tinted, where the wizard's --shadow-lg is neutral. Same geometry in
+       both - 0 4px 16px - so the two can be merged later without moving
+       anything; merging is still a rendered change. tokens.md section 8-F. */
+    --shadow-lg: var(--wp-shadow-lg-cool);
+    --mono: var(--wp-font-mono);
+    --sans: var(--wp-font-sans);
   }
 
   * { box-sizing: border-box; margin: 0; padding: 0; }
@@ -227,8 +234,8 @@
   .sub-heading::after { content: ''; flex: 1; height: 1px; background: var(--border); }
 
   .notice {
-    background: var(--accent-dim); border: 1px solid #b9d2fb; border-radius: var(--radius);
-    padding: 10px 14px; font-size: 12px; color: #0043ce; margin-bottom: 18px; font-family: var(--mono);
+    background: var(--accent-dim); border: 1px solid var(--wp-accent-border-a); border-radius: var(--radius);
+    padding: 10px 14px; font-size: 12px; color: var(--cds-link-secondary); margin-bottom: 18px; font-family: var(--mono);
   }
 
   /* ── DELIVERABLES ── */
@@ -245,7 +252,7 @@
   .deliv-box {
     width: 16px; height: 16px; border: 1.5px solid var(--border-strong); border-radius: 3px;
     flex-shrink: 0; margin-top: 2px; display: flex; align-items: center; justify-content: center;
-    font-size: 11px; color: #fff; transition: all .12s;
+    font-size: 11px; color: var(--cds-text-on-color); transition: all .12s;
   }
   .deliv-item.checked .deliv-box { background: var(--accent); border-color: var(--accent); }
   .deliv-text { font-size: 12.5px; line-height: 1.35; color: var(--text); }
@@ -259,10 +266,10 @@
   }
   .btn-ghost { background: var(--surface); border-color: var(--border-strong); color: var(--text-muted); }
   .btn-ghost:hover { border-color: var(--accent); color: var(--accent); }
-  .btn-primary { background: var(--accent); border-color: var(--accent); color: #fff; box-shadow: var(--shadow); }
-  .btn-primary:hover { background: #0353e9; }
-  .btn-generate { background: var(--accent-green); border-color: var(--accent-green); color: #fff; font-weight: 700; box-shadow: var(--shadow); }
-  .btn-generate:hover { background: #0e6027; }
+  .btn-primary { background: var(--accent); border-color: var(--accent); color: var(--cds-text-on-color); box-shadow: var(--shadow); }
+  .btn-primary:hover { background: var(--cds-hover-primary); }
+  .btn-generate { background: var(--accent-green); border-color: var(--accent-green); color: var(--cds-text-on-color); font-weight: 700; box-shadow: var(--shadow); }
+  .btn-generate:hover { background: var(--wp-hover-success); }
 
   /* ── OUTPUT ── */
   #output-section { display: none; }
@@ -299,7 +306,7 @@
 
   /* ── LOADING ── */
   .loading-overlay {
-    display: none; position: fixed; inset: 0; background: rgba(244,245,247,.82); z-index: 200;
+    display: none; position: fixed; inset: 0; background: var(--wp-scrim-loading); z-index: 200;
     align-items: center; justify-content: center; flex-direction: column; gap: 16px; backdrop-filter: blur(2px);
   }
   .loading-overlay.active { display: flex; }
@@ -369,7 +376,7 @@
   .seq-step.gate { border-color: var(--accent-amber); background: var(--accent-amber-dim); border-style: dashed; }
   .seq-step.gate .seq-label { color: var(--accent-amber); font-weight: 500; }
   .seq-gate-badge {
-    flex-shrink: 0; padding: 3px 9px; border-radius: 20px; background: var(--accent-amber); color: #fff;
+    flex-shrink: 0; padding: 3px 9px; border-radius: 20px; background: var(--accent-amber); color: var(--cds-text-on-color);
     font-family: var(--mono); font-size: 9px; font-weight: 600; letter-spacing: .08em; white-space: nowrap;
   }
   .add-btn-gate { border-color: var(--accent-amber); color: var(--accent-amber); }
@@ -382,13 +389,13 @@
 
   /* ── REVIEW COMMENTS ─────────────────────────────────────────────── */
   .cbadge-total { display:inline-block; min-width:16px; padding:0 5px; margin-left:4px; font-family:var(--mono);
-    font-size:10px; font-weight:700; line-height:16px; text-align:center; color:#fff; background:var(--accent); border-radius:9px; }
+    font-size:10px; font-weight:700; line-height:16px; text-align:center; color:var(--cds-text-on-color); background:var(--accent); border-radius:9px; }
   .step-tab { position:relative; }
   .step-tab .cbadge { position:absolute; top:4px; right:4px; min-width:15px; height:15px; padding:0 4px;
     font-family:var(--mono); font-size:9px; font-weight:700; line-height:15px; text-align:center;
-    color:#fff; background:var(--accent-amber); border-radius:8px; box-shadow:0 0 0 2px var(--surface); }
+    color:var(--cds-text-on-color); background:var(--accent-amber); border-radius:8px; box-shadow:0 0 0 2px var(--surface); }
 
-  .cmt-overlay { position:fixed; inset:0; background:rgba(20,30,50,.28); opacity:0; pointer-events:none;
+  .cmt-overlay { position:fixed; inset:0; background:var(--wp-scrim-cool); opacity:0; pointer-events:none;
     transition:opacity .2s ease; z-index:60; }
   .cmt-overlay.open { opacity:1; pointer-events:auto; }
   /* Starts below the header, not behind it. The containing block was already the
@@ -443,12 +450,12 @@
   .radio-group.group-invalid, .check-group.group-invalid { outline:2px solid var(--red); outline-offset:4px; border-radius:var(--radius); }
   .ov-select.ov-unset { color:var(--red) !important; border-color:var(--red); }
   .use-btn { display:inline-block; margin-left:8px; padding:4px 14px; font-family:var(--sans); font-size:11px; font-weight:700;
-    color:#fff; background:var(--accent-green); border:none; border-radius:var(--radius); cursor:pointer; letter-spacing:.03em; }
-  .use-btn:hover { background:#0e6027; }
+    color:var(--cds-text-on-color); background:var(--accent-green); border:none; border-radius:var(--radius); cursor:pointer; letter-spacing:.03em; }
+  .use-btn:hover { background:var(--wp-hover-success); }
   .sum-chips { display:flex; flex-wrap:wrap; gap:7px; }
-  .sum-chip { background:var(--accent-dim); color:var(--accent); border:1px solid #b9d2fb; border-radius:3px;
+  .sum-chip { background:var(--accent-dim); color:var(--accent); border:1px solid var(--wp-accent-border-a); border-radius:3px;
     padding:3px 10px; font-family:var(--mono); font-size:10px; }
-  .sum-warn { margin-top:10px; color:var(--accent-amber); background:var(--accent-amber-dim); border:1px solid #f0d9ad;
+  .sum-warn { margin-top:10px; color:var(--accent-amber); background:var(--accent-amber-dim); border:1px solid var(--wp-status-warning-border-b);
     border-radius:var(--radius); padding:7px 10px; font-size:11px; }
 
   /* ── CREATION TOOL ───────────────────────────────────────────────── */
@@ -458,7 +465,7 @@
   .ctx-main .ctx-proj { font-weight:700; color:var(--text); font-size:14px; }
   .ctx-main .ctx-sub { font-size:11px; color:var(--text-muted); margin-top:2px; }
   .ctx-sample { font-family:var(--mono); font-size:9px; font-weight:700; color:var(--accent-amber);
-    background:var(--accent-amber-dim); border:1px solid #f0d9ad; border-radius:9px; padding:1px 7px; margin-left:6px; vertical-align:middle; }
+    background:var(--accent-amber-dim); border:1px solid var(--wp-status-warning-border-b); border-radius:9px; padding:1px 7px; margin-left:6px; vertical-align:middle; }
   .ctx-meta { margin-left:auto; display:flex; gap:16px; font-size:11px; color:var(--text-muted); flex-wrap:wrap; }
   .ctx-meta b { color:var(--accent); }
   .ctx-meta code { background:var(--surface2); padding:1px 6px; border-radius:3px; color:var(--accent); }
@@ -468,7 +475,7 @@
   .mode-toggle { display:inline-flex; border:1px solid var(--border-strong); border-radius:6px; overflow:hidden; }
   .mode-btn { padding:8px 18px; font-family:var(--sans); font-size:13px; font-weight:600; border:none; background:var(--surface);
     color:var(--text-muted); cursor:pointer; }
-  .mode-btn.active { background:var(--accent); color:#fff; }
+  .mode-btn.active { background:var(--accent); color:var(--cds-text-on-color); }
   .created-count { font-size:11px; color:var(--text-muted); }
 
   .wo-section { border:1px solid var(--border); border-radius:var(--radius); padding:11px 13px; margin-bottom:9px; background:var(--surface); }
@@ -491,19 +498,19 @@
   .release-banner { max-width:none; margin:0; padding:0 28px 0 calc(var(--nav-w,288px) + 28px); }
   .release-banner .rb-inner { margin-top:14px; border-radius:var(--radius); padding:11px 16px; font-size:13px; font-weight:600;
     display:flex; align-items:center; gap:10px; }
-  .rb-ready { background:var(--accent-green-dim); color:var(--accent-green); border:1px solid #b6e3c6; }
-  .rb-notready { background:var(--accent-amber-dim); color:var(--accent-amber); border:1px solid #f0d9ad; }
-  .rb-hold { background:var(--red-dim); color:var(--red); border:1px solid #f3c4c4; }
+  .rb-ready { background:var(--accent-green-dim); color:var(--accent-green); border:1px solid var(--wp-status-success-border-b); }
+  .rb-notready { background:var(--accent-amber-dim); color:var(--accent-amber); border:1px solid var(--wp-status-warning-border-b); }
+  .rb-hold { background:var(--red-dim); color:var(--red); border:1px solid var(--wp-status-error-border-b); }
   .pill-hold.selected { background:var(--red) !important; border-color:var(--red) !important; }
-  .pill-hold.selected .dot { background:#fff !important; }
+  .pill-hold.selected .dot { background:var(--cds-text-on-color) !important; }
 
   .cstatus { display:inline-flex; border:1px solid var(--border-strong); border-radius:5px; overflow:hidden; }
   .cstatus button { border:none; background:var(--surface); color:var(--text-muted); font-family:var(--sans); font-size:11px;
     font-weight:600; padding:4px 10px; cursor:pointer; border-right:1px solid var(--border); }
   .cstatus button:last-child { border-right:none; }
-  .cstatus button.on-open { background:var(--red); color:#fff; }
-  .cstatus button.on-cleared { background:var(--accent-green); color:#fff; }
-  .cstatus button.on-na { background:var(--text-muted); color:#fff; }
+  .cstatus button.on-open { background:var(--red); color:var(--cds-text-on-color); }
+  .cstatus button.on-cleared { background:var(--accent-green); color:var(--cds-text-on-color); }
+  .cstatus button.on-na { background:var(--text-muted); color:var(--cds-text-on-color); }
   #material-body input, #attach-body input, #constraint-body input, #signoff-body input { width:100%; }
   .signoff-check { width:18px; height:18px; cursor:pointer; }
 
@@ -512,15 +519,15 @@
   .lock-row { display:flex; align-items:center; gap:10px; margin-top:5px; }
   .lock-edit { background:none; border:none; color:var(--accent); cursor:pointer; font-size:11px; padding:0; }
   .override-note { font-size:11px; color:var(--accent-amber); }
-  .sop-tag { font-size:9px; font-weight:700; color:var(--accent); background:var(--accent-dim,#eaf0fd); border:1px solid #cdd9f2; border-radius:9px; padding:1px 6px; margin-left:6px; vertical-align:middle; }
+  .sop-tag { font-size:9px; font-weight:700; color:var(--accent); background:var(--accent-dim); border:1px solid var(--wp-accent-border-b); border-radius:9px; padding:1px 6px; margin-left:6px; vertical-align:middle; }
 
-  #toast { position:fixed; bottom:26px; left:50%; transform:translateX(-50%) translateY(20px); background:var(--text); color:#fff;
-    padding:10px 20px; border-radius:8px; font-size:13px; font-weight:600; opacity:0; pointer-events:none; transition:all .25s; z-index:9999; box-shadow:0 6px 24px rgba(0,0,0,.25); }
+  #toast { position:fixed; bottom:26px; left:50%; transform:translateX(-50%) translateY(20px); background:var(--text); color:var(--cds-text-on-color);
+    padding:10px 20px; border-radius:8px; font-size:13px; font-weight:600; opacity:0; pointer-events:none; transition:all .25s; z-index:9999; box-shadow:var(--wp-shadow-toast); }
   #toast.show { opacity:1; transform:translateX(-50%) translateY(0); }
 
-  .modal-overlay { position:fixed; inset:0; background:rgba(20,28,40,.55); display:none; align-items:center; justify-content:center; z-index:9000; padding:20px; }
+  .modal-overlay { position:fixed; inset:0; background:var(--wp-scrim-cool-strong); display:none; align-items:center; justify-content:center; z-index:9000; padding:20px; }
   .modal-overlay.open { display:flex; }
-  .modal { background:var(--surface); border-radius:0; width:100%; max-width:520px; box-shadow:0 20px 60px rgba(0,0,0,.3); overflow:hidden; max-height:90vh; display:flex; flex-direction:column; }
+  .modal { background:var(--surface); border-radius:0; width:100%; max-width:520px; box-shadow:var(--wp-shadow-modal-lg); overflow:hidden; max-height:90vh; display:flex; flex-direction:column; }
   .modal-head { display:flex; align-items:center; justify-content:space-between; padding:16px 20px; border-bottom:1px solid var(--border); }
   .modal-title { font-weight:700; font-size:15px; color:var(--text); }
   .modal-body { padding:18px 20px; overflow-y:auto; }
@@ -529,11 +536,11 @@
   .hold-photo-preview img { max-width:160px; max-height:120px; border-radius:6px; border:1px solid var(--border); margin-top:8px; display:block; }
 
   /* ── REV 2 ADDITIONS ─────────────────────────────────────────────── */
-  .auto-tag { font-size:9px; font-weight:700; color:var(--accent-green); background:var(--accent-green-dim); border:1px solid #b6e3c6; border-radius:9px; padding:1px 6px; margin-left:6px; vertical-align:middle; }
+  .auto-tag { font-size:9px; font-weight:700; color:var(--accent-green); background:var(--accent-green-dim); border:1px solid var(--wp-status-success-border-b); border-radius:9px; padding:1px 6px; margin-left:6px; vertical-align:middle; }
   .derived-box { padding:9px 11px; border:1px dashed var(--border-strong); border-radius:var(--radius); background:var(--surface2); color:var(--text); font-size:13px; font-weight:600; min-height:38px; display:flex; align-items:center; }
   .material-actions { display:flex; gap:10px; flex-wrap:wrap; margin-top:8px; }
   .workstep-row { display:flex; align-items:flex-start; gap:10px; margin-bottom:8px; }
-  .workstep-row .ws-num { flex:0 0 26px; height:26px; border-radius:50%; background:var(--accent); color:#fff; font-size:12px; font-weight:700; display:flex; align-items:center; justify-content:center; margin-top:5px; }
+  .workstep-row .ws-num { flex:0 0 26px; height:26px; border-radius:50%; background:var(--accent); color:var(--cds-text-on-color); font-size:12px; font-weight:700; display:flex; align-items:center; justify-content:center; margin-top:5px; }
   .workstep-row textarea { flex:1; padding:8px 10px; border:1px solid var(--border-strong); border-radius:var(--radius); font-family:var(--sans); font-size:13px; resize:vertical; min-height:38px; }
   .workstep-row .row-del { flex:0 0 auto; margin-top:6px; }
 
@@ -562,7 +569,7 @@
 
   /* ── REV 3 ADDITIONS ─────────────────────────────────────────────── */
   /* SOP-inherited field highlight (comment 8) */
-  .sop-inherited { background:rgba(37,99,214,0.07) !important; border-color:var(--accent) !important; opacity:0.85; color:var(--text); }
+  .sop-inherited { background:var(--wp-sop-inherited-bg) !important; border-color:var(--accent) !important; opacity:0.85; color:var(--text); }
   .sop-inherited:focus { opacity:1; }
 
   /* Dev mode (comment 7) */
@@ -570,16 +577,16 @@
   .dev-toggle { position:absolute; left:2px; bottom:-9px; width:18px; height:7px; padding:0; border:none;
     background:var(--text-dim); opacity:0.10; border-radius:3px; cursor:pointer; }
   .dev-toggle:hover { opacity:0.35; }
-  .dev-banner { background:#3a2a00; color:#ffd479; font-size:12.5px; font-weight:700; text-align:center; padding:7px 14px; letter-spacing:.3px; }
-  body.dev-mode .header { box-shadow: inset 0 -3px 0 #ffb000; }
+  .dev-banner { background:var(--wp-dev-bg); color:var(--wp-dev-fg); font-size:12.5px; font-weight:700; text-align:center; padding:7px 14px; letter-spacing:.3px; }
+  body.dev-mode .header { box-shadow: inset 0 -3px 0 var(--wp-dev-rule); }
 
   /* SOP reference links (comments 1,3,4) */
   .sop-ref-links { margin-bottom:12px; }
   .ref-links-title { font-size:12px; color:var(--text-muted); margin-bottom:6px; }
   .ref-links { display:flex; flex-wrap:wrap; gap:8px; }
   .ref-link { display:inline-flex; align-items:center; gap:6px; font-size:12.5px; font-weight:600; color:var(--accent);
-    background:var(--accent-dim,#eef3fd); border:1px solid #cdd9f2; border-radius:8px; padding:6px 11px; text-decoration:none; }
-  .ref-link:hover { background:#e2ecfc; }
+    background:var(--accent-dim); border:1px solid var(--wp-accent-border-b); border-radius:8px; padding:6px 11px; text-decoration:none; }
+  .ref-link:hover { background:var(--wp-accent-soft-hover); }
   .ref-link .ref-sys { font-weight:400; color:var(--text-muted); font-size:11px; }
   .ref-link-sm { font-size:12px; font-weight:600; color:var(--accent); text-decoration:none; }
   .ref-link-sm:hover { text-decoration:underline; }
@@ -595,8 +602,8 @@
 
   /* Section nav (jump chips) */
   .section-nav-bar{ position:sticky; top:0; z-index:30; display:flex; flex-wrap:wrap; gap:6px;
-    padding:8px 12px 8px calc(var(--nav-w,288px) + 28px); background:rgba(255,255,255,.94); backdrop-filter:blur(4px);
-    border-bottom:1px solid var(--border); box-shadow:0 1px 4px rgba(20,30,50,.06);
+    padding:8px 12px 8px calc(var(--nav-w,288px) + 28px); background:var(--wp-scrim-frosted); backdrop-filter:blur(4px);
+    border-bottom:1px solid var(--border); box-shadow:var(--wp-shadow-navbar);
     transition:transform .22s ease; }
   .section-nav-bar:empty{ display:none; }
   .section-nav-bar.nav-hidden{ transform:translateY(-160%); }
@@ -611,16 +618,16 @@
      hover, and "this value came from the SOP" is the part people need to see. */
   .field-hint.sop-hint { display: none; }
   .sop-chip { display:inline-block; margin-left:6px; padding:0 6px; border-radius:9px;
-    background:var(--accent-dim); color:var(--accent); border:1px solid #b9d2fb;
+    background:var(--accent-dim); color:var(--accent); border:1px solid var(--wp-accent-border-a);
     font-size:9.5px; font-weight:700; letter-spacing:.04em; text-transform:uppercase;
     vertical-align:middle; cursor:help; position:relative; }
   .sop-chip::after { content:attr(data-tip); position:absolute; bottom:135%; left:50%;
-    transform:translateX(-50%); background:#161616; color:#fff; padding:7px 10px; font-size:12px;
+    transform:translateX(-50%); background:var(--cds-ui-05); color:var(--cds-text-on-color); padding:7px 10px; font-size:12px;
     font-weight:400; letter-spacing:0; text-transform:none; line-height:1.4; white-space:normal;
     width:max-content; max-width:260px; text-align:left; z-index:9999; opacity:0;
-    pointer-events:none; transition:opacity .12s; box-shadow:0 4px 14px rgba(20,30,50,.22); }
+    pointer-events:none; transition:opacity .12s; box-shadow:var(--wp-shadow-tooltip); }
   .sop-chip::before { content:''; position:absolute; bottom:135%; left:50%;
-    transform:translate(-50%,95%); border:5px solid transparent; border-top-color:#161616;
+    transform:translate(-50%,95%); border:5px solid transparent; border-top-color:var(--cds-ui-05);
     opacity:0; transition:opacity .12s; z-index:9999; }
   .sop-chip:hover::after, .sop-chip:hover::before,
   .sop-chip:focus::after, .sop-chip:focus::before { opacity:1; }
@@ -633,7 +640,7 @@
   .pp-chip { display:inline-flex; align-items:center; gap:5px; padding:2px 6px 2px 8px;
     background:var(--surface2); border:1px solid var(--border); border-radius:12px;
     font-size:12px; max-width:100%; }
-  .pp-chip.pp-locked { background:var(--accent-dim); border-color:#b9d2fb; color:var(--accent); }
+  .pp-chip.pp-locked { background:var(--accent-dim); border-color:var(--wp-accent-border-a); color:var(--accent); }
   .pp-chip .pp-name { overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
   .pp-chip .pp-x { background:none; border:0; cursor:pointer; color:var(--text-muted);
     font-size:12px; line-height:1; padding:0 1px; }
@@ -644,7 +651,7 @@
   .pp-add-btn:hover { border-color:var(--accent); color:var(--accent); }
   .pp-menu { position:absolute; top:calc(100% + 4px); left:0; z-index:60; min-width:270px;
     max-height:300px; overflow-y:auto; background:var(--surface); border:1px solid var(--border-strong);
-    box-shadow:0 8px 24px rgba(20,30,50,.18); border-radius:4px; padding:6px 0; }
+    box-shadow:var(--wp-shadow-menu); border-radius:4px; padding:6px 0; }
   .pp-menu[hidden] { display:none; }
   .pp-group { font-size:9.5px; font-weight:700; letter-spacing:.07em; text-transform:uppercase;
     color:var(--text-dim); padding:7px 10px 3px; }
@@ -660,7 +667,7 @@
   /* Critical constraint marker (from the SOP) */
   .crit-tag { display:inline-block; margin-left:6px; padding:1px 7px; border-radius:10px; font-size:10px;
     font-weight:700; letter-spacing:.02em; color:var(--red); background:var(--red-dim);
-    border:1px solid #ffc4c4; white-space:nowrap; vertical-align:middle; }
+    border:1px solid var(--wp-status-error-border-c); white-space:nowrap; vertical-align:middle; }
 
   /* -- WORK PACKAGE NAVIGATOR ------------------------------------------------
      A persistent side panel in the spirit of MS Planner: collapse toggle, one
@@ -677,7 +684,7 @@
     z-index: 120;
     display: flex;
     flex-direction: column;
-    background: #fbfbfc;
+    background: var(--wp-nav-bg);
     border-right: 1px solid var(--border);
     overflow: hidden;
     transition: width .16s ease;
@@ -693,7 +700,7 @@
     background: transparent; border: 1px solid transparent; border-radius: 5px;
     color: var(--text-muted); cursor: pointer;
   }
-  .wp-nav-toggle:hover { background: #eef0f3; color: var(--text); }
+  .wp-nav-toggle:hover { background: var(--wp-nav-hover); color: var(--text); }
   /* Arrow flips to point right when the panel is closed. */
   body.wp-nav-collapsed .wp-nav-toggle-arrow { transform: rotate(180deg); transform-origin: 11px 10px; }
 
@@ -703,23 +710,23 @@
     flex: 1 1 auto; min-width: 0;
     display: inline-flex; align-items: center; justify-content: flex-start; gap: 9px;
     height: 40px; padding: 0 14px;
-    background: var(--accent); color: #fff;
+    background: var(--accent); color: var(--cds-text-on-color);
     border: 0; border-radius: 6px 0 0 6px;
     font: inherit; font-size: 14px; font-weight: 600;
     cursor: pointer; white-space: nowrap;
   }
-  .wp-nav-cta:hover { background: #0353e9; }
+  .wp-nav-cta:hover { background: var(--cds-hover-primary); }
   .wp-nav-cta-plus { font-size: 17px; font-weight: 400; line-height: 1; }
   .wp-nav-cta-more {
     flex: 0 0 auto; width: 30px; height: 40px;
-    background: var(--accent); color: #fff; border: 0; border-left: 1px solid rgba(255,255,255,.28);
+    background: var(--accent); color: var(--cds-text-on-color); border: 0; border-left: 1px solid var(--wp-on-accent-divider);
     border-radius: 0 6px 6px 0; font: inherit; font-size: 12px; cursor: pointer;
   }
-  .wp-nav-cta-more:hover { background: #0353e9; }
+  .wp-nav-cta-more:hover { background: var(--cds-hover-primary); }
   .wp-nav-menu {
     position: absolute; top: calc(100% - 6px); left: 10px; right: 10px; z-index: 10;
     background: var(--surface); border: 1px solid var(--border-strong); border-radius: 6px;
-    box-shadow: 0 10px 26px rgba(20,30,50,.18); padding: 5px 0;
+    box-shadow: var(--wp-shadow-menu-lg); padding: 5px 0;
   }
   .wp-nav-menu[hidden] { display: none; }
   .wp-nav-menu button {
@@ -737,8 +744,8 @@
     font: inherit; font-size: 14px; color: var(--text);
     cursor: pointer; text-align: left; white-space: nowrap;
   }
-  .wp-nav-link:hover { background: #eef0f3; }
-  .wp-nav-link.is-current { background: #e8eaed; font-weight: 600; }
+  .wp-nav-link:hover { background: var(--wp-nav-hover); }
+  .wp-nav-link.is-current { background: var(--wp-nav-active); font-weight: 600; }
   .wp-nav-ico { flex: 0 0 20px; width: 20px; text-align: center; font-size: 15px; color: var(--text-muted); }
   .wp-nav-link-label { flex: 1 1 auto; overflow: hidden; text-overflow: ellipsis; }
   .wp-nav-link-n { flex: 0 0 auto; font-size: 12px; color: var(--text-dim); font-variant-numeric: tabular-nums; }
@@ -770,8 +777,8 @@
     background: none; border: 0; border-radius: 6px;
     font: inherit; color: var(--text); text-align: left; cursor: pointer;
   }
-  .wp-nav-item:hover { background: #eef0f3; }
-  .wp-nav-item.active { background: #e8eaed; }
+  .wp-nav-item:hover { background: var(--wp-nav-hover); }
+  .wp-nav-item.active { background: var(--wp-nav-active); }
   /* Left accent bar on the current package, like Planner's selected plan. */
   .wp-nav-item.active::before {
     content: ''; position: absolute; left: 0; top: 6px; bottom: 6px;
@@ -781,7 +788,7 @@
     flex: 0 0 28px; width: 28px; height: 28px; border-radius: 5px;
     display: inline-flex; align-items: center; justify-content: center;
     font-family: var(--sans); font-size: 11px; font-weight: 700; letter-spacing: .02em;
-    color: #fff; text-transform: uppercase;
+    color: var(--cds-text-on-color); text-transform: uppercase;
   }
   .wp-nav-body { min-width: 0; flex: 1 1 auto; }
   .wp-nav-num { display: block; font-size: 13.5px; font-weight: 600; color: var(--text);
@@ -815,13 +822,13 @@
   /* Narrow screens: keep the rail collapsed-width so the form still has room. */
   @media (max-width: 860px) {
     body { --nav-w: 56px; }
-    body:not(.wp-nav-collapsed) .wp-nav { width: 288px; box-shadow: 6px 0 22px rgba(20,30,50,.16); }
+    body:not(.wp-nav-collapsed) .wp-nav { width: 288px; box-shadow: var(--wp-shadow-rail); }
   }
 
   /* Sticky save bar */
   .sticky-save{ position:fixed; left:var(--nav-w,288px); right:0; bottom:0; z-index:40; display:flex; align-items:center;
-    justify-content:space-between; gap:14px; padding:10px 20px; background:#fff;
-    border-top:1px solid var(--border-strong); box-shadow:0 -2px 10px rgba(20,30,50,.08); }
+    justify-content:space-between; gap:14px; padding:10px 20px; background:var(--surface);
+    border-top:1px solid var(--border-strong); box-shadow:var(--wp-shadow-sticky); }
   .sticky-save .sticky-status{ font-size:13px; font-weight:600; }
   .sticky-save .sticky-actions{ display:flex; gap:10px; }
   .ss-ready{ color:var(--accent-green); }
@@ -836,7 +843,7 @@
   .disc-pill:hover { border-color:var(--accent); color:var(--text); }
   .disc-pill input { display:none; }
   .disc-pill .dot { width:7px; height:7px; border-radius:50%; background:var(--border-strong); transition:background .12s; flex-shrink:0; }
-  .disc-pill.selected { border-color:var(--accent); background:var(--accent-dim,#eef3fd); color:var(--accent); }
+  .disc-pill.selected { border-color:var(--accent); background:var(--accent-dim); color:var(--accent); }
   .disc-pill.selected .dot { background:var(--accent); }
   .disc-scope { border:1px solid var(--border); border-left:3px solid var(--accent); border-radius:6px; padding:12px 14px; margin-bottom:12px; background:var(--bg); }
   .disc-scope-head { display:flex; align-items:center; justify-content:space-between; gap:10px; margin-bottom:8px; flex-wrap:wrap; }
@@ -851,7 +858,7 @@
   .dash-metric .dm-label { font-size:11px; color:var(--text-muted); margin-top:6px; text-transform:uppercase; letter-spacing:.03em; }
   .dash-metric.dm-green .dm-val { color:var(--accent-green); }
   .dash-metric.dm-red .dm-val { color:var(--red); }
-  .dash-metric.dm-blue .dm-val { color:var(--accent, #0f62fe); }
+  .dash-metric.dm-blue .dm-val { color:var(--accent); }
   .dash-metric[onclick] { cursor:pointer; transition:border-color .12s, box-shadow .12s; }
   .dash-metric[onclick]:hover { border-color:var(--accent); }
   .dash-metric.dm-active { border-color:var(--accent); box-shadow:0 0 0 2px var(--accent-dim); }
diff --git a/html/wp-sidenav.css b/html/wp-sidenav.css
index 8bef14e..2801c5e 100644
--- a/html/wp-sidenav.css
+++ b/html/wp-sidenav.css
@@ -5,24 +5,27 @@
    sidebar would either squeeze that column or hide on the one device that matters.
    Overlay behaves identically everywhere, which is also one less layout to test.
 
-   Colours come from the dark app bar it hangs off (#161616 / Carbon Gray 100), not
-   from theme-light.css, so the drawer reads as an extension of the bar. */
+   Colours come from the dark app bar it hangs off, so the drawer reads as an
+   extension of the bar. Until T3.2 that intent was written as hardcoded hex —
+   30 of them — which made the drawer only accidentally match the bar. It now
+   reads the same --wp-appbar-* tokens the bar does, so the stated intent is
+   actually true and flipping --wp-appbar-bg takes the drawer with it. */
 
 .wp-navbtn{
   flex: 0 0 auto; display: inline-flex; align-items: center; justify-content: center;
   width: 40px; height: 40px; margin-right: 4px; padding: 0;
   background: none; border: none; border-radius: 0; cursor: pointer;
-  color: #f4f4f4; font-family: inherit; line-height: 1;
+  color: var(--cds-text-inverse); font-family: inherit; line-height: 1;
 }
-.wp-navbtn:hover{ background: #353535; }
-.wp-navbtn:focus-visible{ outline: 2px solid #ffffff; outline-offset: -2px; }
+.wp-navbtn:hover{ background: var(--wp-appbar-hover); }
+.wp-navbtn:focus-visible{ outline: 2px solid var(--wp-appbar-fg); outline-offset: -2px; }
 /* A light bar (the SOP suite / creator headers) needs the opposite ink. */
-.wp-navbtn[data-bar="light"]{ color: #161616; }
-.wp-navbtn[data-bar="light"]:hover{ background: #e8e8e8; }
+.wp-navbtn[data-bar="light"]{ color: var(--cds-text-primary); }
+.wp-navbtn[data-bar="light"]:hover{ background: var(--cds-layer-hover); }
 
 .wp-navscrim{
   position: fixed; inset: 0; z-index: 10010;
-  background: rgba(22,22,22,.55);
+  background: var(--wp-scrim-drawer);
   opacity: 0; transition: opacity .18s ease;
 }
 .wp-navscrim.is-open{ opacity: 1; }
@@ -32,10 +35,10 @@
   position: fixed; top: 0; left: 0; bottom: 0; z-index: 10011;
   width: min(284px, 84vw);
   display: flex; flex-direction: column;
-  background: #161616; color: #f4f4f4;
-  font-family: 'IBM Plex Sans', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+  background: var(--wp-appbar-bg); color: var(--cds-text-inverse);
+  font-family: var(--wp-font-sans-2);
   transform: translateX(-100%); transition: transform .2s ease;
-  box-shadow: 2px 0 16px rgba(0,0,0,.4);
+  box-shadow: var(--wp-shadow-drawer);
   overflow: hidden;
 }
 .wp-sidenav.is-open{ transform: translateX(0); }
@@ -46,63 +49,63 @@
 
 .wp-sidenav-head{
   display: flex; align-items: center; gap: 10px;
-  padding: 12px 14px; border-bottom: 1px solid #393939; flex: 0 0 auto;
+  padding: 12px 14px; border-bottom: 1px solid var(--cds-inverse-02); flex: 0 0 auto;
 }
 .wp-sidenav-head .wp-logo-chip{ flex: 0 0 auto; }
 .wp-sidenav-title{ font-size: 13px; font-weight: 600; line-height: 1.25; }
-.wp-sidenav-title span{ display: block; font-size: 11px; font-weight: 400; color: #a8a8a8; }
+.wp-sidenav-title span{ display: block; font-size: 11px; font-weight: 400; color: var(--cds-text-placeholder); }
 
 /* The active project, in full (B2). Below 1024px the app bar shows the project
    number alone, so this is where the whole name has to be readable — it wraps on
    as many lines as it needs and is never truncated. */
 .wp-sidenav-proj{
-  padding: 12px 14px; border-bottom: 1px solid #393939; flex: 0 0 auto;
+  padding: 12px 14px; border-bottom: 1px solid var(--cds-inverse-02); flex: 0 0 auto;
   display: flex; flex-direction: column; gap: 2px;
 }
 .wp-sidenav-proj[hidden]{ display: none; }
 .wp-sidenav-proj-k{
   font-size: 10px; font-weight: 600; letter-spacing: .08em;
-  text-transform: uppercase; color: #a8a8a8;
+  text-transform: uppercase; color: var(--cds-text-placeholder);
 }
 .wp-sidenav-proj strong{
-  font-size: 13px; font-weight: 600; line-height: 1.3; color: #f4f4f4;
+  font-size: 13px; font-weight: 600; line-height: 1.3; color: var(--cds-text-inverse);
   overflow-wrap: anywhere;
 }
-.wp-sidenav-proj-n{ font-size: 11px; color: #c6c6c6; }
+.wp-sidenav-proj-n{ font-size: 11px; color: var(--wp-appbar-fg-dim); }
 .wp-sidenav-close{
   margin-left: auto; width: 32px; height: 32px; padding: 0; flex: 0 0 auto;
-  background: none; border: none; border-radius: 0; color: #c6c6c6;
+  background: none; border: none; border-radius: 0; color: var(--wp-appbar-fg-dim);
   font-size: 18px; line-height: 1; cursor: pointer; font-family: inherit;
 }
-.wp-sidenav-close:hover{ background: #353535; color: #fff; }
+.wp-sidenav-close:hover{ background: var(--wp-appbar-hover); color: var(--wp-appbar-fg); }
 
 .wp-sidenav-body{ flex: 1 1 auto; overflow-y: auto; padding: 6px 0 18px; }
 .wp-sidenav-sect{
   padding: 14px 16px 4px; font-size: 11px; font-weight: 600;
-  letter-spacing: .06em; text-transform: uppercase; color: #8d8d8d;
+  letter-spacing: .06em; text-transform: uppercase; color: var(--cds-ui-04);
 }
 .wp-sidenav-link{
   display: flex; align-items: center; gap: 12px; width: 100%;
   /* 44px minimum: this is tapped with a work glove on. */
   min-height: 44px; padding: 10px 16px;
   background: none; border: none; border-left: 3px solid transparent; border-radius: 0;
-  color: #f4f4f4; font: inherit; font-size: 14px; text-align: left; text-decoration: none;
+  color: var(--cds-text-inverse); font: inherit; font-size: 14px; text-align: left; text-decoration: none;
   cursor: pointer;
 }
-.wp-sidenav-link:hover{ background: #353535; }
-.wp-sidenav-link:focus-visible{ outline: 2px solid #ffffff; outline-offset: -2px; }
-.wp-sidenav-link.is-current{ background: #262626; border-left-color: #0f62fe; font-weight: 600; }
+.wp-sidenav-link:hover{ background: var(--wp-appbar-hover); }
+.wp-sidenav-link:focus-visible{ outline: 2px solid var(--wp-appbar-fg); outline-offset: -2px; }
+.wp-sidenav-link.is-current{ background: var(--wp-appbar-layer); border-left-color: var(--cds-interactive-01); font-weight: 600; }
 .wp-sidenav-ico{
-  flex: 0 0 20px; width: 20px; text-align: center; font-size: 15px; color: #c6c6c6;
+  flex: 0 0 20px; width: 20px; text-align: center; font-size: 15px; color: var(--wp-appbar-fg-dim);
 }
-.wp-sidenav-link.is-current .wp-sidenav-ico{ color: #78a9ff; }
+.wp-sidenav-link.is-current .wp-sidenav-ico{ color: var(--cds-link-inverse); }
 .wp-sidenav-label{ flex: 1 1 auto; min-width: 0; }
-.wp-sidenav-label small{ display: block; font-size: 11.5px; font-weight: 400; color: #a8a8a8; }
+.wp-sidenav-label small{ display: block; font-size: 11.5px; font-weight: 400; color: var(--cds-text-placeholder); }
 
 .wp-sidenav-foot{
-  flex: 0 0 auto; border-top: 1px solid #393939; padding: 8px 0;
+  flex: 0 0 auto; border-top: 1px solid var(--cds-inverse-02); padding: 8px 0;
 }
 .wp-sidenav-who{
-  padding: 6px 16px 8px; font-size: 12px; color: #a8a8a8;
+  padding: 6px 16px 8px; font-size: 12px; color: var(--cds-text-placeholder);
 }
-.wp-sidenav-who strong{ display: block; color: #f4f4f4; font-size: 13px; font-weight: 600; }
+.wp-sidenav-who strong{ display: block; color: var(--cds-text-inverse); font-size: 13px; font-weight: 600; }
diff --git a/tests/token_check.py b/tests/token_check.py
new file mode 100644
index 0000000..83c172b
--- /dev/null
+++ b/tests/token_check.py
@@ -0,0 +1,307 @@
+#!/usr/bin/env python3
+"""Prove a token refactor changed no rendered value — T3.2 / S5 / C3.
+
+Screenshots cannot settle wave 3. Three of the fourteen baseline shots are not
+stable capture-to-capture (the creator at 1440px and both admin widths re-render
+live content), so a pixel diff on those says nothing either way, and a pixel diff
+on the other eleven says nothing about the pages' hover, focus and disabled
+states, which is where half the tokens live.
+
+What wave 3 actually claims is narrower and fully checkable: every custom
+property still resolves to the same literal, and every element still computes the
+same colours, shadows and type as it did before. That is what this measures.
+
+    python tests/token_check.py --out before.json     # on the old build
+    python tests/token_check.py --out after.json      # on the new one
+    python tests/token_check.py --compare before.json after.json
+
+Self-contained in the same way as tests/browser_check.py, whose seed() and
+start_server() it reuses rather than growing a second fixture: throwaway SQLite,
+its own uvicorn, headless Edge or Chrome over CDP, all torn down afterwards. Your
+real database is never touched.
+
+Elements are keyed by identity — tag, id and classes, then an occurrence counter
+within the parent — rather than by sibling index. Index alone is not stable here:
+the SOP page injects a sync badge, a drawer scrim and a drawer from three
+different scripts, and they land in whichever order their async work finishes, so
+an index-keyed walk reports dozens of phantom differences for the same set of
+elements in a different order. All three are position:fixed with their own
+z-index, so the order changes nothing painted.
+
+Keys present in only one snapshot are reported as a count and never silently
+dropped — a page that renders a different number of rows is a fact about the
+fixture, not a pass.
+
+Exit codes: 0 identical · 1 a value changed · 2 could not run.
+"""
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+import tempfile
+import time
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+import cdp                                                    # noqa: E402
+from browser_check import seed, start_server, PW              # noqa: E402,F401
+
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+HTML = os.path.join(ROOT, "html")
+
+# Every page, and the user whose session renders the most of it.
+PAGES = [
+    ("login", "/login.html", None),
+    ("launcher", "/index.html", "root"),
+    ("sop", "/work-package-suite.html", "root"),
+    ("creator", "/wp-creation-index.html", "root"),
+    ("admin", "/admin.html", "root"),
+    ("users", "/users.html", "root"),
+    ("field", "/field.html", "root"),
+]
+
+# The properties a colour/type token can reach. Anything T3.2 touched lands in
+# one of these; anything that does not is not a token's business.
+PROPS = [
+    "color", "background-color", "border-top-color", "border-right-color",
+    "border-bottom-color", "border-left-color", "outline-color", "box-shadow",
+    "text-decoration-color", "caret-color", "column-rule-color",
+    "font-family", "font-size", "font-weight", "border-radius",
+]
+
+SNAPSHOT_JS = r"""
+(() => {
+  const props = %(props)s;
+  const names = %(names)s;
+
+  // Custom properties, resolved where they are actually declared: :root for the
+  // page sheets, and .wp-chrome for the two scoped blocks the shared chrome uses.
+  const tokens = {};
+  const rootCS = getComputedStyle(document.documentElement);
+  for (const n of names) {
+    const v = rootCS.getPropertyValue(n).trim();
+    if (v) tokens['root' + n] = v;
+  }
+  for (const sel of ['.wp-chrome', '.wp-chrome[data-bar="dark"]']) {
+    const el = document.querySelector(sel);
+    if (!el) continue;
+    const cs = getComputedStyle(el);
+    for (const n of names) {
+      const v = cs.getPropertyValue(n).trim();
+      if (v) tokens[sel + n] = v;
+    }
+  }
+
+  // Every element, keyed by identity rather than by sibling index. Index alone
+  // is not stable: three JS-injected overlays on the SOP page — the sync badge,
+  // the drawer scrim and the drawer — append in whichever order their async work
+  // finishes, so an index-keyed walk reports 55 phantom differences for a DOM
+  // that is the same set of elements in a different order. All three are
+  // position:fixed with their own z-index, so the order changes nothing painted.
+  // Signature first, then an occurrence counter within the parent, so identified
+  // elements keep their key when a sibling moves.
+  const sig = el => el.tagName
+    + (el.id ? '#' + el.id : '')
+    + (typeof el.className === 'string' && el.className.trim()
+        ? '.' + el.className.trim().split(/\s+/).sort().join('.') : '');
+  const els = {};
+  const walk = (el, path) => {
+    const cs = getComputedStyle(el);
+    els[path] = props.map(p => cs.getPropertyValue(p)).join('|');
+    const seen = {};
+    for (const c of el.children) {
+      const s = sig(c);
+      seen[s] = (seen[s] || 0) + 1;
+      walk(c, path + '/' + s + ':' + seen[s]);
+    }
+  };
+  walk(document.documentElement, 'HTML');
+  return JSON.stringify({ tokens, els, n: Object.keys(els).length });
+})()
+"""
+
+
+def token_names():
+    """Every custom-property name declared anywhere in html/. Read from the
+    working tree, so each build contributes its own names and the comparison is
+    over the intersection — a build that adds tokens is not a difference."""
+    names = set()
+    for fn in sorted(os.listdir(HTML)):
+        if not fn.endswith((".css", ".html")):
+            continue
+        txt = open(os.path.join(HTML, fn), encoding="utf-8", errors="replace").read()
+        txt = re.sub(r"/\*.*?\*/", "", txt, flags=re.S)
+        names.update(re.findall(r"(--[A-Za-z0-9_-]+)\s*:", txt))
+    return sorted(names)
+
+
+def capture(page, base, tok, names):
+    js = SNAPSHOT_JS % {"props": json.dumps(PROPS), "names": json.dumps(names)}
+    out = {}
+    for label, path, user in PAGES:
+        page.clear_cookies()
+        if user:
+            page.set_cookie("wp_session", tok[user])
+        page.goto(base + path)
+        time.sleep(1.2)                       # let the render-blocking scripts settle
+        raw = page.eval(js)
+        out[label] = json.loads(raw) if isinstance(raw, str) else raw
+        print("  captured  %-9s %d elements, %d resolved tokens"
+              % (label, out[label]["n"], len(out[label]["tokens"])))
+    return out
+
+
+def norm(v):
+    """A custom property's value is stored as the text that was written, so
+    `#fff` and `#ffffff`, or `rgba(0,0,0,0.16)` and `rgba(0, 0, 0, .16)`, compare
+    unequal as strings while resolving to the same paint. Consolidating those two
+    notations into one is half of what T3.2 is for, so reporting them as
+    regressions would make this check cry wolf on its own success.
+
+    Normalising here is safe precisely because the element comparison below is
+    the real evidence: if a normalisation ever hid a genuine change, every
+    element consuming that token would show it."""
+    v = v.strip().lower().replace('"', "'")
+    v = re.sub(r"\s*,\s*", ",", v)
+    v = re.sub(r"\(\s*", "(", v)
+    v = re.sub(r"\s*\)", ")", v)
+    v = re.sub(r"\s+", " ", v)
+    v = re.sub(r"#([0-9a-f])([0-9a-f])([0-9a-f])\b", r"#\1\1\2\2\3\3", v)
+    v = re.sub(r"(?<![\w.])\.(\d)", r"0.\1", v)          # .16 -> 0.16
+    v = re.sub(r"(\d)\.0*(?=[,)\s]|$)", r"\1", v)        # 1.0 -> 1
+    return v
+
+
+def compare(a, b):
+    bad = 0
+    notation = 0
+    print("\n%-9s  %-34s  %s" % ("PAGE", "TOKENS", "ELEMENTS"))
+    print("-" * 78)
+    for label, _, _ in PAGES:
+        pa, pb = a.get(label), b.get(label)
+        if not pa or not pb:
+            print("%-9s  MISSING from one snapshot" % label)
+            bad += 1
+            continue
+
+        shared = set(pa["tokens"]) & set(pb["tokens"])
+        raw = [k for k in sorted(shared) if pa["tokens"][k] != pb["tokens"][k]]
+        tdiff = [k for k in raw if norm(pa["tokens"][k]) != norm(pb["tokens"][k])]
+        notation += len(raw) - len(tdiff)
+        only_b = len(set(pb["tokens"]) - set(pa["tokens"]))
+
+        keys = set(pa["els"]) & set(pb["els"])
+        ediff = [k for k in sorted(keys) if pa["els"][k] != pb["els"][k]]
+        gone, added = len(set(pa["els"]) - keys), len(set(pb["els"]) - keys)
+
+        tmsg = "%d same" % len(shared) if not tdiff else "%d CHANGED" % len(tdiff)
+        if only_b:
+            tmsg += " (+%d new)" % only_b
+        emsg = "%d same" % len(keys) if not ediff else "%d CHANGED" % len(ediff)
+        if gone or added:
+            emsg += "  [%d only-before, %d only-after]" % (gone, added)
+        flag = "  " if not (tdiff or ediff) else ">>"
+        print("%s %-9s %-34s  %s" % (flag, label, tmsg, emsg))
+
+        for k in tdiff[:12]:
+            print("      token %s\n            before %s\n            after  %s"
+                  % (k, pa["tokens"][k], pb["tokens"][k]))
+        if len(tdiff) > 12:
+            print("      ... and %d more" % (len(tdiff) - 12))
+        for k in ediff[:12]:
+            va, vb = pa["els"][k].split("|"), pb["els"][k].split("|")
+            for p, x, y in zip(PROPS, va, vb):
+                if x != y:
+                    print("      %s  %s: %s -> %s" % (k, p, x, y))
+        if len(ediff) > 12:
+            print("      ... and %d more elements" % (len(ediff) - 12))
+        bad += len(tdiff) + len(ediff)
+    if notation:
+        print("\n  %d token(s) differ in notation only (#fff vs #ffffff and the"
+              " like)." % notation)
+        print("  Not counted as a change: every element consuming them computed"
+              " the same value.")
+    return bad
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Token-resolution snapshot and diff")
+    ap.add_argument("--out", help="write a snapshot here")
+    ap.add_argument("--compare", nargs=2, metavar=("BEFORE", "AFTER"))
+    ap.add_argument("--base-url", help="use an already-running server")
+    args = ap.parse_args()
+
+    if args.compare:
+        a = json.load(open(args.compare[0], encoding="utf-8"))
+        b = json.load(open(args.compare[1], encoding="utf-8"))
+        bad = compare(a, b)
+        print("\n" + "-" * 78)
+        if bad:
+            print("%d difference(s). The refactor changed a rendered value.\n" % bad)
+            return 1
+        print("No token and no computed value changed on any page.\n")
+        return 0
+
+    if not args.out:
+        ap.error("give --out to capture, or --compare A B to diff")
+
+    exe = cdp.find_browser()
+    if not exe:
+        print("no headless-capable browser found; set WP_BROWSER.")
+        return 2
+
+    names = token_names()
+    print("\nToken check — %d custom-property names declared in html/" % len(names))
+    print("Browser: %s" % exe)
+
+    tmpdir = tempfile.mkdtemp(prefix="wpsuite-token-check-")
+    db_path = os.path.join(tmpdir, "check.db")
+    server = None
+    try:
+        tok = seed(db_path)
+        if args.base_url:
+            base = args.base_url.rstrip("/")
+        else:
+            port = cdp.free_port()
+            base = "http://127.0.0.1:%d" % port
+            server = start_server(port, db_path)
+            if server is None:
+                print("the test server would not start.")
+                return 2
+        print("Target:  %s\n" % base)
+        browser = cdp.Browser(exe)
+        page = browser.page()
+        try:
+            snap = capture(page, base, tok, names)
+        finally:
+            page.close()
+            browser.close()
+        with open(args.out, "w", encoding="utf-8") as fh:
+            json.dump(snap, fh)
+        print("\n  wrote %s" % args.out)
+        return 0
+    finally:
+        if server:
+            server.kill()
+            try:
+                server.wait(timeout=10)
+            except subprocess.TimeoutExpired:
+                pass
+        try:
+            from server.db import engine
+            engine.dispose()
+        except Exception:
+            pass
+        import shutil
+        for _ in range(10):
+            shutil.rmtree(tmpdir, ignore_errors=True)
+            if not os.path.exists(tmpdir):
+                break
+            time.sleep(0.3)
+
+
+if __name__ == "__main__":
+    sys.exit(main())