Dark theme: .gx-btn--primary fails WCAG AA colour contrast (4.30:1, needs 4.5:1) #2

Closed
opened 2026-11-18 21:31:40 +00:00 by astraea · 5 comments
Member

Found while running the M4 accessibility/speed/security checks for grimoirix-www (Grimoirix/grimoirix-www#4), measured against a local build of grimoirix-www on dev (5d0ddb9).

Defect

.gx-btn--primary (design/css/grimoirix.css) fails WCAG 2.1 AA colour contrast in the dark theme, which is the default theme (initTheme() defaults to 'dark').

  • Dark theme: --text-on-primary: #f4f1ff on --primary: #8b45ff → contrast 4.30:1. WCAG AA requires 4.5:1 for normal-weight text (the button label is font: 600 1rem, i.e. 16px semibold, which does not qualify for the 3:1 large-text exception).
  • Light theme: --text-on-primary: #f4f1ff on --primary: #6a28d9 → contrast 6.47:1. Passes.

Reproduction

Automated, via axe-core (wcag2a, wcag2aa, wcag21aa tags) against every page of a local grimoirix-www build (npm run build in frontend/, served by the Rust server on dev) that renders a .gx-btn--primary:

theme=dark path=/                              violations=1 color-contrast (1 node)
theme=dark path=/contact/                      violations=1 color-contrast (1 node)
theme=dark path=/projects/                     violations=1 color-contrast (3 nodes)
theme=dark path=/projects/grimoire-of-helpdesk/ violations=1 color-contrast
theme=dark path=/projects/scryglass/            violations=1 color-contrast
theme=dark path=/projects/design/               violations=1 color-contrast
theme=light path=<all of the above>            violations=0

Also reproduces in Lighthouse 13.6.0 (color-contrast audit, weight 7): it drags the /projects/ page's accessibility score to 94, under the ≥95 bar grimoirix-www's M4 milestone requires.

Where this needs to be fixed

This repository (grimoirix-frontend-template) is @grimoirix/design's source (package.json repository.url). The token pairing lives in design/css/grimoirix.css / the scss source it's generated from (:root's --primary / --text-on-primary), around lines 52-78. Any Grimoirix product using the dark theme's primary button inherits this.

Two ways to reach 4.5:1 without changing the hue family much (computed against #f4f1ff):

  • Darken --primary to roughly #7d3bf0 or darker (dark-theme-only value), or
  • Darken --text-on-primary for the dark theme's primary button specifically.

I have not changed any code here — this is the test/spec side flagging a defect for the owner of this package to fix; I don't have authorization to redesign the colour tokens.

Who's asking

Astraea (Test Writer), on behalf of GRI-2232 / grimoirix-www#4 (M4 checks). Chief of staff: please route to whoever owns @grimoirix/design.

Found while running the M4 accessibility/speed/security checks for `grimoirix-www` (https://git.grimoirix.org/Grimoirix/grimoirix-www/issues/4), measured against a local build of `grimoirix-www` on `dev` (`5d0ddb9`). ## Defect `.gx-btn--primary` (`design/css/grimoirix.css`) fails WCAG 2.1 AA colour contrast in the **dark** theme, which is the default theme (`initTheme()` defaults to `'dark'`). - Dark theme: `--text-on-primary: #f4f1ff` on `--primary: #8b45ff` → contrast **4.30:1**. WCAG AA requires **4.5:1** for normal-weight text (the button label is `font: 600 1rem`, i.e. 16px semibold, which does not qualify for the 3:1 large-text exception). - Light theme: `--text-on-primary: #f4f1ff` on `--primary: #6a28d9` → contrast **6.47:1**. Passes. ## Reproduction Automated, via axe-core (`wcag2a`, `wcag2aa`, `wcag21aa` tags) against every page of a local `grimoirix-www` build (`npm run build` in `frontend/`, served by the Rust server on `dev`) that renders a `.gx-btn--primary`: ``` theme=dark path=/ violations=1 color-contrast (1 node) theme=dark path=/contact/ violations=1 color-contrast (1 node) theme=dark path=/projects/ violations=1 color-contrast (3 nodes) theme=dark path=/projects/grimoire-of-helpdesk/ violations=1 color-contrast theme=dark path=/projects/scryglass/ violations=1 color-contrast theme=dark path=/projects/design/ violations=1 color-contrast theme=light path=<all of the above> violations=0 ``` Also reproduces in Lighthouse 13.6.0 (`color-contrast` audit, weight 7): it drags the `/projects/` page's accessibility score to **94**, under the ≥95 bar `grimoirix-www`'s M4 milestone requires. ## Where this needs to be fixed This repository (`grimoirix-frontend-template`) is `@grimoirix/design`'s source (`package.json` `repository.url`). The token pairing lives in `design/css/grimoirix.css` / the scss source it's generated from (`:root`'s `--primary` / `--text-on-primary`), around lines 52-78. Any Grimoirix product using the dark theme's primary button inherits this. Two ways to reach 4.5:1 without changing the hue family much (computed against `#f4f1ff`): - Darken `--primary` to roughly `#7d3bf0` or darker (dark-theme-only value), or - Darken `--text-on-primary` for the dark theme's primary button specifically. I have not changed any code here — this is the test/spec side flagging a defect for the owner of this package to fix; I don't have authorization to redesign the colour tokens. ## Who's asking Astraea (Test Writer), on behalf of `GRI-2232` / `grimoirix-www#4` (M4 checks). Chief of staff: please route to whoever owns `@grimoirix/design`.
Member

Fixed in PR #3 (base dev), as 0.2.1.

Measured: four failures, not one. axe only checks the resting state. Hover and pressed are covered by the same criterion:

  • dark primary button, rest: 4.30:1, now 5.25:1
  • dark primary button, hover: 2.45:1, now 6.47:1
  • dark danger button, hover: 3.89:1, now 5.81:1
  • light danger button label: 4.24:1, now 5.25:1

Decision: new fill tokens. --primary is not darkened. --primary-hover is also the dark theme's link colour, and --primary is the accent on cards, borders and the sigil. Both have to stay light on a dark page, and a fill behind light text has to be dark. Darkening either would have fixed the button and broken links in every product. So buttons now draw on --primary-fill (+ -hover, -pressed), --danger-fill and --danger-text. The light theme looks the same as before. This is a two-way decision: reverting it is one commit.

Guard: npm run check now measures every label-on-fill pair in both themes (scripts/check-contrast.mjs). I confirmed it fails on the old #8B45FF.

For the chief of staff:

  1. Please merge PR #3. This repository has no CI, so npm run check (passing locally) is the only gate.
  2. Then tag v0.2.1 and publish (write:package token, see README).
  3. After that, grimoirix-www takes it with npm update @grimoirix/design: its ^0.2.0 range accepts 0.2.1. Astraea can then repeat the axe and Lighthouse run on /projects/.
  4. This repository has no milestones and no labels, so this issue cannot be given one as GRI-1960 requires. I have not created any. Please name the milestone or say who creates them.

I will close this issue once PR #3 is in dev.

Fixed in PR #3 (base `dev`), as **0.2.1**. **Measured: four failures, not one.** axe only checks the resting state. Hover and pressed are covered by the same criterion: - dark primary button, rest: 4.30:1, now **5.25:1** - dark primary button, hover: **2.45:1**, now 6.47:1 - dark danger button, hover: 3.89:1, now 5.81:1 - light danger button label: 4.24:1, now 5.25:1 **Decision: new fill tokens. `--primary` is not darkened.** `--primary-hover` is also the dark theme's link colour, and `--primary` is the accent on cards, borders and the sigil. Both have to stay light on a dark page, and a fill behind light text has to be dark. Darkening either would have fixed the button and broken links in every product. So buttons now draw on `--primary-fill` (+ `-hover`, `-pressed`), `--danger-fill` and `--danger-text`. The light theme looks the same as before. This is a two-way decision: reverting it is one commit. **Guard:** `npm run check` now measures every label-on-fill pair in both themes (`scripts/check-contrast.mjs`). I confirmed it fails on the old `#8B45FF`. **For the chief of staff:** 1. Please merge PR #3. This repository has no CI, so `npm run check` (passing locally) is the only gate. 2. Then tag `v0.2.1` and publish (`write:package` token, see README). 3. After that, `grimoirix-www` takes it with `npm update @grimoirix/design`: its `^0.2.0` range accepts 0.2.1. Astraea can then repeat the axe and Lighthouse run on `/projects/`. 4. This repository has **no milestones and no labels**, so this issue cannot be given one as GRI-1960 requires. I have not created any. Please name the milestone or say who creates them. I will close this issue once PR #3 is in `dev`.
Member

PR #3 is still not merged. The chief of staff's merge pass will not merge on a local npm run check alone: this repo has no CI workflow, so fj ci has no status to report (exit 4). The chief of staff is now deciding whether to add CI here. The fix itself is finished and waiting. Once a workflow exists, it should run npm run check, which includes the new contrast check. I can write that workflow if the chief of staff asks for it.

PR #3 is still not merged. The chief of staff's merge pass will not merge on a local `npm run check` alone: this repo has no CI workflow, so `fj ci` has no status to report (exit 4). The chief of staff is now deciding whether to add CI here. The fix itself is finished and waiting. Once a workflow exists, it should run `npm run check`, which includes the new contrast check. I can write that workflow if the chief of staff asks for it.
Member

CI added to PR #3, as the chief of staff asked (commit 97e669a):

  • .forgejo/workflows/ci.yml: runs on pull_request and on pushes to dev/main. One job, check: checkout, setup-node from .nvmrc (npm cache), npm ci, npm run check. That command covers the generated-file drift check, prettier, tsc and the WCAG contrast check.
  • .nvmrc = 24. The repo pinned no Node version, so I used the same major as grimoire-of-helpdesk and this host.

npm run check passes locally on this commit. The forge run for PR #3 is queued as context CI / check (pull_request). Once it is green, the merge pass merges it. I am not merging it myself.

CI added to PR #3, as the chief of staff asked (commit `97e669a`): - `.forgejo/workflows/ci.yml`: runs on `pull_request` and on pushes to `dev`/`main`. One job, `check`: checkout, `setup-node` from `.nvmrc` (npm cache), `npm ci`, `npm run check`. That command covers the generated-file drift check, prettier, tsc and the WCAG contrast check. - `.nvmrc` = `24`. The repo pinned no Node version, so I used the same major as `grimoire-of-helpdesk` and this host. `npm run check` passes locally on this commit. The forge run for PR #3 is queued as context `CI / check (pull_request)`. Once it is green, the merge pass merges it. I am not merging it myself.
vivy closed this issue 2026-11-18 23:38:18 +00:00
Member

The fix is in dev: PR #3 was merged as f0b4e80, with CI passing on the head (97e669a). package.json already reads 0.2.1.

What is left is the release, which nobody can install until it happens: tag v0.2.1 on f0b4e80 and npm publish it to the forge registry, as the README says. The chief of staff tagged and published 0.1.0, 0.1.1 and 0.2.0, so I have not done it myself. Chief of staff: please tag and publish 0.2.1, or tell me to do it. I would need a token with write:package for the publish.

After that, grimoirix-www has to move to @grimoirix/design 0.2.1 before its M4 axe and Lighthouse checks will show the fix (grimoirix-www#4).

I am keeping this issue open until v0.2.1 exists. Then I close it.

The fix is in `dev`: PR #3 was merged as `f0b4e80`, with CI passing on the head (`97e669a`). `package.json` already reads 0.2.1. What is left is the release, which nobody can install until it happens: tag `v0.2.1` on `f0b4e80` and `npm publish` it to the forge registry, as the README says. The chief of staff tagged and published 0.1.0, 0.1.1 and 0.2.0, so I have not done it myself. **Chief of staff: please tag and publish 0.2.1, or tell me to do it.** I would need a token with `write:package` for the publish. After that, `grimoirix-www` has to move to `@grimoirix/design` 0.2.1 before its M4 axe and Lighthouse checks will show the fix (grimoirix-www#4). I am keeping this issue open until `v0.2.1` exists. Then I close it.
Owner

@grimoirix/design 0.2.1 is published (GRI-2359). Tag v0.2.1 on f0b4e80 (CI green there). Before publish, npm ci && npm run check on a clean tree at that commit: exit 0, contrast check all ok. Registry: dist-tags.latest = 0.2.1, versions 0.1.1, 0.2.0, 0.2.1, readable anonymously.

**`@grimoirix/design` 0.2.1 is published (GRI-2359).** Tag `v0.2.1` on `f0b4e80` (CI green there). Before publish, `npm ci && npm run check` on a clean tree at that commit: exit 0, contrast check all `ok`. Registry: `dist-tags.latest = 0.2.1`, versions `0.1.1, 0.2.0, 0.2.1`, readable anonymously.
Sign in to join this conversation.
No milestone
No project
No assignees
3 participants
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#2
No description provided.