diff --git a/README.md b/README.md index 60b24f5..e32fb12 100644 --- a/README.md +++ b/README.md @@ -952,6 +952,8 @@ switched by `?view=`, so a section can be linked to: an alert about a failing se **The status strip.** Under a server's name, on every section of its page, a row of figures says how it is at a glance: **Status** (online, with when it last reported — or *offline*, with when it did, and a note when Proxmox says the guest is still running, so a stopped agent is not read as a dead machine; for a server with no agent report, what Proxmox says, or that nothing has reported), **Maintenance** (only while a window on this server is on, with when it ends and why), **Alerts** (how many are open about this server and how bad — what a maintenance window, a snooze or a closing has put aside is not counted, but said — and a link to the Alerts page), **Updates** (what is waiting, how many of them security fixes, whether a reboot is needed), **Disk** (the fullest, against its own limit: green, yellow within ten points of it, red at it; a mount with its own limit is judged by that, and an ignored mount is left out), **CPU · memory** and **how long it has run** (for a guest Proxmox reads, or from an agent of version 8 on Linux, 7 on Windows, which say it in every report; left out while the server is offline, since it is then no longer how long it has been up). A figure nothing is known for is left out or says so — it is never filled in. It uses what the page already has plus the alerts and the maintenance windows, read again whenever the page is (the *Refresh* button). Everyone signed in sees it. +**Accessibility.** The main pages were checked against WCAG 2.2 AA with axe-core in both themes and now have no violations: text in the status colours is a shade that reads on the light theme, the tabs, pills, switch buttons and info alerts read on the dark one, a link in a sentence is underlined, a link that is a whole line is at least 24 px tall, the controls that had no name have one, and the map’s nodes are named by what is written on them. What was found, what was done and how to run the check again are in docs/ACCESSIBILITY.md. + **Brand colours and logos.** Every kind of integration and DNS provider has its brand's colour and, where the open icon set [Simple Icons](https://simpleicons.org) (CC0) has one, its logo — Proxmox, Synology, Tailscale, Gitea, Jellyfin, Immich, Nextcloud, Grafana, Prometheus, Home Assistant, Sonarr, Radarr, qBittorrent, Hetzner, Cloudflare, Pi-hole and more. The kind **tags** on the Integrations page (cards and table), the Servers page and the DNS page are in that colour with the logo, made readable on the light and the dark theme alike (the lightness is held where the text reads, the hue kept; every tag is at least 4.9:1 on dark and 5.2:1 on light); the dashboard's integration cards have the logo beside their title; the kind picker has it on each choice; and **the menu** has a small icon before each page in its groups — the logo for an integration's page, the page's own icon for the rest — which **Settings → Display → Menu → Show an icon before each page** switches off for this browser. A few kinds have no open logo (NetBox, Prowlarr, Lidarr, Readarr, SABnzbd, Technitium, osTicket, phpIPAM, Fragnet, Dockhand, Semaphore, UPS): they keep their generic icon and an approximate colour. **Settings → Display → Badge colours** shows each tag as it looks now, lets you choose another colour for any of them, and **Use the brand's** goes back. Logos and names belong to their owners and are used only to tell the systems apart. **Shorter page introductions.** The few lines under a page’s title that say what the page is are folded to two lines when they are longer than that, with **Show more** under them, so the page’s own content starts higher up. What you choose is remembered for that page in this browser; a short one is shown as it is, a link inside the folded part opens it when you tab to it, and a printout shows all of it. diff --git a/docs/ACCESSIBILITY.md b/docs/ACCESSIBILITY.md new file mode 100644 index 0000000..eeed046 --- /dev/null +++ b/docs/ACCESSIBILITY.md @@ -0,0 +1,49 @@ +# 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. diff --git a/server/test/accessibility.test.ts b/server/test/accessibility.test.ts new file mode 100644 index 0000000..d52fa3f --- /dev/null +++ b/server/test/accessibility.test.ts @@ -0,0 +1,99 @@ +/** + * What an axe-core sweep of the main pages (both themes) found and what was done about it, kept from drifting: the shades chosen for text on each background really do read (WCAG AA, 4.5:1), they are + * the ones the style sheet uses, and the controls that had no name have one. + * + * Run with: npm test --workspace server + */ +import { test, describe } from "node:test"; +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { join } from "node:path"; + +const web = (...parts: string[]) => readFileSync(join(import.meta.dirname, "..", "..", "web", "src", ...parts), "utf8"); + +const channel = (v: number) => { + const c = v / 255; + return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4; +}; +const luminance = (hex: string) => { + const n = parseInt(hex.replace("#", ""), 16); + return 0.2126 * channel((n >> 16) & 255) + 0.7152 * channel((n >> 8) & 255) + 0.0722 * channel(n & 255); +}; +/** WCAG contrast ratio of two #rrggbb colours. */ +const contrast = (a: string, b: string) => { + const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x); + return (hi + 0.05) / (lo + 0.05); +}; +/** The colour of a tint (a colour at some strength over white or the dark surface), for the backgrounds text sits on. */ +const over = (hex: string, alpha: number, base: string) => { + const f = (h: string) => [(parseInt(h.slice(1), 16) >> 16) & 255, (parseInt(h.slice(1), 16) >> 8) & 255, parseInt(h.slice(1), 16) & 255]; + const [a, b] = [f(hex), f(base)]; + return `#${a.map((v, i) => Math.round(v * alpha + b[i] * (1 - alpha)).toString(16).padStart(2, "0")).join("")}`; +}; + +const css = web("styles.css"); +const WHITE = "#ffffff"; +const DARK_PAGE = "#111827"; +const DARK_CARD = "#1f2937"; +const DARK_PILL = "#232e3e"; + +describe("the shades the style sheet uses read on the surfaces they are used on", () => { + test("light theme: text colours, on white and on their own tint (the badge), at least 4.5:1", () => { + const shades: [string, string, string][] = [ + ["green", "#17692a", "#2fb344"], + ["yellow", "#8a5600", "#f59f00"], + ["orange", "#a14d00", "#f76707"], + ["red", "#b32d2d", "#d63939"], + ["blue", "#0558a8", "#066fd1"], + ]; + for (const [name, shade, tabler] of shades) { + assert.ok(css.includes(shade), `${name}'s shade ${shade} is in the style sheet`); + assert.ok(contrast(shade, WHITE) >= 4.5, `${name} on white: ${contrast(shade, WHITE).toFixed(2)}`); + assert.ok(contrast(shade, over(tabler, 0.1, WHITE)) >= 4.5, `${name} on its tint: ${contrast(shade, over(tabler, 0.1, WHITE)).toFixed(2)}`); + } + assert.ok(css.includes("#5b6372") && contrast("#5b6372", "#f0f1f2") >= 4.5, "grey text on the grey badge"); + }); + + test("dark theme: the tabs and pills that are not chosen, the chosen pill, the switch button and the info alert, at least 4.5:1", () => { + for (const [what, fg, bg] of [ + ["inactive tab", "#9ca3af", DARK_PAGE], + ["inactive pill", "#9ca3af", DARK_CARD], + ["chosen pill, outlined primary button", "#5aa9ff", DARK_PILL], + ["the switch button that is on", "#5aa9ff", "#1e2c3d"], + ["the info alert", "#7cc0f7", "#223245"], + ] as const) { + assert.ok(css.includes(fg), `${what}: ${fg} is in the style sheet`); + assert.ok(contrast(fg, bg) >= 4.5, `${what}: ${contrast(fg, bg).toFixed(2)}`); + } + }); + + test("the light theme's chosen pill and info alert take the dark blue", () => { + assert.ok(contrast("#0558a8", "#f0f7fd") >= 4.5, "the info alert's tint"); + assert.match(css, /:root:not\(\[data-bs-theme="dark"\]\) \.alert-info\s*\{\s*color:\s*#0558a8/); + assert.match(css, /:root:not\(\[data-bs-theme="dark"\]\) :is\(\.text-primary, \.nav-pills \.nav-link\.active\)\s*\{\s*color:\s*#0558a8/); + }); +}); + +describe("links, targets and names", () => { + test("a link in the middle of a sentence is underlined, and one that is a whole line is at least 24 px tall", () => { + assert.match(css, /:is\(p, li, \.small, \.text-secondary, \.form-hint, \.page-intro\) a:not\([^)]*\.nav-link[^)]*\)\s*\{\s*text-decoration:\s*underline/); + assert.match(css, /:is\(li, \.small\) > a:only-child:not\([^)]*\)\s*\{\s*display:\s*inline-block;\s*padding-block:\s*0\.3rem/); + }); + + test("the controls the sweep found without a name have one", () => { + assert.match(web("pages", "Alerts.tsx"), /aria-label="Severity"/); + assert.match(web("pages", "Alerts.tsx"), /aria-label="Kind of alert"/); + assert.match(web("pages", "Secrets.tsx"), /aria-label="Status"/); + assert.match(web("pages", "Users.tsx"), /aria-label=\{`Role of \$\{u\.name \?\? u\.email \?\? "this user"\}`\}/); + }); + + test("a map node is named by what is written on it first (WCAG 2.5.3), with a space between the two parts of the text", () => { + const map = web("pages", "Map.tsx"); + assert.match(map, /"aria-label": `\$\{n\.label\}\$\{n\.sub \? ` \$\{n\.sub\}` : ""\}, \$\{KIND_WORD\[n\.kind\]\}, \$\{STATUS_WORD\[n\.status\]\}`/); + assert.match(map, /\{" "\}\s*/); + }); + + test("keyboard focus shows a ring on every control, by one rule for them all", () => { + assert.match(css, /:where\(a, button, input, select, textarea, summary, \[tabindex\]\):focus-visible\s*\{/); + }); +}); diff --git a/web/src/pages/Alerts.tsx b/web/src/pages/Alerts.tsx index fb9b4c4..a2d131e 100644 --- a/web/src/pages/Alerts.tsx +++ b/web/src/pages/Alerts.tsx @@ -464,7 +464,7 @@ function AlertsNow({ user, tabs }: { user: CurrentUser; tabs: React.ReactNode }) placeholder="Search alerts…" filters={ <> - setSeverity(e.target.value as "all" | AlertSeverity)}> @@ -477,7 +477,7 @@ function AlertsNow({ user, tabs }: { user: CurrentUser; tabs: React.ReactNode }) ))} - setCategory(e.target.value as "all" | AlertCategory)}> {presentCategories.map((c) => ( {n.label} - {n.sub && {n.sub}} + {n.sub && ( + <> + {" "} + {n.sub} + + )} ); @@ -212,7 +217,7 @@ function ConnectionsMap() { onMouseLeave: () => setFocus((f) => (f === n.id ? null : f)), onFocus: () => setFocus(n.id), onBlur: () => setFocus((f) => (f === n.id ? null : f)), - "aria-label": `${KIND_WORD[n.kind]}: ${n.label}${n.sub ? `, ${n.sub}` : ""}, ${STATUS_WORD[n.status]}`, + "aria-label": `${n.label}${n.sub ? ` ${n.sub}` : ""}, ${KIND_WORD[n.kind]}, ${STATUS_WORD[n.status]}`, }; return n.href ? ( diff --git a/web/src/pages/Secrets.tsx b/web/src/pages/Secrets.tsx index 67174d2..91cf6ba 100644 --- a/web/src/pages/Secrets.tsx +++ b/web/src/pages/Secrets.tsx @@ -338,6 +338,7 @@ export default function Secrets({ user }: { user: CurrentUser }) { filters={ td:first-child { html[data-menu-icons="off"] .dropdown-item .menu-item-icon { display: none; } + +/* ── Accessibility (found by an axe-core sweep of the main pages, both themes) ── */ + +/* Tabs that are not the one you are on, and the switch button that is: readable on the dark theme (at least 5.7:1; they were 2.8–3.7). */ +[data-bs-theme="dark"] :is(.nav-tabs, .nav-pills) .nav-link:not(.active) { + color: #9ca3af; +} + +:root:not([data-bs-theme="dark"]) .nav-pills .nav-link:not(.active) { + color: #5b6372; +} + +[data-bs-theme="dark"] .btn.active { + color: #5aa9ff; +} + +/* Tabler's green, yellow, red and blue are light enough to fail as text on white or on their own tint (1.9–4.3:1): on the light theme the text takes a darker shade of the same colour (at least 4.9:1 on white and on the tint). */ +:root:not([data-bs-theme="dark"]) :is(.text-green, .badge.text-green) { + color: #17692a !important; +} + +:root:not([data-bs-theme="dark"]) :is(.text-yellow, .badge.text-yellow) { + color: #8a5600 !important; +} + +:root:not([data-bs-theme="dark"]) :is(.text-orange, .badge.text-orange) { + color: #a14d00 !important; +} + +:root:not([data-bs-theme="dark"]) :is(.text-red, .badge.text-red) { + color: #b32d2d !important; +} + +:root:not([data-bs-theme="dark"]) :is(.text-blue, .badge.text-blue) { + color: #0558a8 !important; +} + +:root:not([data-bs-theme="dark"]) .badge.bg-secondary-lt.text-secondary { + color: #5b6372 !important; +} + +/* Tabler's blue is too dark to read as text on the dark theme and too light on its own tint on the light one (2.7–4.3:1): the chosen pill, text in the primary colour and an outlined primary button take a shade that does (at least 5.7:1 on dark, 6:1 on light). */ +[data-bs-theme="dark"] :is(.text-primary, .nav-pills .nav-link.active, .btn-outline-primary:not(:hover, :active, .active, :disabled)) { + color: #5aa9ff !important; +} + +:root:not([data-bs-theme="dark"]) :is(.text-primary, .nav-pills .nav-link.active) { + color: #0558a8 !important; +} + +.nav-pills .nav-link .opacity-75 { + opacity: 1 !important; +} + +:root:not([data-bs-theme="dark"]) .alert-info { + color: #0558a8 !important; +} + +[data-bs-theme="dark"] .alert-info { + color: #7cc0f7 !important; +} + +:root:not([data-bs-theme="dark"]) .text-warning { + color: #8a5600 !important; +} + +/* A link in the middle of a sentence is underlined, not only another colour (1.4.1: colour alone must not say it is one). */ +:is(p, li, .small, .text-secondary, .form-hint, .page-intro) a:not(.btn, .badge, .nav-link, .dropdown-item, .page-link, .list-group-item, .list-group-item-action, .map-node, .navbar-brand, [role="tab"], .btn-link) { + text-decoration: underline; + text-underline-offset: 0.18em; +} + +/* A link that is a whole line is at least 24 px tall (2.5.8: a target is not smaller than that). */ +:is(li, .small) > a:only-child:not(.nav-link, .dropdown-item, .page-link, .btn, .badge, .list-group-item, .list-group-item-action) { + display: inline-block; + padding-block: 0.3rem; +}