SPELWork dashboards: turn the severity + dark-accent proposals into tokens #174

New issue

Closed

opened 2026-09-28 20:29:23 +00:00 by forge-ci · 4 comments

forge-ci commented 2026-09-28 20:29:23 +00:00

Member

Copy link

Two sets of values in spelwork-dashboard-design-part1.md exist only in that doc and a one-off HTML file:

• §3 severity tokens: severity-slow (#B45309 / #FACC15) and severity-critical (#9F1239 / #FB7185), sitting between the existing safety-* tokens.
• Dark-mode accent variants: sanctum #397FEF, pilgrimage #D161C0, federation #9197AC, trust #A275F0 and error #F87171. Each passes AA on #121212, where the canonical values fail.

Before starting

@peterswimm needs to sign off on both sets. The spec's open questions ask for exactly this, and brand colour changes need approval from Toilville leadership.

Acceptance criteria

• Update the spec to the current sources. It still cites packages/udg/lib/src/token_registry.dart and dist/udg-tokens.css, both removed in the 2026-06-27 cut-over. Colour now lives in Brand/UDG/dtcg/color.json (baseline) and Brand/UDG/products/<name>/dtcg/color.json.
• Decide the level for each set: baseline or product (spelwork / rituals). A product override needs a RATIONALE.yml entry.
• Add the approved values as DTCG entries. just build then regenerates dist/, and just check (WCAG AA across every product and theme) must pass.

Two sets of values in [`spelwork-dashboard-design-part1.md`](https://git.toilville.dev/Toilville/toilville-design/src/branch/main/Brand/specs/spelwork/spelwork-dashboard-design-part1.md) exist only in that doc and a one-off HTML file: - **§3 severity tokens**: `severity-slow` (`#B45309` / `#FACC15`) and `severity-critical` (`#9F1239` / `#FB7185`), sitting between the existing `safety-*` tokens. - **Dark-mode accent variants**: sanctum `#397FEF`, pilgrimage `#D161C0`, federation `#9197AC`, trust `#A275F0` and error `#F87171`. Each passes AA on `#121212`, where the canonical values fail. ## Before starting @peterswimm needs to sign off on both sets. The spec's open questions ask for exactly this, and brand colour changes need approval from Toilville leadership. ## Acceptance criteria - [ ] Update the spec to the current sources. It still cites `packages/udg/lib/src/token_registry.dart` and `dist/udg-tokens.css`, both removed in the 2026-06-27 cut-over. Colour now lives in `Brand/UDG/dtcg/color.json` (baseline) and `Brand/UDG/products/<name>/dtcg/color.json`. - [ ] Decide the level for each set: baseline or product (spelwork / rituals). A product override needs a `RATIONALE.yml` entry. - [ ] Add the approved values as DTCG entries. `just build` then regenerates `dist/`, and `just check` (WCAG AA across every product and theme) must pass.

ville was assigned by forge-ci 2026-09-28 20:29:23 +00:00

forge-ci commented 2026-09-28 20:56:50 +00:00

Author

Member

Copy link

Recommendation: keep theme modes; four severity levels plus a stale state

Dark accents: no separate *-on-dark tokens

The standard way to do dark mode is one semantic token with a value per theme (DTCG modes, Material / Apple semantic colours). Rituals' color.json already works this way and has dark values for all five accents.

The spec measured contrast against #121212. Rituals' real dark surface is cocoa #2B1810, and on it the existing theme values beat the spec's proposals in four of five cases:

accent	current Rituals dark	spec proposal
sanctum	#86B4FD 8.03:1	#397FEF 4.40:1 (fails AA)
pilgrimage	#CD91C4 6.80:1	#D161C0 4.98:1
federation	#B5C1D7 9.33:1	#9197AC 5.82:1
trust	#A78BFA 6.22:1	#A275F0 5.11:1
error	#BE5656 3.75:1 (fails AA)	#F87171 6.12:1

So: keep the current values, and change only Rituals' dark color.accent.error to #F87171.

Severity: don't adopt the five-state proposal as written

1. "Old" isn't a severity. It describes data freshness. Grafana and Datadog show stale or missing data as a separate neutral state.
2. It reuses the governance colours safety.allow/review/block for operational health, giving one token two meanings. §4 of the spec warns against exactly that for the mode colours.
3. In light mode the states only differ by hue. fine, old, broken and very serious are all dark (8.7–10:1 on white, relative luminance 0.055–0.081), and very serious is lighter than broken. In greyscale or with red-green colour blindness they collapse.

Proposed instead: the common four levels (Grafana alert states, PagerDuty) plus a neutral state for no data:

state	level	token
fine	ok	existing accent.success
slow	warning	existing accent.warning
broken	error	existing accent.error
very serious	critical	new accent.critical
old	stale / no data	new neutral (on the neutral.warm-* family)

Every state is shown with an icon and its name (spec §5 already asks for the name). Lightness has to step in order from ok to critical, so the scale reads without hue.

Needs a decision first

The baseline success / warning / error (#12883E / #CD4D0B / #DC2626) have the same value in light and dark:

• On cocoa they reach only 3.72 / 3.76 / 3.50:1.
• warning is 4.47:1 on white, just under AA.

They need real dark values before the dashboards can build on them. That's a brand colour change, so @peterswimm signs off.

Acceptance criteria, revised

• Peter approves the four-plus-stale model and the baseline dark values.
• Rituals dark accent.error → #F87171.
• Add accent.critical and the stale neutral, light and dark, with lightness in order. just check stays green.
• Update the spec to the current sources (Brand/UDG/dtcg/color.json, Brand/UDG/products/<name>/dtcg/color.json).

## Recommendation: keep theme modes; four severity levels plus a stale state ### Dark accents: no separate `*-on-dark` tokens The standard way to do dark mode is one semantic token with a value per theme (DTCG modes, Material / Apple semantic colours). Rituals' `color.json` already works this way and has dark values for all five accents. The spec measured contrast against `#121212`. Rituals' real dark surface is cocoa `#2B1810`, and on it the existing theme values beat the spec's proposals in four of five cases: | accent | current Rituals dark | spec proposal | |---|---|---| | sanctum | `#86B4FD` 8.03:1 | `#397FEF` 4.40:1 (fails AA) | | pilgrimage | `#CD91C4` 6.80:1 | `#D161C0` 4.98:1 | | federation | `#B5C1D7` 9.33:1 | `#9197AC` 5.82:1 | | trust | `#A78BFA` 6.22:1 | `#A275F0` 5.11:1 | | error | `#BE5656` **3.75:1 (fails AA)** | `#F87171` 6.12:1 | **So: keep the current values, and change only Rituals' dark `color.accent.error` to `#F87171`.** ### Severity: don't adopt the five-state proposal as written 1. **"Old" isn't a severity.** It describes data freshness. Grafana and Datadog show stale or missing data as a separate neutral state. 2. **It reuses the governance colours** `safety.allow/review/block` for operational health, giving one token two meanings. §4 of the spec warns against exactly that for the mode colours. 3. **In light mode the states only differ by hue.** fine, old, broken and very serious are all dark (8.7–10:1 on white, relative luminance 0.055–0.081), and very serious is *lighter* than broken. In greyscale or with red-green colour blindness they collapse. **Proposed instead:** the common four levels (Grafana alert states, PagerDuty) plus a neutral state for no data: | state | level | token | |---|---|---| | fine | ok | existing `accent.success` | | slow | warning | existing `accent.warning` | | broken | error | existing `accent.error` | | very serious | critical | **new** `accent.critical` | | old | stale / no data | **new** neutral (on the `neutral.warm-*` family) | Every state is shown with an icon and its name (spec §5 already asks for the name). Lightness has to step in order from ok to critical, so the scale reads without hue. ### Needs a decision first The baseline `success` / `warning` / `error` (`#12883E` / `#CD4D0B` / `#DC2626`) have **the same value in light and dark**: - On cocoa they reach only 3.72 / 3.76 / 3.50:1. - `warning` is 4.47:1 on white, just under AA. They need real dark values before the dashboards can build on them. That's a brand colour change, so @peterswimm signs off. ## Acceptance criteria, revised - [ ] Peter approves the four-plus-stale model and the baseline dark values. - [ ] Rituals dark `accent.error` → `#F87171`. - [ ] Add `accent.critical` and the stale neutral, light and dark, with lightness in order. `just check` stays green. - [ ] Update the spec to the current sources (`Brand/UDG/dtcg/color.json`, `Brand/UDG/products/<name>/dtcg/color.json`).

peterswimm commented 2026-10-20 15:09:24 +00:00

Owner

Copy link

Recommendation (2026-10-20). Needs my sign-off and Toilville leadership approval, because these are brand colour changes:

• Keep the current dark accents for sanctum, pilgrimage, federation and trust. They already pass AA on cocoa, and they beat the spec's proposals.
• Change the rituals dark accent.error from #BE5656 to #F87171. The current value is about 3.75:1 on cocoa, which fails AA (Brand/UDG/products/rituals/dtcg/color.json:615).
• Adopt four severity levels plus a stale neutral (new accent.critical and stale tokens), not the five-state set as written.
• Give the baseline success, warning and error real dark values.

Once this is approved, ville adds the DTCG entries and updates the spec's source paths (Brand/specs/spelwork/spelwork-dashboard-design-part1.md:133-136).

**Recommendation (2026-10-20). Needs my sign-off and Toilville leadership approval, because these are brand colour changes:** - **Keep** the current dark accents for sanctum, pilgrimage, federation and trust. They already pass AA on cocoa, and they beat the spec's proposals. - **Change** the rituals dark `accent.error` from `#BE5656` to `#F87171`. The current value is about 3.75:1 on cocoa, which fails AA (`Brand/UDG/products/rituals/dtcg/color.json:615`). - **Adopt four severity levels plus a stale neutral** (new `accent.critical` and stale tokens), not the five-state set as written. - **Give the baseline success, warning and error real dark values.** Once this is approved, ville adds the DTCG entries and updates the spec's source paths (`Brand/specs/spelwork/spelwork-dashboard-design-part1.md:133-136`).

peterswimm self-assigned this 2026-10-20 15:09:24 +00:00

peterswimm commented 2026-10-21 23:42:08 +00:00

Owner

Copy link

Approved (Peter, 2026-10-21), including Toilville leadership sign-off. The recommendation above is now decided:

• Keep the current dark accents for sanctum, pilgrimage, federation and trust.
• Change the rituals dark accent.error from #BE5656 to #F87171.
• Use four severity levels plus a stale neutral (new accent.critical and stale tokens).
• Give the baseline success, warning and error real dark values.

@ville, over to you: add the DTCG entries and update the spec's source paths (Brand/specs/spelwork/spelwork-dashboard-design-part1.md:133-136). Once they land, Rituals regenerates its tokens and checks dark-mode contrast in test/udg/contrast_test.dart.

**Approved (Peter, 2026-10-21), including Toilville leadership sign-off.** The recommendation above is now decided: - Keep the current dark accents for sanctum, pilgrimage, federation and trust. - Change the rituals dark `accent.error` from `#BE5656` to `#F87171`. - Use four severity levels plus a stale neutral (new `accent.critical` and stale tokens). - Give the baseline success, warning and error real dark values. @ville, over to you: add the DTCG entries and update the spec's source paths (`Brand/specs/spelwork/spelwork-dashboard-design-part1.md:133-136`). Once they land, Rituals regenerates its tokens and checks dark-mode contrast in `test/udg/contrast_test.dart`.

ville referenced this issue 2026-10-22 13:39:07 +00:00

docs(spelwork): Part 2 — sketches for the three §6 dashboards #224

ville referenced this issue from a commit 2026-10-22 14:01:18 +00:00

docs(spelwork): align dashboard sketches with #172 and #174

ville referenced this issue 2026-10-22 14:04:14 +00:00

SPELWork dashboards: sketch the three main dashboards (spec Part 1 §6) #171

ville referenced this issue from a commit 2026-10-23 12:50:33 +00:00

feat(tokens): four severity levels plus a stale state (#174)

ville referenced this issue 2026-10-23 12:51:07 +00:00

feat(tokens): four severity levels plus a stale state (#174) #225

peterswimm referenced this issue from a commit 2026-10-23 13:43:33 +00:00

Merge pull request 'feat(tokens): four severity levels plus a stale state (#174)' (#225) from feat/174-severity-tokens into main

ville referenced this issue 2026-10-23 20:24:12 +00:00

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

ville referenced this issue from a commit 2026-10-24 10:03:24 +00:00

docs(spelwork): colour-vision check of severity and stage colours (#173)

ville referenced this issue 2026-10-24 10:03:25 +00:00

docs(spelwork): colour-vision check of severity and stage colours (#173) #228

ville referenced this issue 2026-10-24 10:35:19 +00:00

SPELWork dashboards: colour-blind check of warning states and step colours (spec §1) #173

peterswimm referenced this issue 2026-10-27 23:06:24 +00:00

SPELWork tokens: the three questions Part 1 leaves open after #172/#173/#174 #234

peterswimm commented 2026-10-27 23:07:00 +00:00

Owner

Copy link

Closing — shipped in #225.

Against what was approved on 2026-10-21, including leadership sign-off:

• Four severity levels plus a stale state, as accent.success / accent.warning / accent.error / new accent.critical, plus new neutral.warm-stale.
• Rituals dark accent.error #BE5656 → #F87171, as decided.
• Dark accents for sanctum, pilgrimage, federation and trust kept.
• No separate *-on-dark token family — each accent keeps one token with a value per theme, which was the right call and is what §3 now documents.

§3 of Part 1 is now "Warning colors — four levels plus a stale state", and both of this issue's entries in the open-questions list are struck through. #230 later revised three of the light values for colour-vision separation under #173; that supersedes the values here and does not reopen the decision.

Carried to #234: whether Rituals and blocks should get accent.critical and neutral.warm-stale in their own color.json (§3, "Rituals and blocks").

**Closing — shipped in #225.** Against what was approved on 2026-10-21, including leadership sign-off: - Four severity levels plus a stale state, as `accent.success` / `accent.warning` / `accent.error` / new `accent.critical`, plus new `neutral.warm-stale`. - Rituals dark `accent.error` `#BE5656` → `#F87171`, as decided. - Dark accents for sanctum, pilgrimage, federation and trust kept. - No separate `*-on-dark` token family — each accent keeps one token with a value per theme, which was the right call and is what §3 now documents. §3 of Part 1 is now "Warning colors — four levels plus a stale state", and both of this issue's entries in the open-questions list are struck through. #230 later revised three of the light values for colour-vision separation under #173; that supersedes the values here and does not reopen the decision. Carried to #234: whether Rituals and `blocks` should get `accent.critical` and `neutral.warm-stale` in their own `color.json` (§3, "Rituals and blocks").

peterswimm closed this issue 2026-10-27 23:07:05 +00:00

Sign in to join this conversation.

No Branch/Tag specified

Branches Tags

main

archive/ds-bundle-snapshot-20261007

archive/design-system-superset-20260628

Labels

Clear labels   

build-dist

Ask the UDG build bot to run just build and commit generated files to this PR

  

priority

P1

Urgent — no working icon yet (custom art pending) or a shipping asset

  

priority

P2

High — has an accessible stand-in; bespoke art wanted

  

priority

P3

Medium — stage visual headers

  

priority

P4

Low — behavioral dimension family

  

bug

Something is not working

  

duplicate

This issue or pull request already exists

  

enhancement

New feature

  

help wanted

Need some help

  

invalid

Something is wrong

  

question

More information is needed

  

wontfix

This won't be fixed

No labels

build-dist

priority

P1

priority

P2

priority

P3

priority

P4

bug

duplicate

enhancement

help wanted

invalid

question

wontfix

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

ville

peterswimm

2 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

Toilville/toilville-design#174

No description provided.