theme: the dark palette's measured set omits surface-hover and the tint washes, so adopting it fails axe at 12px

[krisarmstrong]

Raised from seed#2693, where adopting the canonical theme turned Storybook interactions and accessibility red with 37 axe color-contrast violations. The palette's header records its dark pairs as "text 4.5:1 or better, UI edges 3:1 or better", and each token's comment gives its ratio on base and on raised. Two surfaces products actually use are not in that set:

pairing	measured	needed
--color-text-muted #91896e on --color-surface-hover #312e25	3.88:1	4.5:1
bg-status-success/20 wash under text-status-success (#3cb46e), 12px	4.37:1	4.5:1
bg-cat-1/20 wash under text-cat-1 (#60a5fa), 12px	4.49:1	4.5:1

The hover surface is where list rows, chips and command-palette items put their small text; the bg-<hue>/NN wash under same-hue text is the fleet's standard status pill. Both are in every product's markup, so all four repos will meet this as they adopt (UI-SEED-7 / UI-STEM-7 / UI-NIAC-9 / UI-TRL-8).

Seed fixed it in its own markup (same-hue pills to /15 — 4.80 and 4.95:1 — and the affected chips from muted to secondary, 5.97:1), because a product-local edit to msn-shared.css cannot pass the hash gate. That works, but it is the same fix three more times unless the canonical side decides it:

1. extend the measured set to surface-hover (and any other surface the component layer paints), adjusting --color-text-muted in dark until it clears 4.5:1 there; and
2. state the supported tint recipe — either the canonical component layer owns a .status-pill with a wash that clears 4.5:1 at 12px, or the tokens document the alpha that does (/15, not /20, for the current hues).

Method: axe via the Storybook a11y gate, ratios recomputed with the WCAG relative-luminance formula against the composited background.

[krisarmstrong]

Stem's adoption run (stem-20260916-1309, PR MustardSeedNetworks/stem#1297) confirms the text-muted / surface-hover pair and adds two things worth having before the fix lands.

It is a regression, not a pre-existing shortfall. In stem the same three sites measured 6.40:1 before adoption (old cold-steel dark: #93a8b2 on #142430) and 3.88:1 after. Any adopter that treats it as inherited debt will under-prioritise it.

Storybook axe does not necessarily catch it. Stem runs the a11y addon blocking in real Chromium (preview.tsx, test: 'error') and it was green 39/111 with the bad pair present, because stories render on the addon's own #ffffff / #1a1a2e backgrounds, never on surface-hover. Seed's 10 failures came from stories that happen to paint the hover surface. So a repo passing this gate is not evidence its palette is clean — the sites have to be found by grepping the class pairs.

Live exposure across the fleet at origin/main, from a sweep of every .tsx (excluding pairings that lift the text on hover, which never render the bad combination):

repo	sites
seed	help/HelpDrawer.tsx:137, profiles/ProfileManagement.tsx:181, settings/SettingsDrawer.tsx:531
niac-go	components/ProtocolTree.tsx:89,97
stem	SettingsDrawer.tsx:259,274, HelpDrawer.tsx:294 — substituted in stem#1297
trellis	none

The proposed #9c957d (hover 4.53) clears all of them without a component edit, so seed's and stem's substitutions become belt-and-braces rather than the fix.

Each adopted repo now carries a hash re-copy row for after this lands (stem UI-STEM-17, niac UI-NIAC-18, trellis UI-TRL-12, seed UI-SEED-17) — changing canonical invalidates the sha256 all four pin, so check 9 goes red in every repo the moment this merges.

[krisarmstrong]

Clause 1 is in #76 — but the audit that fixes it found the problem is wider than this issue recorded, and clause 2 has no answer in alpha.

Clause 1: eleven tokens, not two. Enumerating every text-token × surface-token pair in both modes (rather than the two pairs reported) turns up 16 failing pairs across 11 tokens. The two here are in it; the rest were invisible for the same reason — the measured set was base and raised. Worst case is --color-surface-border at 2.63:1 on hover in dark, the token #69 had just darkened for its 3:1. Fixed in #76, each by the smallest same-hue lightness step, plus scripts/check-theme-contrast.py so the set cannot quietly narrow again. New canonical sha256 ee86c3d70b04.

Clause 2: no alpha works. The recipe is wrong, not the number.

Same-hue text on its own wash, worst of base/raised/hover, after clause 1's token fixes:

alpha	light (success/warning/error/info)	dark
/20	3.93 · 3.90 · 3.81 · 4.06	3.71 · 3.67 · 3.65 · 3.70
/15	4.21 · 4.16 · 4.12 · 4.37	4.05 · 4.00 · 4.01 · 4.03
/10	4.49 · 4.45 · 4.43 · 4.70	4.42 · 4.40 · 4.35 · 4.40
/08	4.63 · 4.58 · 4.53 · 4.84	4.53 · 4.54 · 4.50 · 4.52

Only /08 clears 4.5, and a wash that faint is not a pill. The cause is structural: the wash pulls the ground toward the text, so every increase in alpha costs contrast, and the hues sit only ~4.6–5.2:1 on a plain surface to begin with. That also means this issue's note that seed's /15 gives 4.80 and 4.95:1 does not reproduce — those look like base/raised-only readings, the same blind spot as clause 1.

Two options that do work, both needing a markup change in four repos:

• (A) canonical .status-pill + per-hue modifier with a fixed opaque background. Maximally measurable — the gate can check the exact declared pair.
• (B) per-hue "on-wash" text tokens (--color-status-success-strong etc., darker in light, lighter in dark). Four new tokens; a pill swaps text-status-x for text-status-x-strong and keeps its wash.

Recommending (B): it leaves the approved status hues untouched for icons and plain text, adds four values the contrast gate can measure directly, and the migration is one class name inside pills rather than a new component every product must adopt. Raised to the owner; not decided here.

Third, found on the way: six of the eight published product hues fail as text.

Product	Light	worst light	Dark	worst dark
seed	#2f7d3a	3.97 sunken	#34b244	4.91 hover
stem	#1565c0	4.47 sunken	#2d81e1	3.45 hover
niac	#6a3fa8	5.66 sunken	#9569d3	3.38 hover
trellis	#b94689	3.80 sunken	#cd5199	3.38 hover

ui/theme/README.md claimed "each dark value is at least 4.5:1 on the dark page ground", which is true and beside the point — the page ground is the easiest surface, and the same hue on a hovered row is a full point worse. Set C is owner-approved and a brand anchor is not something a driver re-picks, so #76 records the measurements and changes nothing. check-theme-contrast.py --product ui/src/theme/product-<name>.css measures a repo's own file.

Method for all of the above: WCAG 2.2 relative luminance, alpha composited source-over against its ground, scripts/check-theme-contrast.py in #76.

[krisarmstrong]

Evidence that clauses 1 and 2 are entangled, from preparing seed's adoption (UI-SEED-17).

Seed's product-seed.css still carries dark --color-brand-primary: #6cc472, where set C publishes #34b244. Moving it to the published value fails Storybook axe with 10 color-contrast violations:

Element has insufficient color contrast of 4.23
  (foreground #34b244, background #263e22, 9.0pt/12px, normal)
  Expected contrast ratio of 4.5:1

#263e22 is not a surface token — it is bg-brand-primary/15 composited over the dark card. So the brand pill is the same recipe as the status pill, and the published set C value is unusable as its text under that recipe, while the stale #6cc472 passes because it is lighter.

Two consequences:

1. Correcting a product hue to set C is blocked on the tint-recipe decision, not merely on the hue being right. seed's adoption therefore lands the canonical re-copy only, and leaves the hue alone with this recorded.
2. It is more evidence for the on-wash text token over raising the hues: a hue chosen to pass its own wash is necessarily lighter/paler than the brand anchor, which is how #6cc472 came to exist in the first place. An -on-wash token lets the pill be legible without the brand drifting pale.

Measured against ee86c3d70b04 (#76), 431/431 Storybook tests otherwise green on seed with that file.