feat(tokens): SPELWork step ramp, color.stage.0 to .5 (#172) #226

Merged

peterswimm merged 1 commit from feat/172-stage-ramp into main

2026-10-23 20:24:29 +00:00

ville commented

2026-10-23 20:24:12 +00:00

Member

Refs #172. Does not close it. Peter signs off before merge.

Scope

The DTCG entries for the SPELWork pipeline step ramp that Peter confirmed in #172 (2026-10-21). The steps are the six dimension stages: Foundation, Intent, Structure, Execution, Scale, Outcome. Colour is one sequential brand-blue lightness ramp. The icon (spel.stage.0 to .5) and the name always travel with the colour.

Brand/UDG/dtcg/color.json: new color.stage.0 to .5, light and dark.
Brand/UDG/products/spelwork/dtcg/color.json: the same six tokens, light values only.
udg/generators/extract.py: short aliases --stage-0 to --stage-5.
udg/generators/wcag.py: 18 non-text 3:1 pairs.
Brand/specs/spelwork/spelwork-dashboard-design-part1.md: section 4 rewritten from "blocked" to the decided model.

Stage	Light	Dark
0 Foundation	`#5172A6`	`#5475A9`
1 Intent	`#416194`	`#638AC5`
2 Structure	`#315182`	`#739FE2`
3 Execution	`#224170`	`#86B4FD`
4 Scale	`#13315F`	`#A9CAFD`
5 Outcome	`#04214E`	`#CDDFFD`

Not in this PR: #173 (colour-blind check), text-on-stage tokens, any SPELWork dark theme, any change to the Part 2 spec.

Testing

No new unit tests. The behaviour change is in the wcag.py pair list, and wcag.py check --all is the gate for it.

All 10 build commands and all 13 check commands pass (each justfile recipe command was run directly because just is not installed on this machine).
python3 -m pytest generator/tests/: 400 passed, 20 skipped.
The new pairs run in SPELWork (18 rows, light only, lowest 3.85:1) and in toilville and wp-themes (36 rows each, light and dark, lowest 3.24:1). No failures. Products without the tokens skip the pairs.
Contrast with the surface rises with every step in both themes. OKLCH lightness gaps are 0.057 to 0.060 (light) and 0.067 to 0.070 (dark).

Impact Statement

Existing features: none change. These are new tokens.
Public APIs / contracts: new CSS vars --stage-0 to --stage-5 (toilville, wp-themes) and --udg-color-stage-0 to -5 (SPELWork). New Dart keys stage0 to stage5.
Schemas: none.
Data / artifacts: dist/ regenerated for spelwork, toilville and wp-themes (23 files). rituals, blocks and the other products are unchanged.
Integrations: none.
Mappings: new wcag.py pairs, each stage against bg.surface, bg.surface-raised and bg.surface-variant.
Backward compatibility: no existing token changes.

Docs

Part 1 spec section 4 is rewritten, and its open questions are updated.

Remaining review points

SPELWork receives light stage values only. It has no dark theme and no dark surfaces. A dark stage value in its skin would apply under prefers-color-scheme: dark while the surface stays light, and stages 2 to 5 would fall to 2.67, 2.09, 1.66 and 1.34:1 on #FEFEFE. So no dark stage override is emitted for SPELWork until it has a dark theme. The dark values are defined in the baseline.
Dark Execution reuses the Sanctum value on purpose. color.stage.3 dark is #86B4FD, the same as color.accent.sanctum dark. The earlier value #88ACE4 was a near duplicate. The overlap is accepted because a stage is always shown with its icon and name. The other dark steps are spaced around this anchor.
No text-on-stage tokens were added. The ink differs by step. Light steps take white. In the dark theme, step 0 takes white (4.67:1) and steps 1 to 5 take #0A1B33 (4.91:1 to 12.79:1). The rule is documented in the spec. wcag.py does not check text on a stage fill. If the dashboards place text directly on steps, that needs a follow-up.
The Part 2 spec has stale wording. It says the step ramp tokens are "not drafted" and still carries #174 wording from before #225 merged. It will be updated after this PR merges.
#173 can proceed once these stage values are under review. The colour-blind check for the step ramp runs against them.
The ramp starts darker than the brand blue #7394C8. The brand blue gives 3.06:1 on bg.surface, but only 2.72:1 on bg.surface-raised and 2.44:1 on bg.surface-variant, so it cannot be a step.

Refs #172. Does not close it. Peter signs off before merge. ## Scope The DTCG entries for the SPELWork pipeline step ramp that Peter confirmed in #172 (2026-10-21). The steps are the six dimension stages: Foundation, Intent, Structure, Execution, Scale, Outcome. Colour is one sequential brand-blue lightness ramp. The icon (`spel.stage.0` to `.5`) and the name always travel with the colour. - `Brand/UDG/dtcg/color.json`: new `color.stage.0` to `.5`, light and dark. - `Brand/UDG/products/spelwork/dtcg/color.json`: the same six tokens, light values only. - `udg/generators/extract.py`: short aliases `--stage-0` to `--stage-5`. - `udg/generators/wcag.py`: 18 non-text 3:1 pairs. - `Brand/specs/spelwork/spelwork-dashboard-design-part1.md`: section 4 rewritten from "blocked" to the decided model. | Stage | Light | Dark | |---|---|---| | 0 Foundation | `#5172A6` | `#5475A9` | | 1 Intent | `#416194` | `#638AC5` | | 2 Structure | `#315182` | `#739FE2` | | 3 Execution | `#224170` | `#86B4FD` | | 4 Scale | `#13315F` | `#A9CAFD` | | 5 Outcome | `#04214E` | `#CDDFFD` | Not in this PR: #173 (colour-blind check), text-on-stage tokens, any SPELWork dark theme, any change to the Part 2 spec. ## Testing No new unit tests. The behaviour change is in the `wcag.py` pair list, and `wcag.py check --all` is the gate for it. - All 10 build commands and all 13 check commands pass (each `justfile` recipe command was run directly because `just` is not installed on this machine). - `python3 -m pytest generator/tests/`: 400 passed, 20 skipped. - The new pairs run in SPELWork (18 rows, light only, lowest 3.85:1) and in `toilville` and `wp-themes` (36 rows each, light and dark, lowest 3.24:1). No failures. Products without the tokens skip the pairs. - Contrast with the surface rises with every step in both themes. OKLCH lightness gaps are 0.057 to 0.060 (light) and 0.067 to 0.070 (dark). ## Impact Statement - Existing features: none change. These are new tokens. - Public APIs / contracts: new CSS vars `--stage-0` to `--stage-5` (`toilville`, `wp-themes`) and `--udg-color-stage-0` to `-5` (SPELWork). New Dart keys `stage0` to `stage5`. - Schemas: none. - Data / artifacts: `dist/` regenerated for `spelwork`, `toilville` and `wp-themes` (23 files). `rituals`, `blocks` and the other products are unchanged. - Integrations: none. - Mappings: new `wcag.py` pairs, each stage against `bg.surface`, `bg.surface-raised` and `bg.surface-variant`. - Backward compatibility: no existing token changes. ## Docs Part 1 spec section 4 is rewritten, and its open questions are updated. ## Remaining review points 1. **SPELWork receives light stage values only.** It has no dark theme and no dark surfaces. A dark stage value in its skin would apply under `prefers-color-scheme: dark` while the surface stays light, and stages 2 to 5 would fall to 2.67, 2.09, 1.66 and 1.34:1 on `#FEFEFE`. So no dark stage override is emitted for SPELWork until it has a dark theme. The dark values are defined in the baseline. 2. **Dark Execution reuses the Sanctum value on purpose.** `color.stage.3` dark is `#86B4FD`, the same as `color.accent.sanctum` dark. The earlier value `#88ACE4` was a near duplicate. The overlap is accepted because a stage is always shown with its icon and name. The other dark steps are spaced around this anchor. 3. **No text-on-stage tokens were added.** The ink differs by step. Light steps take white. In the dark theme, step 0 takes white (4.67:1) and steps 1 to 5 take `#0A1B33` (4.91:1 to 12.79:1). The rule is documented in the spec. `wcag.py` does not check text on a stage fill. If the dashboards place text directly on steps, that needs a follow-up. 4. **The Part 2 spec has stale wording.** It says the step ramp tokens are "not drafted" and still carries #174 wording from before #225 merged. It will be updated after this PR merges. 5. **#173 can proceed** once these stage values are under review. The colour-blind check for the step ramp runs against them. 6. **The ramp starts darker than the brand blue `#7394C8`.** The brand blue gives 3.06:1 on `bg.surface`, but only 2.72:1 on `bg.surface-raised` and 2.44:1 on `bg.surface-variant`, so it cannot be a step.

ville added 1 commit

2026-10-23 20:24:13 +00:00

feat(tokens): SPELWork step ramp, color.stage.0 to .5 (#172 )

PR policy check / policy-gate (pull_request) Successful in 1s

Details

Security Scans / Trivy filesystem scan (pull_request) Successful in 1m1s

Details

Block Validation / validate (pull_request) Successful in 1m34s

Details

Security Scans / Gitleaks secret scan (pull_request) Successful in 59s

Details

Test Generator / lint-workflows (pull_request) Successful in 29s

Details

Test Generator / test (pull_request) Successful in 1m27s

Details

Test Generator / lint-prose (pull_request) Successful in 35s

Details

UDG dist drift gate / dist/ matches dtcg + udg sources (pull_request) Successful in 20s

Details

Copy coverage / Design copy reaching rendered HTML (pull_request) Successful in 48s

Details

efd3ae7390

Peter confirmed on 2026-10-21: the six steps are the dimension stages
(Foundation, Intent, Structure, Execution, Scale, Outcome), coloured by
one sequential brand-blue lightness ramp. The icon and the name always
travel with the colour.

Baseline Brand/UDG/dtcg/color.json defines color.stage.0 to .5 with a
light and a dark value:

  stage  light    dark
  0      #5172A6  #5475A9
  1      #416194  #638AC5
  2      #315182  #739FE2
  3      #224170  #86B4FD
  4      #13315F  #A9CAFD
  5      #04214E  #CDDFFD

- Contrast with the surface rises with every step in both themes.
  Lightness gaps are 0.057 to 0.060 (light) and 0.067 to 0.070 (dark).
- Dark stage 3 is the existing Sanctum value #86B4FD. The earlier
  #88ACE4 was a near duplicate. The overlap is accepted because a stage
  is always shown with its icon and name.
- SPELWork (Brand/UDG/products/spelwork) carries the same six tokens
  with light values only. It has no dark theme, and a dark stage value
  would apply under prefers-color-scheme: dark while its surface stays
  light (stages 2 to 5 would fall to 2.67 to 1.34:1). No dark stage
  override is emitted until SPELWork has a dark theme.
- No text-on-stage tokens. The ink rule is documented in the spec.

Generators:
- extract.py: SHORT_ALIAS --stage-0 to --stage-5.
- wcag.py: each stage needs 3:1 on bg.surface, bg.surface-raised and
  bg.surface-variant (18 non-text pairs, WCAG 1.4.11).

Part 1 spec section 4 rewritten from "blocked" to the decided model.

dist/ regenerated with the build commands. All 13 check commands pass.