Files
Homelab-manager/docs/ACCESSIBILITY.md
T
bobbanandClaude Sonnet 5.5 12e9fee7af Accessibility sweep: colours, links, targets and names
An axe-core check of 37 pages in both themes found and fixed low-contrast text
in the status colours (light) and tabs, pills and the info alert (dark),
in-sentence links with no underline, link targets under 24 px, selects with no
name and map nodes whose name did not start with their text. docs/ACCESSIBILITY.md
says what was found and how to run the check again.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-10 21:52:00 +01:00

50 lines
4.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Accessibility
The app is checked against **WCAG 2.2 level AA** with [axe-core](https://github.com/dequelabs/axe-core), the standard automated checker, in both themes. This page says what was found, what was done and how to run the same check again.
## Where it stands
A sweep of 37 pages (the dashboard, alerts and their history, servers and a server's page, every menu page that has data, the settings pages and the new pages) in the **light and the dark theme**, with the rules for WCAG 2 A and AA, 2.1 A and AA, 2.2 AA and axe's best practices, ends with **no violations**. Keyboard focus shows a 2 px ring on every control (one rule for them all), the skip link and the main landmark are there, and no page uses a positive tab order.
What an automated check cannot judge is not covered by it: whether a label says the right thing, whether the reading order makes sense to a person, or how a page works with a particular screen reader. Those were looked at by hand on the pages that changed, not on every page.
## What the sweep found, and what was done
| Found | Where | Done |
|---|---|---|
| Colour contrast too low (1.9–4.3:1) on **green, yellow, red and blue text and badges** on the light theme | the status badges and figures on most pages | The text takes a darker shade of the same colour on the light theme only (green `#17692a`, yellow `#8a5600`, orange `#a14d00`, red `#b32d2d`, blue `#0558a8`, grey on a grey badge `#5b6372`): at least 4.5:1 on white and on the badge's tint. The dark theme is unchanged |
| Contrast 2.7–3.7:1 for **tabs and pills that are not chosen**, the **chosen pill**, the **switch button that is on**, **outlined primary buttons** and the **info alert** on the dark theme | the view tabs, Cards/Table, the names lists, Settings | Lighter shades on the dark theme (`#9ca3af`, `#5aa9ff`, `#7cc0f7`), at least 4.5:1 on their backgrounds; the count in a pill is no longer faded |
| **Links told apart by colour alone** in a sentence (1.4.1) | notes and intros all over | A link inside a sentence is underlined |
| **Link targets** under 24 px tall (2.5.8) | a link that is a whole line (the dashboard's list, a table's *Timeline*) | Such a link has padding to at least 24 px |
| **Selects with no name** | the severity and kind filters on Alerts, the status filter on Secrets, each user's role on Users | Each has an `aria-label` (a role's names the user) |
| **Label in name** (2.5.3) | the nodes on the Map | A node is named by what is written on it first, then what it is and how it is |
All of this is in the *Accessibility* part at the end of `web/src/styles.css` and in those pages; `server/test/accessibility.test.ts` checks that the shades are the ones used, that each reads (the contrast is computed), and that the labels are there.
## Running the check again
The sweep is run in the browser: it needs nothing installed in the project.
1. Start the app (or a scratch copy with some data) and sign in.
2. Get `axe.min.js` (`npm install axe-core` in any folder, then `node_modules/axe-core/axe.min.js`) and serve it from the app's built folder (`web/dist/`, which is not committed), or paste it into the browser's console.
3. In the console, on a page of the app:
```js
await new Promise((ok) => { const s = document.createElement("script"); s.src = "/axe.min.js"; s.onload = ok; document.head.appendChild(s); });
async function scan(routes, theme) {
document.documentElement.setAttribute("data-bs-theme", theme);
const out = [];
for (const url of routes) {
history.pushState({}, "", url); window.dispatchEvent(new PopStateEvent("popstate"));
await new Promise((ok) => setTimeout(ok, 1500));
const r = await axe.run(document, { runOnly: { type: "tag", values: ["wcag2a", "wcag2aa", "wcag21a", "wcag21aa", "wcag22aa", "best-practice"] }, resultTypes: ["violations"] });
out.push([url, r.violations.map((v) => `${v.id} (${v.nodes.length}) ${v.nodes[0].target.join(" ")}`)]);
}
return out.filter(([, v]) => v.length);
}
await scan(["/", "/alerts", "/servers", "/integrations"], "dark"); // empty when there is nothing to fix
await scan(["/", "/alerts", "/servers", "/integrations"], "light");
```
Do a handful of pages at a time (each takes a second or two), and both themes: the light and the dark theme fail in different places. Check a page again after changing a colour, since a new shade can fix one background and break another.