references/input-accessibility.md

# Windows input and accessibility baseline

## Contents

1. Input parity
2. Keyboard and focus
3. Mouse, touch, pen, and drag
4. UI Automation semantics
5. Visual and cognitive accessibility
6. Status, errors, and timing
7. Accessibility test matrix
8. Official sources

## 1. Input parity

Make every primary scenario possible with keyboard alone. Pointer hover, right-click, touch swipe, pen barrel button, drag-and-drop, and gestures may accelerate a task but must not be the only way to complete it.

Use standard controls first because they already implement much of the focus, keyboard, pointer, touch, and UI Automation behavior. For every custom control, define:

- automation role, name, value, state, and supported patterns;
- tab-stop and inner arrow-key behavior;
- keyboard activation and Escape behavior;
- pointer cursor, hover, press, and context menu behavior;
- touch target, manipulation threshold, and gesture alternative;
- focus visuals, selected visuals, and high-contrast rendering.

## 2. Keyboard and focus

- Put actionable elements in the tab sequence; keep labels and decorative elements out.
- Match tab order to visual and reading order. Prefer natural XAML order and use `TabIndex` only to correct a demonstrated issue.
- Use arrow keys inside composite controls such as lists, menus, radio groups, tabs, and grids.
- Set initial focus to the most useful safe element when a window, page, dialog, or task surface opens.
- Return focus to the invoker when a flyout or dialog closes. After deletion, move focus to a predictable adjacent item or stable container.
- Keep the platform focus visual visible. Do not encode focus only through a subtle color change.
- Use access keys for visible commands and form navigation; use keyboard accelerators for frequent or standard actions.
- Show accelerators in menus and tooltips where users learn commands.
- Allow Escape to close dismissible UI or cancel the current transient mode. Do not discard unsaved work silently.
- Ensure Enter and Space activate controls according to standard control behavior; do not invent conflicting key semantics.

Use familiar shortcuts only when the command truly has the familiar meaning:

| Shortcut | Expected meaning |
|---|---|
| `Ctrl+N` | new item/document/window as appropriate |
| `Ctrl+O` | open |
| `Ctrl+S` | save |
| `Ctrl+Z` / `Ctrl+Y` or `Ctrl+Shift+Z` | undo / redo, consistent with the app domain |
| `Ctrl+F` | search or find |
| `F5` | refresh when refresh is meaningful |
| `Delete` | delete selected item, with undo or confirmation based on consequence |
| `Alt+Left` | back when the app has navigation history |
| `F6` | move between major panes in complex workspaces |

Do not override operating-system or assistive-technology shortcuts.

## 3. Mouse, touch, pen, and drag

### Mouse and pointer

- Use hover to preview or accelerate, never to hide the only route to a command.
- Provide a context menu for object-specific commands; expose frequent commands visibly as well.
- Use tooltips for unfamiliar icons, truncated content, and shortcut education—not for essential instructions.
- Keep selection and focus visually distinct in dense lists and grids.
- Preserve target position during hover and press; avoid geometry changes that make the pointer chase a control.

### Touch and pen

Use platform controls at their default size where possible. For custom targets, meet the Windows touch baseline:

- target at least 40 × 40 epx, even if the visible glyph is smaller;
- a 32 epx-tall target can be acceptable when it is at least 120 epx wide;
- for touch-optimized experiences, prefer 44 × 44 epx with at least 4 epx visible separation;
- enlarge frequent or high-consequence targets beyond the minimum;
- do not place destructive targets tightly beside routine actions.

Support mouse precision without making touch impossible. Make scrolling, zoom, selection, and pen input coexist without gesture conflicts.

### Drag and drop

Show a clear drag affordance, valid targets, insertion position, forbidden states, and completion feedback. Use a movement threshold to prevent accidental drags. Always provide keyboard and menu commands such as Move up/down, Move to, Attach, or Import for critical drag operations.

## 4. UI Automation semantics

Accessible names must be concise, unique enough in context, and action-oriented for commands.

- Let standard controls promote visible text when that produces the correct name.
- Set `AutomationProperties.Name` explicitly for icon-only buttons, meaningful images, custom-drawn content, ambiguous repeated controls, or controls whose visible text does not describe the action.
- Associate form labels with fields through `AutomationProperties.LabeledBy` where applicable.
- Put supplemental instructions in help text or accessible descriptions; do not stuff them into the name.
- Expose selection, checked, expanded, pressed, read-only, required, invalid, busy, and disabled states through the correct control or automation peer.
- Mark decorative images and duplicate glyphs so they do not create noise.
- Implement the appropriate UI Automation patterns for custom controls; an accessible name alone is insufficient.

Do not add an explicit name to every control mechanically. Duplicate or stale names can make the screen-reader experience worse.

## 5. Visual and cognitive accessibility

- Maintain at least 4.5:1 text contrast in the normal light and dark themes.
- Test high contrast; do not use a high-contrast theme as a substitute for adequate normal-theme contrast.
- Pair color with text, shape, icon, position, or pattern for errors, selection, and status.
- Preserve visible focus, current selection, and input validation at all theme states.
- Support Windows text-size settings and display scaling without clipped text, inaccessible controls, or lost commands.
- Prefer wrapping and adaptive height to truncation. Test long localized strings, narrow windows, and right-to-left layout when the product supports such locales.
- Use plain, specific writing. Put the decision or recovery action first; avoid blame and error codes without explanation.
- Avoid flashing and nonessential repetitive animation. Respect system animation preferences and keep interaction possible while motion runs.
- Provide captions or transcripts for meaningful audio/video and text alternatives for informative graphics.

## 6. Status, errors, and timing

Announce important asynchronous state changes without stealing focus. Use a suitable live-region or standard control behavior for loading completion, errors, and background status.

Error feedback must answer:

1. What failed?
2. What user work was preserved?
3. What can the user do now?

Place field errors near the field and summarize multiple errors at the task level when useful. Move focus only when it helps recovery, such as focusing the first invalid field after submit.

Do not auto-dismiss critical errors. Give users enough time to read transient status, pause time limits when feasible, and provide a persistent history for important background operations or notifications.

## 7. Accessibility test matrix

- [ ] Complete primary flows with keyboard only.
- [ ] Verify logical Tab, Shift+Tab, arrow, Enter, Space, Escape, access-key, and accelerator behavior.
- [ ] Test Narrator reading order, names, roles, values, states, and live announcements.
- [ ] Inspect the UI Automation tree with Accessibility Insights for Windows or Inspect.
- [ ] Test light, dark, and at least one high-contrast theme.
- [ ] Measure text contrast and verify that color is not the only cue.
- [ ] Test Windows text-size changes, display scale changes, Magnifier, and narrow windows.
- [ ] Test mouse, touch when supported, context menus, and alternatives to drag/hover.
- [ ] Check long strings, localization expansion, and any supported right-to-left language.
- [ ] Add automated accessibility checks for critical screens and flows where the test stack supports them.

## 8. Official sources

- [Accessibility checklist for Windows apps](https://learn.microsoft.com/windows/apps/design/accessibility/accessibility-checklist)
- [Keyboard interactions](https://learn.microsoft.com/windows/apps/develop/input/keyboard-interactions)
- [Guidelines for touch targets](https://learn.microsoft.com/windows/apps/develop/input/guidelines-for-targeting)
- [Touch interactions](https://learn.microsoft.com/windows/apps/develop/input/touch-interactions)
- [Accessible text requirements](https://learn.microsoft.com/windows/apps/design/accessibility/accessible-text-requirements)
- [Accessibility testing](https://learn.microsoft.com/windows/apps/design/accessibility/accessibility-testing)