# Ballbox html-first accessibility plan

## Goal
Shift key Ballbox flows toward semantic HTML first, then JS enhancement.

## Principles
- Prefer native elements before custom widgets.
- Use labels, fieldsets, lists, headings, and forms.
- Keep critical actions reachable by keyboard with visible focus.
- Use ARIA to expose state, not to replace missing semantics.
- Keep selection and status visible in the document flow.

## Scope executed now
1. `classes-by-date`
   - custom overlay flow replaced with in-page detail panel
   - slot selection exposed with `aria-expanded`, `aria-controls`, and live status
   - filters and results structured as labeled sections/lists
2. `admin/payments`
   - custom Radix selects in QR forms replaced with native `<select>`
   - action areas converted into real forms with labels and submit buttons
   - live status/error messaging and explicit help text added

## Next backlog
- Audit all custom dialogs, popovers, and selects.
- Add keyboard + screen reader acceptance checks for core booking and admin flows.
- Add automated accessibility checks in Playwright for public booking flows.
- Build a small set of html-first form primitives and ban `div`-as-control patterns in review.
- Tie route/pending UX improvements to the maintainability note about replacing global route feedback with localized boundaries.

## Related docs
- `docs/maintainability-priorities-2026-03.md`
- `docs/implemented-sports.md`
- `docs/implemented-payments.md`