GRI-2234: 0.2.1 - button labels meet WCAG AA contrast in both themes #3

Merged
vivy merged 2 commits from fix/GRI-2234-dark-primary-contrast into dev 2026-11-18 23:38:18 +00:00
Member

Fixes #2. Board: GRI-2234. Reported by Astraea for grimoirix-www#4 (M4 accessibility checks).

What was wrong

The issue reports one pair. Measuring every label-on-fill pair the components draw found four failures against WCAG 2.1 AA (4.5:1, normal text):

Pair Before After
dark .gx-btn--primary, rest 4.30:1 5.25:1 (#7B2FF7, arcane purple)
dark .gx-btn--primary:hover 2.45:1 6.47:1 (#6A28D9)
dark .gx-btn--danger:hover 3.89:1 5.81:1 (#B81C32)
light .gx-btn--danger label on page 4.24:1 5.25:1 (#B81C32)

axe only reported the first one because it measures the resting state. Hover is covered by the same WCAG criterion.

Why new tokens and not a new --primary

In dark mode, --primary-hover is also the link colour (a { color: var(--primary-hover) }, 7.30:1 on the page). --primary is also used for card accents, nav and toggle borders, and the sigil. A fill behind light text has to be dark, and a link or accent on a dark page has to be light. One token cannot be both. Darkening --primary/--primary-hover would have fixed the button and broken links and accents in every product.

So the buttons now draw on role tokens: --primary-fill (+ -hover, -pressed), --danger-fill and --danger-text. The accent tokens keep their values. The light theme looks exactly as before: its fills equal its old values. The only visible change is in the dark theme: primary button, its hover, and the danger button's hover.

Guard

npm run check now ends with scripts/check-contrast.mjs. It reads the generated grimoirix.css and measures 12 pairs per theme: every button state, body and muted text, and links. Exit codes: 0 = all pass, 1 = a pair fails, 2 = a token is missing, which means nothing was measured, so it is not a pass. I checked that it catches the defect: restoring #8B45FF makes it exit 1 with FAIL dark 4.30:1.

Version

0.2.1, not 0.3.0. The new tokens exist only to fix a bug. grimoirix-www pins ^0.2.0, and for a 0.x version npm reads that range as <0.3.0. A 0.2.1 reaches it through npm update @grimoirix/design with no range edit.

One behaviour change for consumers: a project that set $dark-overrides: (primary: …) to recolour its buttons now has to override primary-fill instead. No current consumer does this (grimoirix-www has no overrides).

After merge

Tag v0.2.1 and publish (needs a write:package token, see README). Then grimoirix-www takes it with npm update @grimoirix/design, and Astraea's axe and Lighthouse run on /projects/ can be repeated.

Checks

npm run check passes: build is reproducible, prettier and tsc are clean, contrast exits 0. This repository has no CI, so this local run is the only gate.

Fixes #2. Board: GRI-2234. Reported by Astraea for `grimoirix-www#4` (M4 accessibility checks). ## What was wrong The issue reports one pair. Measuring every label-on-fill pair the components draw found four failures against WCAG 2.1 AA (4.5:1, normal text): | Pair | Before | After | | --- | --- | --- | | dark `.gx-btn--primary`, rest | 4.30:1 | **5.25:1** (`#7B2FF7`, arcane purple) | | dark `.gx-btn--primary:hover` | **2.45:1** | 6.47:1 (`#6A28D9`) | | dark `.gx-btn--danger:hover` | 3.89:1 | 5.81:1 (`#B81C32`) | | light `.gx-btn--danger` label on page | 4.24:1 | 5.25:1 (`#B81C32`) | axe only reported the first one because it measures the resting state. Hover is covered by the same WCAG criterion. ## Why new tokens and not a new `--primary` In dark mode, `--primary-hover` is also the **link colour** (`a { color: var(--primary-hover) }`, 7.30:1 on the page). `--primary` is also used for card accents, nav and toggle borders, and the sigil. A fill behind light text has to be dark, and a link or accent on a dark page has to be light. One token cannot be both. Darkening `--primary`/`--primary-hover` would have fixed the button and broken links and accents in every product. So the buttons now draw on role tokens: `--primary-fill` (+ `-hover`, `-pressed`), `--danger-fill` and `--danger-text`. The accent tokens keep their values. **The light theme looks exactly as before**: its fills equal its old values. The only visible change is in the dark theme: primary button, its hover, and the danger button's hover. ## Guard `npm run check` now ends with `scripts/check-contrast.mjs`. It reads the generated `grimoirix.css` and measures 12 pairs per theme: every button state, body and muted text, and links. Exit codes: 0 = all pass, 1 = a pair fails, 2 = a token is missing, which means nothing was measured, so it is not a pass. I checked that it catches the defect: restoring `#8B45FF` makes it exit 1 with `FAIL dark 4.30:1`. ## Version **0.2.1**, not 0.3.0. The new tokens exist only to fix a bug. `grimoirix-www` pins `^0.2.0`, and for a 0.x version npm reads that range as `<0.3.0`. A 0.2.1 reaches it through `npm update @grimoirix/design` with no range edit. One behaviour change for consumers: a project that set `$dark-overrides: (primary: …)` to recolour its buttons now has to override `primary-fill` instead. No current consumer does this (`grimoirix-www` has no overrides). ## After merge Tag `v0.2.1` and publish (needs a `write:package` token, see README). Then `grimoirix-www` takes it with `npm update @grimoirix/design`, and Astraea's axe and Lighthouse run on `/projects/` can be repeated. ## Checks `npm run check` passes: build is reproducible, prettier and tsc are clean, contrast exits 0. This repository has no CI, so this local run is the only gate.
Dark primary button was 4.30:1 at rest and 2.45:1 on hover; dark danger
hover 3.89:1; light danger label 4.24:1. Buttons now draw on fill tokens
(--primary-fill, -hover, -pressed, --danger-fill, --danger-text) kept apart
from --primary/--primary-hover, which stay accents and link colours.
npm run check measures every text-on-fill pair (scripts/check-contrast.mjs).
GRI-2234: CI workflow running npm run check on Node from .nvmrc
All checks were successful
CI / check (pull_request) Successful in 45s
97e669aab2
vivy merged commit f0b4e8023c into dev 2026-11-18 23:38:18 +00:00
vivy deleted branch fix/GRI-2234-dark-primary-contrast 2026-11-18 23:38:18 +00:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
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
Grimoirix/grimoirix-frontend-template!3
No description provided.