Appearance
Accessibility
WCAG 2.2 Level AA is a release gate, not a backlog item. This page documents the commitments, the patterns, and how they are verified.
What is measured, and what is not
AdminVora does not claim WCAG, Section 508, EN 301 549 or European Accessibility Act conformance, and publishes no VPAT. What is measured is below.
These are legal-compliance claims. A buyer can rely on them in a procurement process, so they are the last claims in this documentation that should outrun the build.
Measured, every release, by npm run test:a11y
| Standard swept | WCAG 2.1 AA, via axe-core (best-practice rules excluded) |
| Coverage | Every page, both colour modes |
| Current result | 10 nodes, all one rule — aria-required-children — inside Tabulator's grouped grid on the tables reference page |
| In AdminVora's own markup | No violation remains, and no colour-contrast failure anywhere |
| Held by | A ratchet baseline in tools/a11y.baseline.json — worse fails, and better fails too, so gains are locked in |
Contrast is measured separately and more strictly than axe manages: npm run test:contrast checks every preset in both modes at 4.5:1, reading computed styles from the browser rather than trusting the token generator's own arithmetic.
Not measured
- The 2.1-to-2.2 delta. The sweep runs at 2.1 AA. The 2.2 additions are not covered.
- Everything an automated sweep cannot answer — meaningful focus order, sensible reading order, whether an accessible name is true rather than merely present, whether an error message helps. The manual checklist below is the record of those, and it is a checklist rather than a gate.
- Assistive technology on real hardware. No NVDA, JAWS or VoiceOver testing has been done. This is scheduled and honestly outstanding.
- Section 508, EN 301 549 and the European Accessibility Act. No assessment has been carried out against any of them. They are not claimed.
The target
Full WCAG 2.2 AA with a published VPAT is the intended destination, and the distance to it is the three items above plus the vendor grid. Known Limitations carries the standing list.
Note — whatever is measured here covers AdminVora's components and shipped pages. Your application's content, copy and data are yours. A component library cannot make a badly-written error message clear.
Keyboard
Every interactive element is operable from the keyboard. No exceptions.
Global keys
| Key | Action |
|---|---|
| Tab / Shift+Tab | Move focus |
| Enter | Activate links and buttons |
| Space | Activate buttons, toggle checkboxes |
| Esc | Close the topmost overlay |
| Ctrl/⌘+K | Command palette |
| ? | Keyboard shortcut reference |
Composite widgets
Widgets that manage their own focus use roving tabindex: one child has tabindex="0", the rest have -1. Tab enters and leaves the widget; arrows move within it.
The two navigation trees are the exception, and the table says so on their own rows rather than in a footnote. Both are built from real disclosure elements and are operated by the platform, so Tab reaches everything and nothing is unreachable — what they do not add is the arrow-key layer.
| Widget | Keys |
|---|---|
| Tabs | ←→, Home, End |
| Menu / sidebar tree | Tab between triggers and links, Enter/Space to open a group — no arrow keys, no typeahead (why) |
| Tree view | Same: disclosure buttons carrying aria-expanded, operated with Tab and Enter/Space |
| Segmented control | ←→ (native radio behaviour) |
| Data grid | ↑↓ rows, Space select, Enter open |
| Kanban | Space pick up, arrows move, Space drop, Esc cancel |
| Combobox / palette | ↑↓, Enter, Esc |
| Date picker | Arrows by day, PgUp/PgDn by month |
| Slider | Arrows, Home, End, PgUp/PgDn |
Important — arrow-key direction is swapped in RTL. In Arabic, ← means "forward". This is the most commonly missed RTL detail in navigation components.
Focus management rules
| Situation | Requirement |
|---|---|
| Modal opens | Focus moves inside; trapped until close |
| Modal closes | Focus returns to the trigger |
| Drawer opens | Same |
| Route change (SPA) | Focus moves to the page <h1> |
| Content injected | Focus stays put unless the user initiated a jump |
| Element removed | Focus moves to a logical neighbour, never to <body> |
| Skip link activated | Focus moves to #main (which has tabindex="-1") |
js
// The pattern
const previous = document.activeElement;
openDialog();
// …later
closeDialog();
previous?.focus();Losing focus to <body> is the single most common SPA accessibility bug. The user's next Tab starts from the top of the page.
Focus indicators
scss
:where(a, button, input, select, textarea, summary, [tabindex]:not([tabindex="-1"])):focus-visible {
outline: var(--av-focus-width) solid var(--av-focus-color);
outline-offset: var(--av-focus-offset);
}Requirements (WCAG 2.4.11 / 2.4.13):
| Requirement | Implementation |
|---|---|
| ≥ 2px thick | --av-focus-width: 2px |
| ≥ 3:1 against the adjacent background | Verified by the token contrast lint |
| Encloses the whole control | outline + outline-offset, never a partial underline |
| Visible in every theme | Ring colour flips on brand-coloured surfaces |
| Never removed globally | outline: none is banned by Stylelint |
scss
// On a coloured surface, invert and add a halo so the ring contrasts with BOTH layers
.btn-primary:focus-visible {
--av-focus-color: var(--av-neutral-0);
box-shadow: 0 0 0 4px oklch(from var(--av-color-primary) l c h / .35);
}:focus-visible rather than :focus — mouse users do not see a ring on click, keyboard users always do. This is what makes it possible to have prominent focus indicators without designers objecting.
Semantics
Landmarks
html
<header> → banner
<nav aria-label="Main">
<main> → main
<aside> → complementary
<footer> → contentinfo
<form role="search">Exactly one of each per page. Multiple <nav> elements need distinct labels.
Headings
- One
<h1>per page: the page title - No skipped levels (
h2→h4is a failure) - Card and section titles use the level appropriate to their nesting
- Visual size is set by a class, never by choosing a different heading level
html
<!-- ❌ Chosen for size -->
<h4 class="av-page-header__title">Orders</h4>
<!-- ✅ Correct level, styled by class -->
<h1 class="av-page-header__title">Orders</h1>Names, roles, values
Every interactive element has:
| Property | Source |
|---|---|
| Name | Visible text, aria-label, or aria-labelledby |
| Role | Native element, or an explicit role |
| Value/state | aria-expanded, aria-selected, aria-checked, aria-pressed, aria-current |
html
<!-- Every state has a paired ARIA attribute -->
<button aria-expanded="false" aria-controls="menu">Catalog</button>
<button aria-pressed="true">Bold</button>
<a aria-current="page" href="/orders">Orders</a>
<div role="tabpanel" aria-labelledby="tab-1" tabindex="0">
<th aria-sort="ascending">
<input aria-invalid="true" aria-describedby="email-error">Rule enforced in review: if JavaScript toggles an is-* class, it must toggle the corresponding ARIA attribute in the same statement.
Live regions
AdminVora.a11y.announce(message, priority = 'polite') writes into one shared, visually hidden role="status" region the runtime creates on first use, switching its aria-live between polite and assertive. It clears the region first, so a repeated message announces again:
js
AdminVora.a11y.announce('Saved.');
AdminVora.a11y.announce('3 fields need attention.', 'assertive');Toasts use their own two regions, polite and assertive (for danger).
What to announce, and how urgently:
| Event | Politeness | Message |
|---|---|---|
| Table sorted | polite | "Sorted by Date, descending" |
| Rows selected | polite | "3 rows selected" |
| Page changed | polite | "Page 2 of 52" |
| Form submitted | polite | "Order saved" |
| Validation failed | assertive | "There are 2 problems with this form" |
| Upload complete | polite | "report.pdf uploaded" |
| Item deleted | polite | "Order 1042 deleted" |
| Connection lost | assertive | "You are offline" |
| Kanban card moved | polite | "Moved to In progress, position 2 of 5" |
Warning — over-using
assertivemakes the product unusable. It interrupts whatever the user is currently reading. Reserve it for errors and connection loss.
Colour and contrast
| Content | Minimum | AdminVora target |
|---|---|---|
| Body text | 4.5:1 | 7:1 |
| Large text (≥ 18.66px bold / 24px) | 3:1 | 4.5:1 |
| UI component boundaries | 3:1 | 3.5:1 |
| Focus indicator | 3:1 | 4.5:1 |
| Graphical objects (icons, chart lines) | 3:1 | 3:1 |
| Disabled elements | — | exempt |
Verified across every preset × light/dark × normal/high-contrast by npm run lint:tokens. A failure blocks the build.
Never colour alone
WCAG 1.4.1. Every status has an icon and text:
html
<!-- ❌ Colour is the only signal -->
<span class="av-badge av-badge--success">Paid</span>
<!-- ✅ -->
<span class="av-badge av-badge--success-soft">
<svg class="av-icon av-icon--xs" aria-hidden="true" viewBox="0 0 24 24"><path d="M4 12.5l5 5 11-11"/></svg>
Paid
</span>Charts with more than five series get dash patterns and marker shapes automatically. See Charts.
Forms
Covered in detail in Forms & Inputs. The rules:
| Rule | WCAG |
|---|---|
Every input has a <label for> | 1.3.1, 3.3.2 |
| No placeholder-only labels | 3.3.2 |
| Errors identified in text | 3.3.1 |
| Error suggestions provided | 3.3.3 |
aria-invalid on invalid fields | 4.1.2 |
aria-describedby links help and error text | 1.3.1 |
| Error summary focused after a failed submit | 3.3.1 |
Correct autocomplete tokens | 1.3.5 |
Field groups use <fieldset> + <legend> | 1.3.1 |
| Destructive actions confirmed or reversible | 3.3.4, 3.3.6 |
Motion and timing
| Requirement | Implementation |
|---|---|
prefers-reduced-motion respected | Global, plus per-module guards |
| No auto-playing animation over 5 s | Skeletons and spinners are exempt (they indicate progress) |
| No content flashing more than 3× per second | Enforced in review — seizure risk |
| Toast timers pause on hover and focus | WCAG 2.2.1 |
| Session timeouts warn 2 minutes before | WCAG 2.2.1 |
| No time limits on form completion | WCAG 2.2.1 |
Target size (WCAG 2.5.8)
24 CSS pixels, under a coarse pointer, on controls. That sentence has three parts and each one is a decision.
--av-size-touch-min is the number, defined once in the token layer. Nothing hard-codes 24.
scss
@media (pointer: coarse) {
.av-check { --av-check-size: var(--av-size-touch-min); }
}Under a coarse pointer only. A mouse can hit a 16px caret; a fingertip covers about 9 mm and cannot aim at what it is covering. Growing every checkbox on a desktop to touch size makes a dense screen worse for the pointer actually in use, so the rules live in @media (pointer: coarse) and change nothing for a mouse. This is why the density axis is not the answer: density is a document attribute the reader chooses, and the pointer is not something they choose.
On controls. Buttons, checkboxes, switches, steppers, sliders, sort headers, carousel dots, segmented options. Links keep their line height — a breadcrumb, a table-cell link and a card-header action are text, and SC 2.5.8 exempts a link in a sentence for the same reason a word is not a button. That is a decision on the record (6 September 2026), not an oversight: a link that ought to be a target ought to be marked up as a button.
Two techniques, chosen per component rather than applied uniformly:
| Situation | Technique | Example |
|---|---|---|
| The drawn control is the target | Raise its own size knob | .av-check, .av-table__sort |
| The drawing must not change | Grow the target around it | .av-mail-row__star, .av-cat-row__toggle, .av-carousel__dot |
The second is the one worth reading twice. A carousel dot is a position indicator: a 24px disc would read as a button and a row of them would read as a toolbar. So the dot stays 8px and the box around it grows, with background-clip: content-box keeping the paint on the dot. The star and the caret grow with padding and an equal negative margin, so the target is 24px and the row it sits in does not move a pixel.
The measurement that matters is the effective target, not the element's box: a control wrapped in a label, or named by a for=, is activated by the whole label, and that is what a thumb lands on. Measuring boxes alone reported 262 failures where there were 113 — and a gate that cries wolf gets its threshold lowered.
npm run test:touch holds all of this: every control on every page, measured with a coarse pointer, plus a vacuity guard that re-measures with a fine one and requires the sizes to differ — so a @media (pointer: coarse) block that quietly stopped matching fails the build instead of passing while testing the desktop stylesheet.
8px spacing between adjacent targets is not separately checked. It falls out of the --av-space-2 gap in button groups, toolbars and table action cells.
Zoom and reflow
| Requirement | WCAG |
|---|---|
| 200% zoom without loss of content or function | 1.4.4 |
| 400% zoom / 320px width with no horizontal scroll | 1.4.10 |
| Text spacing adjustable without clipping | 1.4.12 |
| No fixed-height text containers | 1.4.12 |
No user-scalable=no | 1.4.4 |
scss
/* ❌ Clips when a user applies a text-spacing bookmarklet */
.av-badge { height: 20px; line-height: 20px; }
/* ✅ Grows with content */
.av-badge { min-block-size: 20px; padding-block: 2px; line-height: 1.4; }Testing
Automated (catches ~35%)
bash
npm run test:a11yjs
// tests/a11y/pages.spec.js
import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';
const PAGES = ['/dashboard', '/orders', '/settings', '/auth/login', '/apps/kanban'];
const THEMES = ['light', 'dark'];
for (const path of PAGES) {
for (const theme of THEMES) {
test(`${path} (${theme}) has no axe violations`, async ({ page }) => {
await page.goto(path);
await page.evaluate((t) => AdminVora.theme.set('mode', t), theme);
const results = await new AxeBuilder({ page })
.withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa'])
.analyze();
expect(results.violations).toEqual([]);
});
}
}Custom assertions beyond axe:
js
test('every icon-only control has an accessible name', async ({ page }) => {
const unnamed = await page.$$eval('button, a', (els) => els
.filter((el) => el.querySelector('svg') && !el.textContent.trim())
.filter((el) => !el.getAttribute('aria-label') && !el.getAttribute('aria-labelledby'))
.map((el) => el.outerHTML.slice(0, 120)));
expect(unnamed).toEqual([]);
});
test('focus is never lost after closing a modal', async ({ page }) => {
await page.goto('/orders');
await page.click('[data-bs-toggle="modal"]');
await page.keyboard.press('Escape');
const tag = await page.evaluate(() => document.activeElement?.tagName);
expect(tag).not.toBe('BODY');
});
test('no heading levels are skipped', async ({ page }) => {
const levels = await page.$$eval('h1,h2,h3,h4,h5,h6',
(hs) => hs.map((h) => Number(h.tagName[1])));
levels.reduce((prev, cur) => {
expect(cur - prev).toBeLessThanOrEqual(1);
return cur;
}, levels[0]);
});Manual (catches the other 65%)
Every component ships only after this checklist passes.
Keyboard, no mouse
- [ ] Reach every interactive element with Tab
- [ ] Focus is always visible
- [ ] Tab order follows visual order
- [ ] No keyboard traps
- [ ] Esc closes every overlay
- [ ] Composite widgets follow their documented arrow-key model
Screen readers
- [ ] NVDA + Firefox (Windows) — the most common combination
- [ ] VoiceOver + Safari (macOS)
- [ ] VoiceOver (iOS)
- [ ] TalkBack (Android)
- [ ] Every control announces name, role, and state
- [ ] Live-region announcements are useful, not noise
Visual
- [ ] 200% zoom
- [ ] 400% zoom / 320px width
- [ ] Windows High Contrast mode
- [ ] Greyscale — is anything now ambiguous?
- [ ] Colour-blindness simulation (deuteranopia, protanopia, tritanopia)
- [ ] Text-spacing bookmarklet applied
Cognitive
- [ ] Error messages say what to do, not just what is wrong
- [ ] Destructive actions confirmed or undoable
- [ ] No unexpected context changes on focus or input (WCAG 3.2.1, 3.2.2)
- [ ] Consistent navigation and labelling across pages
Assistive technology support
| Screen reader | Browser | Support |
|---|---|---|
| NVDA | Firefox, Chrome | Full |
| JAWS | Chrome, Edge | Full |
| VoiceOver | Safari (macOS, iOS) | Full |
| TalkBack | Chrome (Android) | Full |
| Narrator | Edge | Tested, minor gaps in complex grids |
| Orca | Firefox (Linux) | Tested |
| Other AT | Support |
|---|---|
| Dragon NaturallySpeaking | Full — all controls have visible labels |
| Windows High Contrast | Full — forced-colors handled |
| Browser zoom to 400% | Full |
| Screen magnifiers | Full — focus scrolls into view |
| Switch access | Full — no hover-only interactions |
Reporting an issue
Accessibility bugs are treated as P1. Report to a11y@creativeigniter.com with:
- The page or component
- Assistive technology and version
- Browser and OS
- Expected versus actual behaviour
- WCAG success criterion, if known
Target response: 2 business days. Target fix: next patch release.
Read next: Performance.