Skip to content

Accessibility ​

pd-components is WCAG 2.2 AA first (SPEC §1.2 rule 8): every keyboard map, focus move, and ARIA attribute described on the component pages is part of the contract, backed by tests/a11y/*.a11y.test.ts (axe, zero violations, closed and open states) and the ARIA-syncing assertions in tests/unit/*.test.ts. But an unstyled, markup-agnostic library can only own behavior — it has no opinion on your copy, your color, or your layout. This page draws that line component by component, then gives you the checklist for the half it can't do for you.

What the library guarantees vs. what you provide ​

The library managesYou must provide
aria-expanded on every invoker, synced at the moment state flipsaria-label on the wrapping <nav>, the drawer's <dialog>, and any icon-only button (▾, ✕, ☰)
Full keyboard operability with no roving tabindex; available controls retain native DOM orderVisible :focus-visible styles (the library ships zero CSS)
Focus save/restore on drawer close, drill/back, and EscapeTarget size (WCAG 2.5.8) for every invoker you style
Closing/inactive animated surfaces become inert immediately, before their visual exit finishesKeep visual order matching DOM order; CSS reordering can still create a confusing sequence
role="group"/aria-label on labeled drilldown panels; role="status" on filter-statusColor contrast (1.4.3 / 1.4.11)
Dismissible/hoverable/persistent hover panels (1.4.13) once you opt in with hoverReduced-motion-safe exit animations (the library sets no transforms/animations itself)
Dev-console warnings for structurally unreachable markup (e.g. a keyboard-dead mega menu panel)Fixing what the warning tells you — it never throws, never blocks render

WCAG 2.2 AA commitments by success criterion ​

2.1.1 Keyboard (no trap, everything operable) ​

  • pd-nav/pd-nav-panel — no roving tabindex; triggers are plain a[href]/button. A panel with no enabled, tabbable open/toggle button[commandfor] outside it is unreachable by keyboard alone (hover/focus association isn't sufficient), so PdNavPanel warns to the console on connect (#warnIfUnreachable, src/nav/nav-panel.ts). Fix by adding a real invoker button — this is a dev-time signal, not a runtime block.
  • pd-drawer — dialog.showModal() gives native top-layer focus containment; Tab/Shift+Tab cycle inside without extra code. The native cancel event (Escape) is intercepted so dismissal still runs the animated, cancelable hide('escape') path rather than an abrupt native close.
  • pd-drilldown — drill/back are plain buttons; the outgoing panel becomes inert synchronously and focus is moved deterministically on every transition (see 2.4.3 below), so a keyboard user is never left in an inactive screen while its exit remains rendered.
  • pd-filter — index letters matching zero items get the disabled attribute (not aria-disabled), removing them from the tab order entirely. This is a deliberate reading of 2.1.1: it requires available functionality to be operable by keyboard, and a letter with no matches has no function to expose. The tradeoff (a sighted keyboard user sees a visibly disabled control rather than a missing one, which is more informative than silently absent) is documented on the filter component page.
  • pd-header — never auto-hides while it contains focus or an open descendant (#isLocked() in src/header/header.ts). A keyboard user tabbing through the primary nav never has their focused control scrolled off-screen mid-traversal.

1.4.13 Content on Hover or Focus ​

Applies to pd-nav's opt-in hover panels. All three sub-requirements are met structurally, not by convention:

  • Dismissible — Escape closes the open panel from anywhere in the nav, without moving the pointer.
  • Hoverable — the hover region for panel X is its invoker(s) ∪ any data-pd-hover-for="X" element ∪ the panel itself, resolved via delegated pointerover/pointerout and a closest() membership test. The pointer can travel from trigger to panel content without the panel closing.
  • Persistent — no open-ended timeout while hovered. hover-close-delay (default 200ms) only starts once the pointer leaves the entire region, and re-entry cancels the pending close. Keyboard focus anywhere in the associated link/button/panel region also suppresses that close; focusout owns dismissal once the pointer is gone.

This is automatic once you add hover; the one thing to get right yourself is keeping a panel's visual footprint inside the region you declared with data-pd-hover-for — content that visually overflows an undeclared area falls outside the hoverable guarantee.

2.4.3 Focus Order ​

  • pd-drilldown — drilling in moves focus to the destination panel's first tabbable (by convention its own Back button, first in source order). Backing out returns focus to the exact button that drilled in, tracked per stack entry — never "the drilldown's first button," so focus order always matches navigation history rather than jumping.
  • pd-nav Escape — closes one layer at a time and focuses the closed panel's primary invoker (the first usable open/toggle invoker outside the panel itself, §2.3 of the spec) — closing returns focus to a real entry point, not to <body> or an unavailable control. A nested panel consumes the first Escape so an ancestor panel or native dialog cannot close from the same keypress.
  • pd-drawer — explicit focus save/restore, not a reliance on native dialog restore (which is absent in jsdom and inconsistent under polyfills — SPEC §5.3). Command-driven opens remember the exact invoker even when WebKit leaves a clicked button unfocused; API opens remember the active element. Restore is skipped if focus already moved somewhere meaningful during close, so the drawer never yanks focus back over an intentional move.
  • Your job: keep visual order matching DOM order. This is why the docs recipes are CSS-Grid first (SPEC §1.2) — a flex/grid reorder that changes visual order without changing DOM order breaks 2.4.3 for sighted keyboard users even though the library's focus moves are all correct.

4.1.2 Name, Role, Value ​

  • aria-expanded is synced on every invoker of a disclosure-like element (disclosure, nav panel, drawer dialog) at the moment the open attribute flips — before the exit animation runs, not after. A screen reader announces the new state immediately on activation.
  • aria-controls is never set — commandfor already provides the programmatic association via the Invoker Commands API, and every unit test suite asserts this (avoids a redundant/conflicting relationship).
  • pd-drilldown-panel[label] maps to role="group" + aria-label — gives an entered panel a name (see the screen-reader note below).
  • pd-filter buttons all get aria-pressed synced (both the active and inactive ones) — correct toggle-button semantics, not just a true slapped on the winner.
  • pd-filter-status sets role="status" (implicit aria-live="polite"); the announced string is entirely your author-written template — the component only re-renders it.
  • Your job: every label. aria-label on the wrapping <nav>, on the drawer's <dialog>, on icon-only invokers. None of this is defaulted — the component has no idea what language or brand voice you're using. Missing labels are consistently the top axe finding on unstyled components like these.

Screen-reader behavior notes ​

  • aria-expanded announcements — happen synchronously with the open attribute flip (#syncInvokers in src/internal/openable.ts), so a screen reader on a toggle button announces the new expanded/collapsed state reliably while the exit animation is still in flight. The closing surface is already inert; you don't need to wait for hidden/dialog.close() or pd:closed to trust what has been announced.
  • role="status" announcements (pd-filter-status) — polite live regions are only announced once the screen reader is idle, and only on text changes. That's why the component mutates the same node's textContent on every pd:filter instead of removing/re-adding it — some AT/browser combinations silently miss an added node but reliably catch a text mutation. Rapid re-filtering (fast-clicking through letters) can still cause a screen reader to collapse or skip intermediate announcements — that's inherent live-region behavior, not a component bug. Keep the template terse (Showing {count} of {total} brands) so whatever is announced is useful.
  • Focus-move announcements in pd-drilldown — when --pd-drill activates a panel, focus lands on its first tabbable, normally its own Back button. If that panel has a label attribute, the panel is role="group"/aria-label, and because focus landed inside that group, most screen readers announce the group's name as part of entering it — a drill-in reads as "Skincare, group, Back, button" rather than an unlabeled "Back, button," telling the user where they just went. Panels without label skip this entirely, so always label any panel a user could drill into from content that doesn't already say where it leads.

Author checklist ​

  • Visible :focus-visible styles on every interactive element you style — the library ships none; check nothing upstream in your theme has set outline: none without replacing it.
  • aria-label on the wrapping <nav> (and on any other landmark hosting a pd-header/pd-nav).
  • WCAG 2.5.8 target size: invoker buttons (mega-menu toggles, filter letters, close buttons) need a 24×24 CSS px minimum or adequate spacing from neighbors — the copy-paste recipes on each component page use padding rather than fixed dimensions for exactly this reason.
  • Color contrast for text and non-text UI (1.4.3 / 1.4.11) — a headless component makes zero color decisions for you.
  • A prefers-reduced-motion guard on every exit animation you write; see styles/base.css for a blanket example, and each component page's CSS recipe repeats a local one so the snippet is self-contained.
  • aria-label on every icon-only invoker (▾, ✕, ☰) — put it on the <button>, not on the icon.

See the Styling guide for how data-state/aria-* selectors drive CSS without any of the above being compromised, and each component page's own Accessibility section for the ARIA table specific to that element.