# Accessibility and Keyboard Rules

This document defines the minimum accessibility and keyboard-interaction rules for `qt-material3-widgets`.

## Core rules

- Keyboard focus must be visible and distinct from hover.
- Buttons and selection controls must be reachable with Tab and activatable with Space/Enter where appropriate.
- Dialogs must support Escape to close when that matches the widget contract.
- Text fields must delegate text editing behavior to `QLineEdit` or another Qt editor primitive.
- Accessible names should come from visible labels or button text when the user has not set one explicitly.
- Accessible descriptions should prefer error text over supporting text when an error state is active.

## Family rules

### Buttons
- Derive semantics from `QAbstractButton`.
- Keep `StrongFocus` unless a widget intentionally opts out.
- Do not hide the focus ring on keyboard focus.

### Selection controls
- Must remain checkable and keyboard-toggleable.
- Checked state must be reflected consistently in interaction state and accessible semantics.

### Dialogs
- Should take focus on open.
- Should move focus to a reasonable child when one exists.
- Should support Escape close unless the widget explicitly documents a different behavior.

### Text fields
- Must expose the label as the accessible name when possible.
- Should expose supporting text or error text as the accessible description.
- Should use the hosted line edit as the focus proxy.