Keyboard Navigation Testing

Free — GPL coresize Mplanned, not built

Generated from docs/plan/core/keyboard-navigation-testing/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

AstroBaaS commits to keyboard-accessible admin UI and default storefront templates. Merchants get a testing guide and checklist to verify keyboard navigation works in their own customized storefronts. This ensures customers without mice or with motor disabilities can use the shop.

The problem

Merchants don’t test keyboard-only navigation. Customers using only keyboards or assistive devices that emulate keyboards cannot navigate the admin or storefront. This locks out users and may expose the merchant to accessibility legal risk.

What it does

• Admin UI: all interactive elements (buttons, links, form fields, modals) are navigable by Tab key
• Admin UI: Tab order is logical and follows visual order (left-to-right, top-to-bottom)
• Admin UI: all interactive elements have visible focus indicators (outline, highlight, or underline)
• Admin UI: Escape key closes any open modal and returns focus to the button that opened it
• Admin UI: Enter key activates buttons; Space activates checkboxes; Arrow keys move focus in dropdowns
• Admin UI: form labels are associated with inputs (HTML label with for= attribute or aria-labelledby)
• Storefront product pages: links, buttons, and quantity input are keyboard navigable
• Storefront cart/checkout: form fields and buttons are keyboard accessible
• Storefront: ‘Skip to content’ link is available to bypass navigation and move focus to main content
• Documentation: keyboard shortcuts guide published in admin (e.g., ‘Press Escape to close’, ‘Enter to submit’)
• Testing checklist: accessible in admin under Settings > Accessibility, guides merchants through keyboard testing steps

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• Does not automatically detect keyboard accessibility issues — merchants must test manually or use external tools like axe-core, WebAIM.
• Does not provide screen reader compatibility — that’s a separate a11y scope beyond keyboard (NVDA, JAWS, VoiceOver require additional semantic HTML).
• Does not provide drag-and-drop alternatives in this sprint — dragging is a separate UI pattern with its own keyboard fallback; focus on Tab, Enter, Escape, Arrow.
• Does not audit customer storefronts for keyboard a11y — merchants must test their own custom templates and themes (core provides base, merchants inherit).
• Does not include automated testing suite — merchants should use external tools (Lighthouse, WebAIM Wave, or paid services) to audit their storefront.

Data model

none

API

None recorded.

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Settings page section titled ‘Accessibility & Keyboard Testing’ with: (1) status indicator ‘Keyboard navigation: Implemented’; (2) quick reference guide: ‘Tab to navigate, Escape to close modals, Enter to submit’; (3) expandable checklist of keyboard test steps (e.g., ‘Tab through every button on this page’, ‘Press Escape in a modal’, ‘Use Arrow keys in a dropdown’); (4) link to full accessibility documentation; (5) link to external tools (axe-core, WebAIM).

The seam — why this is core

Core owns the keyboard-navigable implementation of admin UI and default storefront templates, focus indicators, Tab order, and Escape/Enter/Arrow key behavior. Merchants inherit this and are responsible for testing their own customized themes and ensuring custom components remain accessible.

Core owns the interface + honest keyboard tester; accessibility is infrastructure, not a support commitment or credential.

Dependencies

• UI framework (Astro, React, or vanilla JS depending on implementation)
• Form and modal component libraries (must support keyboard out-of-the-box)

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• Tab key cycles through all interactive elements (buttons, links, inputs, selects) on a page in logical order
• Escape key closes any open modal and returns focus to the button/link that opened it
• All buttons and interactive elements have a visible focus indicator (outline, highlight, or color change)
• Enter key activates buttons and submits forms
• Space key toggles checkboxes and radio buttons
• Arrow Up/Down keys navigate within a dropdown select without opening a new page
• Keyboard shortcuts (if any) are documented in the Accessibility settings page and work as documented
• Tab order on checkout form follows the visual order (billing address top-to-bottom, payment, then button), not DOM source order

Risks

If focus indicators are too subtle (low contrast, no visible change), merchants think keyboard navigation is broken when it actually works. If modals are not keyboard-trapped, Tab can escape the modal and confuse the user flow. If Escape doesn’t close modals, users are stuck. If merchants customize the UI, they may break keyboard accessibility in their own code, but that’s their responsibility, not core’s (though it affects their support load).

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.