mirror of
https://github.com/storytold/craft-contrib.git
synced 2026-11-19 09:01:31 +01:00
* RFC-0014: Accessibility in every UI chang * RFC-0014: manual tests never block; platform checks; owner, RFC-0007 - A screen-reader test is never a condition for merging. The needs screen reader test label is for accessibility fixes and for accessibility logic an app builds itself, not for every UI PR. - CI reads the running app through the platform's accessibility API with standard tools (UI Automation on Windows), so contributors never install a screen reader. - The kittest requirement doesn't block review until the shared helpers exist. - Owner and review check (CodeRabbit path instructions), and how the priority rule sits on RFC-0007's levels. * RFC-0014: the rules in standards/, the AGENTS.md text as its own block craftrules is retired, so the rules are standards/accessibility.md here, which also answers the first open question. The appendix becomes standards/house-rules-accessibility.md, a generated block like the Rust rules, because the core block has no room for it. Point 10 says where each part goes and what the house-rules check needs. The README lists both files.
2.8 KiB
2.8 KiB
Accessibility
These apply to native Craft apps and to shared libraries that draw interface. The source is standards/house-rules-accessibility.md in storytold/craft-contrib. The full rules are standards/accessibility.md.
People use the apps with screen readers, braille displays, magnifiers, high contrast, large text, voice control or only a keyboard. They reach the interface only through its AccessKit tree, keyboard focus and colours. A UI change is not done until it works for them. The bar is WCAG 2.2 AA as applied to software.
- Design first. Name the pattern (menu, tab list, toolbar, tree, grid, list, dialog, slider, canvas) and follow its keyboard model and roles from the WAI-ARIA Authoring Practices Guide and the platform's guidelines. Observe how the reference app exposes it with Accessibility Insights, Accessibility Inspector or Accerciser.
- Keyboard. Every action works from the keyboard, in visual order, with no trap. Esc closes and returns focus. Alt or F10 and F6 behave as on the platform. Move egui's focus (
request_focus), never only a highlight. - Semantics. Every control has a role, a translated name that starts with its visible label, and its state and value. Shortcuts and access keys are set on the node, in the current platform's form. A drawn surface publishes nodes for its content, with caret, selection and correct editability.
- Feedback. Announce changes away from focus through a live region.
- Seeing. Contrast at least 4.5:1 for text and 3:1 for controls and focus, in both themes. Never colour alone. Follow the system's high contrast, text size and reduced motion settings.
- Pointer. Anything done by dragging can be done without dragging.
- Check the tree, not only the screenshot. Each new or changed control, dialog or keyboard path gets a kittest test that drives it by keyboard and asserts roles, names, states, focus and announcements. If the helpers do not exist yet, say so in the pull request. Keep
with_accessibility_checkon and CI's platform checks green. Withui.screenshot, also read the accessibility tree. - Rule out known failures: focus left in the document behind a menu, ribbon or KeyTips; editable surfaces reported read-only; dialogs that do not take or return focus, or leave controls behind them reachable; painted rows with no node; identical names; another platform's shortcut text in a name; silent state changes; drag-only actions.
- Be honest in the pull request. Its Accessibility section says what the tests and the tree cover. Tree tests never prove "works with screen readers". Ask for
needs screen reader testonly for an accessibility fix or accessibility logic of its own, and never hold a pull request back for that test.