# Accessibility (a11y) & WCAG

`@ktbsh/ui` components must be **accessible from the first version**, not bolted on later.

## Target

| Aspect / standard | Requirement / target |
|-------------------|----------------------|
| **WCAG 2.2** | **AA** (minimum for all shipped interactive components) |
| **APG patterns** | Follow [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/) where a pattern exists (dialog, combobox, tabs, …) |
| **Keyboard** | Full operation without a pointer |
| **Screen readers** | Correct name, role, value/state; no silent custom elements |

**Product copy** (visible labels, error messages, helper text) is the **consumer application’s** responsibility unless a component ships default English chrome by design (then document and keep overridable).  
This library owns **structure, roles, keyboard, focus, and state exposure**. The SDK only provides platform hooks (`formAssociated`, events).

## Non-negotiable component checklist

Every interactive component PR must cover:

1. **Semantics** — correct native element inside shadow when possible (`button`, `input`, `a`); otherwise correct ARIA role + states.
2. **Name** — accessible name via slot text, `<label>` association, `aria-label` / `aria-labelledby` props (documented).
3. **Keyboard** — Tab/Shift+Tab order; Enter/Space for buttons; Escape where dismissible; arrow keys for composite widgets per APG.
4. **Focus** — visible `:focus-visible` (tokenized ring); `delegatesFocus` when the host should forward focus to the control.
5. **Disabled / busy** — not focusable traps; `aria-disabled` / native `disabled` as appropriate; no click when disabled.
6. **States** — invalid, expanded, selected, pressed, checked exposed to AT (`aria-*` or native).
7. **Contrast** — text/icons meet WCAG AA against their backgrounds in **light and dark** themes (use semantic color tokens; do not invent low-contrast greys).
8. **Motion** — respect `prefers-reduced-motion` for non-essential animation (when motion exists).
9. **Forms** — associate labels; error text linked with `aria-describedby` / `aria-errormessage` when we ship Field/Label patterns.
10. **Hit target** — interactive controls aim for **≥ 24×24 CSS px** (WCAG 2.2 Target Size AA) unless an exception applies.
11. **Focus not obscured** (2.4.11) — overlays (modal, menu, popover) must not fully hide the focused control; manage focus when opening/closing.
12. **Dragging** (2.5.7) — any drag-only interaction must also have a single-pointer / keyboard alternative.
13. **Focus appearance** (2.4.13) — focus indicator (e.g. `--kb-focus-ring`) aims for **≥ 3:1** contrast against adjacent colors in light and dark.

## Tokens & themes

- Semantic colors must be choosable so **fg on bg** pairs can meet AA (document known pairs in Storybook later).
- Focus ring uses a dedicated token (`--kb-focus-ring`) and remains visible in both themes.
- Never remove focus outlines without an equal-or-better visible indicator.

## Testing (per component)

| Layer | Expectation |
|-------|-------------|
| **Unit / runtime** | Critical a11y-related behavior (e.g. `aria-invalid`, disabled, open/close) |
| **Storybook** | Stories for keyboard/focus states; a11y addon when Storybook lands |
| **Manual** | Keyboard-only pass; spot-check with a screen reader for complex widgets |
| **CI** | Prefer automated axe (or equivalent) on Storybook/static stories once Storybook exists |

## Authoring rules (kitbash)

- Prefer **native** elements inside the shadow tree for built-in a11y.
- Do not put interactive controls only in light DOM without a clear pattern.
- `render` / `events` still obey SDK serialization rules (no outer closures).
- Document required props for a11y (e.g. `label`, `aria-label`) in Storybook — not a second copy in README.

## Explicit non-goals (until scoped)

- Full AAA for all content (strive where cheap; AA is the gate).
- Replacing consumer apps’ page-level landmarks / skip links (document how to compose them).
- Automated contrast CI for every token pair on day one (add when token set stabilizes).

## References

- [WCAG 2.2](https://www.w3.org/TR/WCAG22/)
- [ARIA APG](https://www.w3.org/WAI/ARIA/apg/)
- Design architecture: `docs/superpowers/specs/2026-07-19-kitbash-ui-design-system-design.md`
- Agent process: `AGENTS.md`