Project-SDE-WP-Suite/docs/waves/wave-3.md

# Wave 3 — Token consolidation and one button system

**Items:** `C3`, `S5`, `A3`/`F5` (full), `A5`
**Depends on:** wave 2 merged
**Why here:** every remaining visual task lands once instead of four times. Skipping this
means "one button system" gets implemented in four token systems and drifts, which is exactly
how `.field-hint` broke.

This wave should produce **no intentional visual change** except the two known defects it
fixes. Treat any other diff in the screenshot comparison as a bug in your refactor.

---

### T3.1 — Inventory the token systems

- **Items:** `C3` part 1, `S5` part 1
- **Depends on:** T2.3
- **Blocks:** T3.2
- **Surface:** documentation
- **Files:** creates `docs/reference/tokens.md`

**Problem:** Four parallel token systems. `#0f62fe` alone is declared four times, as
`--cds-interactive-01`, `--primary`, and `--accent` twice.

**Do:** Produce a mapping table: every custom property and every raw hex, hsl or rgb value in
the four stylesheets, where it is declared, what consumes it, and which canonical token it
maps to. Include spacing and type scales, not just color. Mark genuine duplicates,
near-duplicates (values one or two hex digits apart, which are usually accidents), and
one-offs.

**Do not:** change any stylesheet in this task.

**Done when:**

- [ ] `docs/reference/tokens.md` lists every declaration with file and line
- [ ] every value is mapped to a proposed canonical token or flagged as a one-off with a reason
- [ ] near-duplicates are called out explicitly, since those are where unintended visual change will come from
- [ ] the `#0f62fe` count matches or corrects the wave 0 baseline count

---

### T3.2 — Establish one source of truth

- **Items:** `C3` part 2, `S5` part 2
- **Depends on:** T3.1
- **Blocks:** T3.3, T3.4, T4.6, T4.7
- **Surface:** `html/`
- **Files:** all 4 stylesheets

**Do:** Create the canonical token set in one place. Convert the other stylesheets to alias
it. Page stylesheets declare no new values. Keep existing custom property names as aliases
where deleting them would touch large amounts of markup — an alias pointing at the canonical
token is fine; a second declaration of the same literal is not.

**Do not:** change any rendered value in this task, including the two known defects. Fix
those in `T3.3` and `T3.4` so their diffs are reviewable separately from a 4-stylesheet
refactor.

**Done when:**

- [ ] exactly one declaration exists per canonical value; grep for `#0f62fe` returns 1
- [ ] no page stylesheet declares a raw color, spacing or type value
- [ ] screenshot diff against the wave 2 state is empty on all 6 pages at both widths
- [ ] `docs/reference/tokens.md` is updated to reflect what was actually built

---

### T3.3 — Fix `.field-hint` and the drift it documents

- **Items:** `S5` part 3
- **Depends on:** T3.2
- **Blocks:** nothing
- **Surface:** `html/`
- **Files:** `work-package-suite-styles.css` around line 336

**Problem:** There is a comment at `work-package-suite-styles.css:336` describing
`.field-hint` rendering unstyled. It is the documented consequence of the duplicate token
systems.

**Do:** Fix `.field-hint` properly now that the tokens are consolidated, and delete the
comment. Then check for the same class of failure elsewhere: any selector that silently
renders unstyled because it referenced a token the page never saw.

**Done when:**

- [ ] `.field-hint` renders correctly everywhere it appears
- [ ] the stale comment is deleted
- [ ] any other silently-unstyled selectors found are listed in the PR and either fixed or logged

---

### T3.4 — A3/F5 full fix: fields look editable

- **Items:** `A3`, `F5` full
- **Depends on:** T3.2
- **Blocks:** T5.1
- **Surface:** `html/`
- **Files:** SOP wizard stylesheet

**Do:** Remove the wizard's local field token override entirely, so it consumes the canonical
field token. Remove the interim fix from `T1.5` rather than leaving both.

**Done when:**

- [ ] the wizard declares no field-specific color of its own
- [ ] enabled inputs are visually identical to enabled inputs on every other page
- [ ] disabled inputs remain clearly distinguishable from enabled ones
- [ ] the `T1.5` interim change is gone; grep confirms it

---

### T3.5 — A5: one button system

- **Items:** `A5`
- **Depends on:** T3.2
- **Blocks:** T5.1, T7.2
- **Surface:** `html/`
- **Files:** button styles, and any page overriding them

**Problem:** Green `Save & View` and green `SOP Complete` against blue everywhere else. Two
button languages competing.

**Do:** One button system: primary, secondary, tertiary, destructive. Map every existing
button to one of those roles. Green becomes a status color, not an action color.

Apply sentence case **to buttons and field labels only**.

**Do not:** touch the uppercase card-header idiom in `console.css`. It is deliberate, it
works, and the review specifically scoped the sentence-case rule to exclude it. Changing it
is out of scope.

**Done when:**

- [ ] every button in the app maps to one of four documented roles
- [ ] no green action buttons remain; `Save & View` and `SOP Complete` use the primary role
- [ ] buttons and field labels are sentence case
- [ ] uppercase card headers in `console.css` are unchanged — confirm by diff
- [ ] button roles are documented in `docs/reference/tokens.md`

---

## Wave 3 exit criteria

- [ ] one token source of truth; page sheets alias only
- [ ] `#0f62fe` declared once
- [ ] no unintended visual change on any page versus wave 2
- [ ] fields look editable, buttons speak one language