# Accessibility Test Suite

## Objective

Make accessibility checks part of normal development rather than an audit before launch.

Automated accessibility checks over components and pages, paired with a defined set of manual keyboard and screen reader passes.

## Before You Begin

This feature is being added to an application that already exists and already
works. Do not scaffold a new project, and do not assume a blank slate.

Inspect the codebase first and establish:

- The existing application structure and where code of this kind already lives.
- The framework and version in use.
- The existing design system — colours, spacing, typography, and component conventions.
- Existing UI components you can reuse instead of writing new ones.
- The existing database structure, if this feature needs to persist anything.
- The existing authentication and authorization system, if this feature is user-scoped.
- Dependencies already installed, so you don't add a library that duplicates one.
- The existing test setup and conventions.

Only start writing code once you understand the above. If the application
already implements part of this feature, extend it rather than replacing it.

## Implementation Instructions

1. Run automated checks against both isolated components and assembled pages, because contrast and naming failures show up in components while landmark, heading order, and duplicate-label failures only appear once the page is built.
2. Write scripted keyboard passes for the flows that matter: tab through the whole flow, operate every control without a pointer, confirm focus is visible at each step, and confirm focus returns sensibly when a dialog closes.
3. Test components in their open, loading, error, and disabled states rather than only their resting state, since a dialog that traps focus correctly when open may leave focus stranded when it closes on an error.
4. Record any known violation as a dated, owned exception with a stated reason and a review date, and fail the run when an exception passes that date rather than letting it become permanent.
5. Broader visual review — hierarchy, spacing, copy, and responsive behaviour — belongs to the Design QA Checklist; this brief owns the machine-checkable and keyboard-checkable half. Do not duplicate the checklist's judgement items as automated assertions.

## UI and UX Requirements

Match the application's existing design system exactly. Reuse its components,
spacing, and typography. This feature should look like it was always there.

## Responsive Requirements

Works on mobile, tablet, and desktop. Touch targets are large enough to hit on a
phone, and nothing overflows horizontally at 320px.

## Accessibility Requirements

- Fully keyboard navigable.
- Correct semantic elements and ARIA roles.
- Visible focus states.
- Meets WCAG AA contrast.
- Dynamic changes are announced to screen readers.
- Respects prefers-reduced-motion.

## Edge Cases

- An automated pass covers only a fraction of real accessibility barriers, so a green run must never be reported as an accessibility guarantee — pair it with the manual passes and say plainly what was not checked.
- Components hidden behind an interaction go untested unless the suite opens them, so menus, dialogs, tooltips, and expanded rows must be driven into their open state before being checked.
- Loading and error states are where accessible names and live-region announcements are most often missing, and they are the states least likely to be present when a check runs against a resting component.
- An exception with no expiry becomes a permanent silence; every suppression needs an owner, a reason, and a date at which it is reconsidered.
- Checks running against a component in isolation will report missing landmarks and heading structure that the surrounding page actually provides, so those rules belong to the page-level run only.
- Colour contrast depends on the rendered theme, so a suite that only tests one theme misses every contrast failure in the other.
- A check that fails intermittently because the page had not settled will be disabled rather than fixed; wait for a visible, stable outcome before asserting.

## Testing

Exercise the feature end to end in the running application. Cover every edge case
above, then run the existing test suite and confirm nothing regressed.

## Acceptance Criteria

- [ ] Automated checks run against both components in isolation and fully assembled pages, in every supported theme.
- [ ] Scripted keyboard passes cover each major flow end to end, including focus visibility and focus return after a dialog closes.
- [ ] Open, loading, error, and disabled states are exercised, not only resting states.
- [ ] Every suppressed violation has a named owner, a written reason, and a review date, and the run fails once that date passes.
- [ ] The reported result states which checks are automated and which require a human, rather than presenting a passing run as full coverage.
- [ ] No check in the suite fails intermittently on an unchanged codebase.
- [ ] The feature matches the existing design system.
- [ ] No existing functionality is broken.

## Adaptation Rules

- Match the existing design system. Do not introduce a new colour palette,
  spacing scale, or component library.
- Reuse existing components and utilities wherever they fit.
- Follow the naming, file layout, and code style already present.
- Do not upgrade, replace, or remove existing dependencies to make this
  feature fit. Adapt the feature to the app, not the app to the feature.
- Do not break existing functionality. If a change is genuinely required in
  existing code, make the smallest one that works and say so.
- If something in these instructions conflicts with how the application is
  built, follow the application and explain the deviation.

## Final Verification

Before you report the work as done:

1. Re-read the acceptance criteria above and check each one against what you
   actually built.
2. Run the application and exercise the feature end to end.
3. Run the existing test suite and confirm you have broken nothing.
4. Check the feature on mobile, tablet, and desktop widths.
5. Check keyboard navigation and focus handling.
6. Summarize what changed: files added, files modified, and anything you
   deliberately did differently because of how this application is built.

If any acceptance criterion is unmet, fix it before reporting completion.