Skip to content

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 sweptWCAG 2.1 AA, via axe-core (best-practice rules excluded)
CoverageEvery page, both colour modes
Current result10 nodes, all one rule — aria-required-children — inside Tabulator's grouped grid on the tables reference page
In AdminVora's own markupNo violation remains, and no colour-contrast failure anywhere
Held byA 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 ​

KeyAction
Tab / Shift+TabMove focus
EnterActivate links and buttons
SpaceActivate buttons, toggle checkboxes
EscClose the topmost overlay
Ctrl/⌘+KCommand 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.

WidgetKeys
Tabs←→, Home, End
Menu / sidebar treeTab between triggers and links, Enter/Space to open a group — no arrow keys, no typeahead (why)
Tree viewSame: disclosure buttons carrying aria-expanded, operated with Tab and Enter/Space
Segmented control←→ (native radio behaviour)
Data grid↑↓ rows, Space select, Enter open
KanbanSpace pick up, arrows move, Space drop, Esc cancel
Combobox / palette↑↓, Enter, Esc
Date pickerArrows by day, PgUp/PgDn by month
SliderArrows, 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 ​

SituationRequirement
Modal opensFocus moves inside; trapped until close
Modal closesFocus returns to the trigger
Drawer opensSame
Route change (SPA)Focus moves to the page <h1>
Content injectedFocus stays put unless the user initiated a jump
Element removedFocus moves to a logical neighbour, never to <body>
Skip link activatedFocus 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):

RequirementImplementation
≥ 2px thick--av-focus-width: 2px
≥ 3:1 against the adjacent backgroundVerified by the token contrast lint
Encloses the whole controloutline + outline-offset, never a partial underline
Visible in every themeRing colour flips on brand-coloured surfaces
Never removed globallyoutline: 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 → h4 is 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:

PropertySource
NameVisible text, aria-label, or aria-labelledby
RoleNative element, or an explicit role
Value/statearia-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:

EventPolitenessMessage
Table sortedpolite"Sorted by Date, descending"
Rows selectedpolite"3 rows selected"
Page changedpolite"Page 2 of 52"
Form submittedpolite"Order saved"
Validation failedassertive"There are 2 problems with this form"
Upload completepolite"report.pdf uploaded"
Item deletedpolite"Order 1042 deleted"
Connection lostassertive"You are offline"
Kanban card movedpolite"Moved to In progress, position 2 of 5"

Warning — over-using assertive makes the product unusable. It interrupts whatever the user is currently reading. Reserve it for errors and connection loss.


Colour and contrast ​

ContentMinimumAdminVora target
Body text4.5:17:1
Large text (≥ 18.66px bold / 24px)3:14.5:1
UI component boundaries3:13.5:1
Focus indicator3:14.5:1
Graphical objects (icons, chart lines)3:13: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:

RuleWCAG
Every input has a <label for>1.3.1, 3.3.2
No placeholder-only labels3.3.2
Errors identified in text3.3.1
Error suggestions provided3.3.3
aria-invalid on invalid fields4.1.2
aria-describedby links help and error text1.3.1
Error summary focused after a failed submit3.3.1
Correct autocomplete tokens1.3.5
Field groups use <fieldset> + <legend>1.3.1
Destructive actions confirmed or reversible3.3.4, 3.3.6

Motion and timing ​

RequirementImplementation
prefers-reduced-motion respectedGlobal, plus per-module guards
No auto-playing animation over 5 sSkeletons and spinners are exempt (they indicate progress)
No content flashing more than 3× per secondEnforced in review — seizure risk
Toast timers pause on hover and focusWCAG 2.2.1
Session timeouts warn 2 minutes beforeWCAG 2.2.1
No time limits on form completionWCAG 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:

SituationTechniqueExample
The drawn control is the targetRaise its own size knob.av-check, .av-table__sort
The drawing must not changeGrow 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 ​

RequirementWCAG
200% zoom without loss of content or function1.4.4
400% zoom / 320px width with no horizontal scroll1.4.10
Text spacing adjustable without clipping1.4.12
No fixed-height text containers1.4.12
No user-scalable=no1.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:a11y
js
// 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 readerBrowserSupport
NVDAFirefox, ChromeFull
JAWSChrome, EdgeFull
VoiceOverSafari (macOS, iOS)Full
TalkBackChrome (Android)Full
NarratorEdgeTested, minor gaps in complex grids
OrcaFirefox (Linux)Tested
Other ATSupport
Dragon NaturallySpeakingFull — all controls have visible labels
Windows High ContrastFull — forced-colors handled
Browser zoom to 400%Full
Screen magnifiersFull — focus scrolls into view
Switch accessFull — 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.

Documentation for @creativeigniter/adminvora