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 manages | You must provide |
|---|---|
aria-expanded on every invoker, synced at the moment state flips | aria-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 order | Visible :focus-visible styles (the library ships zero CSS) |
| Focus save/restore on drawer close, drill/back, and Escape | Target size (WCAG 2.5.8) for every invoker you style |
Closing/inactive animated surfaces become inert immediately, before their visual exit finishes | Keep 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-status | Color contrast (1.4.3 / 1.4.11) |
Dismissible/hoverable/persistent hover panels (1.4.13) once you opt in with hover | Reduced-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 rovingtabindex; triggers are plaina[href]/button. A panel with no enabled, tabbable open/togglebutton[commandfor]outside it is unreachable by keyboard alone (hover/focus association isn't sufficient), soPdNavPanelwarns 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 nativecancelevent (Escape) is intercepted so dismissal still runs the animated, cancelablehide('escape')path rather than an abrupt native close.pd-drilldown— drill/back are plain buttons; the outgoing panel becomesinertsynchronously 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 thedisabledattribute (notaria-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()insrc/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 —
Escapecloses the open panel from anywhere in the nav, without moving the pointer. - Hoverable — the hover region for panel
Xis its invoker(s) ∪ anydata-pd-hover-for="X"element ∪ the panel itself, resolved via delegatedpointerover/pointeroutand aclosest()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-navEscape — 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-expandedis synced on every invoker of a disclosure-like element (disclosure, nav panel, drawer dialog) at the moment theopenattribute flips — before the exit animation runs, not after. A screen reader announces the new state immediately on activation.aria-controlsis never set —commandforalready 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 torole="group"+aria-label— gives an entered panel a name (see the screen-reader note below).pd-filterbuttons all getaria-pressedsynced (both the active and inactive ones) — correct toggle-button semantics, not just atrueslapped on the winner.pd-filter-statussetsrole="status"(implicitaria-live="polite"); the announced string is entirely your author-written template — the component only re-renders it.- Your job: every label.
aria-labelon 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-expandedannouncements — happen synchronously with theopenattribute flip (#syncInvokersinsrc/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 alreadyinert; you don't need to wait forhidden/dialog.close()orpd:closedto 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'stextContenton everypd:filterinstead 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-drillactivates a panel, focus lands on its first tabbable, normally its own Back button. If that panel has alabelattribute, the panel isrole="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 withoutlabelskip 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-visiblestyles on every interactive element you style — the library ships none; check nothing upstream in your theme has setoutline: nonewithout replacing it. aria-labelon the wrapping<nav>(and on any other landmark hosting apd-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-motionguard on every exit animation you write; seestyles/base.cssfor a blanket example, and each component page's CSS recipe repeats a local one so the snippet is self-contained. aria-labelon 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.