Keyboard Navigation

All interactive components are operable without a pointer device. The conventions below are applied consistently across the system.

Focus Management

• All interactive elements receive a clearly visible focus indicator. The default browser outline is not suppressed; components augment it where needed.
• Components that open a layer (dropdown, dialog) move focus into the opened content and return it to the trigger on close.
• Modals and dialogs trap focus — Tab cycles only within the open dialog until it is dismissed.

Skip Navigation

The Skip Navigation Link component provides a visible-on-focus link that jumps directly to the main content area. It must be the first focusable element in the page and must target the id of the <main> element.

Tab Order

Tab order follows the visual reading order (left-to-right, top-to-bottom). Positive tabindex values are not used — DOM order determines sequence.

Component-Specific Notes

• Menu / Navigation — uses arrow keys for item navigation within a menu, Enter/Space to activate, Escape to close. See the Menu component for the full interaction pattern.
• Breadcrumb — rendered as a <nav aria-label="Breadcrumb">; the current page link is marked aria-current="page". See the Breadcrumb component.
• Tabs (seven-minute-tabs) — follow the ARIA authoring practices for the tabs pattern: arrow keys switch tabs, Tab moves into the panel.
• Dropdowns — Escape closes the dropdown and returns focus to the trigger.

ARIA Patterns

ARIA is used sparingly and only where native HTML semantics are insufficient. The principle is: prefer native elements, reach for ARIA only when there is no suitable HTML equivalent.

Landmark Roles

Every page should contain exactly one <main> element. Navigation regions use <nav> with a descriptive aria-label to distinguish multiple navigation landmarks (e.g. "Main navigation", "Breadcrumb", "Pagination").

Interactive Widgets

• Disclosure (details/summary) — uses native <details>/<summary> wherever possible; ARIA aria-expanded is only added when a custom toggle is required.
• Tabs — role="tablist", role="tab", role="tabpanel" following the ARIA tabs pattern.
• Navigation menus — role="list" on <ul> elements restores list semantics in browsers that strip them with list-style: none.
• Pagination — wrapped in <nav aria-label="Pagination">; current page marked aria-current="page".

Live Regions

Dynamic content changes (e.g. search results, form validation messages) are announced via aria-live="polite". Urgent interruptions use aria-live="assertive" — this is reserved for genuine errors only.

Icon-Only Controls

Any control that conveys meaning through an icon alone must include an accessible label. Use aria-label on the control or <span class="sr-only"> for a visually-hidden text alternative.

Color & Contrast

Color is never the sole means of conveying information. All meaningful distinctions are also communicated through text, icons, or patterns.

Contrast Requirements

• Normal text (below 18pt / 14pt bold): minimum 4.5 : 1 contrast ratio against its background.
• Large text (18pt+ / 14pt+ bold) and UI component boundaries: minimum 3 : 1.
• Decorative elements and disabled controls are exempt.

Brand Token Constraints

The brand token layer (Brand Tokens) exposes primary, secondary, and accent color roles. When overriding these for a child template, verify the new palette against the contrast requirements above — especially for:

• Button text on button background
• Link color on page background
• Focus indicator against adjacent colors

The Core Colors page lists all palette entries. Choose accessible pairings from that palette.

Focus Indicators

Focus indicators must meet a 3 : 1 contrast ratio between the focused and unfocused states. The default system focus style is a solid outline that contrasts against both light and dark backgrounds.

Motion & Animation

Animations and transitions respect the user's operating-system preference for reduced motion.

prefers-reduced-motion

All CSS animations and transitions are wrapped in a @media (prefers-reduced-motion: no-preference) block or reset to animation: none; transition: none; inside a @media (prefers-reduced-motion: reduce) block. Users who have enabled the reduced-motion setting in their OS receive no decorative movement.

Animation Guidelines

• Decorative animations (parallax, auto-playing carousels, background movement) must be pausable or disabled under reduced-motion.
• Functional animations (dropdown open, accordion expand) are kept short (under 200 ms) and use opacity or transform — not width/height changes that cause layout reflow.
• Nothing flashes more than three times per second (WCAG 2.3.1).

Component Reference

The JCrafts Animation and Jump Mark components both implement prefers-reduced-motion support. Use them as implementation references.

Testing Accessibility

Automated tools catch roughly 30–40 % of accessibility issues. Manual testing is required for the rest.

Automated Scan

• Run axe DevTools (browser extension) or Lighthouse on each page type.
• Integrate an axe-core assertion in end-to-end tests to catch regressions in CI.
• Common issues caught automatically: missing alt text, invalid ARIA roles, low contrast (approximately), missing form labels.

Keyboard-Only Walkthrough

Unplug (or disable) the pointer and navigate the full page using only the keyboard:

1. Tab through every interactive element in order — confirm visual focus is always visible.
2. Activate every control with Enter/Space — confirm the expected action occurs.
3. Open and close every overlay (dropdown, dialog, mobile menu) — confirm focus returns to the trigger.
4. Complete any forms keyboard-only — confirm error messages are reachable.

Screen Reader Testing

• Test with at least one combination: NVDA + Firefox (Windows) or VoiceOver + Safari (macOS/iOS).
• Verify landmark navigation (headings, regions, lists) reads in a logical order.
• Verify that dynamic content changes (live regions) are announced.
• Verify that icon-only buttons announce their purpose, not just "button".

Zoom & Reflow

• Zoom the browser to 200 % — no content should be clipped or require horizontal scrolling on a 1280 px viewport.
• At 400 % zoom (WCAG 1.4.10 Reflow), all content must be available in a single-column layout without loss of information.