ui-controls-accessibility

# ui-controls-accessibility

## Requested Outcome Gate

Before rendering, turn every explicitly requested workflow outcome into a compact ledger: `user outcome -> triggering control/event -> rendered state branch -> recovery/next action`. Success and failure are separate outcomes. When a backend is unavailable but the outcome can be modeled locally, make both outcomes reachable through the primary control flow with documented sample inputs or a deterministic local mock resolver. Preview controls may supplement this proof, but they must not be the only route to an ordinary product failure state. Use distinct preview controls only when no credible primary-flow trigger exists. Do not deliver while any requested outcome exists only in prose, an unreachable conditional, an ambiguous shared trigger, or a generic error state from a different step.

Use this specialist for complex forms, non-trivial composite widgets, accessibility audits, or control/state failures that need deeper guidance. Ordinary controls, focus, labels, and responsive behavior are covered by `ui-design-executor` and do not require loading this skill.

## Control Taxonomy

Use familiar controls for the job:

- Button: clear command.
- Icon button: familiar compact command, with tooltip or accessible label.
- Toggle or checkbox: binary setting.
- Radio group: mutually exclusive choice where every option should be visible.
- Segmented control: small mode set that changes a view or filter.
- Select or combobox: larger option set.
- Menu: secondary commands.
- Tabs: peer views with persistent context.
- Slider: continuous numeric adjustment.
- Stepper or numeric input: precise numeric adjustment.
- Table or grid: comparison and repeated scanning.
- Drawer: secondary workflow while preserving main context.
- Modal: blocking decision or short focused task.
- Tooltip: explain an icon or concise unfamiliar label, not required content.

Do not style decorative pills as controls unless they have standard keyboard and state behavior.

## Required States

Represent states that a real product would need:

- Default, hover, active/pressed, focus-visible, disabled.
- Selected/current for tabs, nav, filters, rows, and options.
- Empty, loading, success, warning, error.
- Validation for form fields.
- Permission or unavailable state when actions are gated.
- Mobile collapsed state for navigation, filters, and dense tables.

Do not add every state to every component. Add the states the workflow can actually reach.

State coverage is an implementation requirement, not a prose checklist. For a standalone prototype, put each critical state in real DOM or rendering logic and make it inspectable through the real workflow, a small preview-only state switcher, or a clearly labeled state gallery. Listing state names while shipping only the happy path does not count.

## Accessibility Checks

Minimum checks:

- Contrast: body text, muted text, controls, borders, focus rings, and semantic status.
- Keyboard: tab order, visible focus, Escape for popovers/modals, Enter/Space activation where expected.
- Composite widgets: tabs use `tablist`/`tab` semantics with `aria-selected`, roving focus, and Left/Right or Up/Down arrow-key movement as appropriate; menus, listboxes, and grids follow their expected keyboard model.
- Labels: every input and icon-only action needs a visible label, aria-label, or clear surrounding context.
- Target size: small controls need enough clickable area.
- Text scaling: labels and buttons must fit with realistic localized text.
- Motion: avoid critical information that appears only through animation; respect reduced-motion where practical.
- Status: do not rely on color alone.

## Responsive Rules

Define stable responsive behavior:

- Navigation may collapse; primary action remains reachable.
- Tables switch to horizontal scroll, column priority, or list cards depending on data shape.
- Filters collapse into a drawer or toolbar menu.
- Two-pane layouts become stacked or detail-over-list.
- Fixed-format UI such as boards, grids, tiles, and toolbars need stable dimensions.
- Text must wrap or truncate intentionally; it must not overlap controls.

Do not scale font size with viewport width. Use explicit type roles and breakpoints.

If the brief explicitly forbids horizontal scrolling or names a narrow target such as 320px, do not choose horizontal table/nav scrolling. Use column priority, stacked labeled rows/cards, wrapped navigation, and full-width actions so the primary workflow fits the viewport.

When 320px or long localized copy is explicit but preview tools are unavailable, delivery must still name the unrun viewport/text-fit check and its concrete pass criteria: `scrollWidth <= clientWidth`, all primary actions remain visible and reachable, and the longest supplied localized label/help text wraps without clipping or overlap.

## Form And Data Rules

Forms:

- Group related fields.
- Put helper/error text near the field.
- Show required/optional intent clearly.
- Use inline validation for recoverable errors.
- Implement the reachable lifecycle: pristine, dirty/touched invalid, submitted-pending with duplicate submission blocked, recoverable server/error feedback, and success. Do not show dirty validation on first render. Every outcome the user explicitly requests (for example import success and import failure) needs its own reachable trigger. With no backend, prefer documented sample inputs or a deterministic local mock resolver exercised by the normal submit action; preview actions are supplementary and must not replace the primary workflow. A conditional branch that is never called with one outcome is dead code and does not count.
- When a JavaScript parser is unavailable, avoid backslash regex shorthands in generated validators; use `[0-9]`, direct string checks, or `input.validity`. A no-backend prototype may use one explicit Success/Server failure selector, but the normal submit/import action must read it before mutati