Docs / Secure
WCAG 2.2 AA (Admin)
EdgeCMS targets WCAG 2.2 Level AA for the Admin UI and the Storyblok-class visual-edit host (@edgecms/client mountVisualEdit). This is an implementation baseline and CI evidence, not a formal certification.
Scope
| Surface | Focus | Labels | Contrast | Keyboard |
|---|---|---|---|---|
| Admin shell | Skip link, route focus on #content, :focus-visible rings | Form/aria-* on core inputs; icon buttons named | Semantic tokens (muted-foreground, warning) | Sidebar, tables, dialogs (Radix), bulk actions |
| Entry live preview | Device/mode toggles focusable | aria-label + aria-pressed on chrome | Emerald/warning text tuned for AA | Mode and device groups |
| Visual-edit host | :focus-visible outline ≥3:1 | aria-label="Edit {field}", badge aria-hidden | Field outline + badge use sky-700 | Tab, Enter/Space activate, Escape blurs; polite live region for save/conflict |
Visual-edit keyboard map
- Tab moves between
[data-edgecms-field]nodes (tabindex="0"). - Enter / Space starts in-place edit (
contenteditable,role="textbox"). - Escape blurs the active field (triggers the existing save/
UPDATEpath). - Save / conflict / error ACK messages are announced via
#edgecms-ve-live(aria-live="polite").
Local axe gate (not required PR CI)
PR CI stays lean (typecheck / lint / unit tests / build). Run axe locally or for partner demos — fails on critical / serious violations (WCAG 2.A / 2.AA / 2.1 AA / 2.2 AA tags):
| Layer | Command | Coverage |
|---|---|---|
| Visual-edit host | bun test packages/client/src/__tests__/visual-edit-axe.test.ts | Mounted [data-edgecms-field] + editing role="textbox" |
| Admin critical path | bun run test:e2e:a11y | /sign-in, /admin/tenants, collections, entries, media, users, webhooks, publishing, releases, settings |
bun run check:a11y
# or full local gate including Playwright axe + benches:
bun run check:all:fullAdmin Playwright axe includes color-contrast (critical/serious) via local check:a11y / test:e2e:a11y — not a required PR Actions job. Semantic tokens (muted-foreground, success, info, warning) are the preferred palette for chrome text. Visual-edit unit axe does not disable contrast. Playwright Chromium install is local-only (Actions runners have flaked on unsupported OS images).
Verification
bun run check:a11y
bun run test:client
bun run --filter edgecms-admin test src/components/skip-to-main.test.tsx
bun run --filter edgecms-admin test src/features/entries/components/related-entries-display.test.tsx
bun run lintManual: open Admin live preview + demo host, Tab through editable fields, confirm focus ring and SR announcements on save/conflict.
Out of scope (follow-ups)
- Remaining Admin surfaces not yet in
e2e/a11y-axe.spec.ts(entry editor, TipTap, environments, plugins, sync conflicts). - Third-party TipTap chrome beyond existing
aria-invalid/aria-describedbywiring. - Marketing website (
apps/website) surfaces.