# Accessibility Plan

Mechanica targets WCAG AA contrast and full keyboard access for all DOM controls. The 3D canvas is inherently visual, so every machine must also expose structured text, part lists, facts, and guided-tour captions outside the canvas.

## Principles

1. All interactive DOM controls are native buttons, links, inputs, or selects.
2. Visible focus states are mandatory.
3. Reduced-motion preferences are honored.
4. Color is never the only indicator of state.
5. Engineering values use readable labels and tabular numerals.
6. Canvas interactions have equivalent sidebar controls where possible.

## Implemented foundation

- Skip link to main content.
- Semantic navigation and main landmarks.
- Search form with `role="search"`.
- Buttons use `aria-pressed` where stateful.
- Inputs and selects have explicit labels.
- Favourite buttons have machine-specific `aria-label`.
- Viewer panels use headings and grouped controls.
- Detail drawer exposes selected part text and specs.
- Route transitions use reduced-motion-aware timing.
- Theme tokens maintain high contrast in dark mode.
- Focus-visible rings are defined globally.

## Keyboard behavior

Current and planned keyboard controls:

| Area | Keys |
| --- | --- |
| Top navigation | Tab/Shift+Tab, Enter |
| Catalogue filters | Tab/Shift+Tab, Arrow keys in selects |
| Machine cards | Tab to card link and favourite button |
| Component list | Tab to part rows and sliders |
| Playback controls | Tab, Enter/Space |
| Sliders | Arrow keys, PageUp/PageDown where browser-supported |
| Camera presets | Tab, Enter/Space |

Future canvas keyboard controls should include:

- Arrow keys to orbit selected preset camera.
- `+` / `-` to zoom.
- `R` reset camera.
- `Space` play/pause.
- `[` / `]` step cycle.
- `X`, `Y`, `Z` clipping axis shortcuts.

## Reduced motion

Current handling:

- Route transitions reduce to zero-duration when the user prefers reduced motion.
- The animation contract includes a `reducedMotion` flag for future model controllers.

Future handling:

- Disable auto-playing guided tours by default for reduced-motion users.
- Replace rapid mechanical motion with stepped or slow explanatory motion.
- Avoid flashing combustion/highlight effects.

## Canvas accessibility

Canvas should not be the only source of information. Each machine route includes:

- Part list.
- Part descriptions.
- Engineering facts.
- Status bar.
- Guided-tour text model in registry.

Production viewer improvements:

- Add an off-screen live region for selected part changes.
- Add keyboard-driven part selection.
- Add a text-only "How it works" transcript view.
- Add captions for every guided-tour step.

## Contrast targets

Dark theme tokens are designed around:

- Background: `#0B0E14`
- Panel: `#121721`
- Primary text: near-white
- Muted text: cool gray with AA contrast on panel
- Accent: `#4C8DFF`
- Warm highlight: `#FFB04C`

Any new token must be checked against the background and panel surfaces before use.

## Testing checklist

Before release:

1. Navigate catalogue and viewer using keyboard only.
2. Verify focus order in desktop, tablet, and mobile layouts.
3. Test with `prefers-reduced-motion`.
4. Test with Windows High Contrast Mode where possible.
5. Run a screen reader pass for catalogue cards, filters, controls, and selected part drawer.
6. Verify color contrast for all text sizes.
7. Confirm copy-link workflow has non-color feedback.