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