# Accessibility and Responsive Audit Notes

This document records the accessibility and responsive expectations for the integrated demo. It is intentionally practical: reviewers can use it as a release gate before sharing the build publicly.

## Accessibility standard for the demo

The demo should meet the spirit of WCAG 2.2 AA for the primary happy paths:

- collect an item;
- answer trivia;
- submit a prediction;
- review badges/challenges;
- review leaderboard position.

The demo does not need a formal third-party accessibility certification for this milestone, but it must avoid obvious blockers.

## Automated checks available

Run the existing unit/E2E checks from the README, then optionally run:

```sh
node scripts/qa/a11y-static-check.mjs
```

For machine-readable output:

```sh
node scripts/qa/a11y-static-check.mjs --format json
```

For a strict pre-release gate:

```sh
node scripts/qa/a11y-static-check.mjs --fail-on-warning
```

The static checker is dependency-free and focuses on regressions that frequently slip into prototypes:

- images missing `alt`;
- buttons or links without accessible names;
- form controls without labels;
- click-only `div`/`span` style controls;
- positive `tabIndex`;
- likely ARIA typos;
- missing document `lang` or mobile viewport metadata;
- SVG images without accessible names.

It complements, but does not replace, Playwright role-based tests and manual keyboard/screen-reader review.

## Manual accessibility checklist

### Page structure

Pass criteria:

- The app has one clear top-level heading.
- Major areas use semantic headings in order.
- Cards and panels do not rely on heading size alone to communicate hierarchy.
- The leaderboard uses readable row/group labels.

Review method:

1. Inspect the page with a screen reader rotor/landmark list if available.
2. Navigate by headings.
3. Confirm the page still makes sense without visual layout.

### Keyboard support

Pass criteria:

- All interactive controls are reachable with `Tab`.
- Focus is visibly obvious on every control.
- `Enter` and/or `Space` activate buttons.
- Focus order follows the visible reading order.
- Disabled controls are skipped or clearly communicated.
- No keyboard trap exists.

Review method:

1. Put the mouse aside.
2. Complete collection, trivia, prediction, and leaderboard review with keyboard only.
3. Confirm toast/status messages do not steal focus unexpectedly.

### Screen-reader status updates

Pass criteria:

- Trivia result is represented as text, not only color/icon.
- Badge unlocks and challenge completions are visible as text.
- Error messages are adjacent to or associated with the failed action.
- Loading states expose readable copy such as “Loading passport…”.

Review method:

1. Trigger a trivia answer.
2. Trigger a collect action.
3. Trigger an API failure.
4. Confirm a screen reader or DOM inspection can identify the status text.

### Forms and validation

Pass criteria:

- Prediction controls have visible labels or accessible labels.
- Validation errors explain the fix.
- Required fields are indicated in text, not only color.
- Error copy persists long enough to be read.

Review method:

1. Submit an incomplete prediction.
2. Submit an invalid score if score inputs are available.
3. Correct the error and resubmit.

### Color and contrast

Pass criteria:

- Text has sufficient contrast against card/background colors.
- Badge/challenge states are not communicated by color alone.
- Focus ring has visible contrast on dark and light surfaces.
- Disabled controls are still readable.

Review method:

1. Check mobile and desktop.
2. Use OS high-contrast mode if available.
3. Confirm success/error states include text or icon + label.

### Motion and animation

Pass criteria:

- Reward animations are brief and do not block action.
- No essential information is available only during animation.
- Reduced-motion users are not forced through large movement effects.

Review method:

1. Enable reduced motion in the OS/browser if available.
2. Trigger a badge/challenge completion.
3. Confirm the experience remains usable.

## Responsive audit

### Breakpoints to review

| Device class | Viewport | Required outcome |
| --- | ---: | --- |
| Small mobile | 375 × 667 | No horizontal scroll; primary cards stack; buttons are tappable. |
| Modern mobile | 390 × 844 | Dashboard, trivia, and prediction controls remain readable. |
| Tablet portrait | 768 × 1024 | Cards use available width without excessive whitespace. |
| Tablet landscape | 1024 × 768 | Leaderboard and challenge grids remain aligned. |
| Desktop | 1440 × 900 | Content width is comfortable; lines do not stretch excessively. |

### Responsive pass criteria

- Minimum tap target is approximately 44 × 44 CSS pixels for primary actions.
- Text does not overlap when team/stadium names are long.
- Leaderboard rows wrap or truncate gracefully with accessible full names still available.
- Prediction forms remain visible above the fold on mobile after validation errors.
- Loading skeletons/spinners do not cause large layout jumps.
- Empty states fit on mobile without hiding the next action.
- Toasts/banners do not cover bottom navigation or form submit buttons.

### Manual responsive script

1. Open browser devtools responsive mode.
2. Select each viewport in the table above.
3. Reload the app at that viewport.
4. Perform:
   - one collection;
   - one trivia answer;
   - one prediction submission;
   - one leaderboard review.
5. Confirm no horizontal scroll and no inaccessible hidden controls.
6. Capture screenshots for the release evidence folder or crowdfunding update.

## Known acceptable limitations for this milestone

The demo may use in-memory/local demo persistence rather than production authentication. That is acceptable if:

- the UI is honest about demo state;
- refresh persistence behaves as documented;
- test users cannot corrupt shared deployment data in a way that blocks the demo;
- reset/reseed instructions are available in the README or runbook.

## Release blocker definition

Treat any of the following as a blocker before a public demo:

- primary action is not keyboard reachable;
- collect/trivia/prediction status is communicated only by color;
- mobile layout prevents completing a primary action;
- API failure creates a permanent disabled button;
- repeated actions inflate XP or leaderboard rank;
- missing labels make prediction/trivia forms ambiguous to assistive technology.