@verndale/accessibility-standards 1.0.0

package/dist/profiles/ai-orchestration/implementation/accessibility.md

@@ -0,0 +1,329 @@
+<!-- GENERATED by @verndale/accessibility-standards; DO NOT EDIT -->
+# Accessibility implementation contract
+
+## semantics.accessible-name
+
+Every interactive or meaning-bearing control has a concise programmatic name derived from visible text when available.
+
+Proof: unit, axe, human.
+
+## semantics.alert
+
+Use alert semantics only for urgent, time-sensitive messages that require immediate announcement.
+
+Proof: unit, human.
+
+## semantics.consequential-action
+
+Legal, financial, destructive, or data-submitting actions support review, confirmation, or reversal as required.
+
+Proof: e2e, human.
+
+## semantics.data-table
+
+Tabular relationships use table markup with associated headers; interactive grids implement their full keyboard model.
+
+Proof: axe, e2e, human.
+
+## semantics.expanded-state
+
+Expandable controls expose aria-expanded and identify the controlled region when needed.
+
+Proof: unit, axe, e2e.
+
+## semantics.focus.initial
+
+On activation, focus moves to the deterministic target appropriate to the pattern.
+
+Proof: unit, e2e.
+
+## semantics.focus.return
+
+On dismissal, focus returns to the invoking control or a documented logical successor.
+
+Proof: unit, e2e.
+
+## semantics.focus.visible
+
+Keyboard focus is visible, sufficiently contrasted, and not fully obscured.
+
+Proof: e2e, human.
+
+## semantics.form-error
+
+Identify errors in text, associate them with fields, and provide correction guidance.
+
+Proof: unit, axe, e2e, human.
+
+## semantics.form-label
+
+Every form control has a persistent programmatically associated label.
+
+Proof: unit, axe.
+
+## semantics.form-required
+
+Requiredness is communicated visually and programmatically before submission.
+
+Proof: unit, axe.
+
+## semantics.headings
+
+Headings describe document structure without choosing levels for visual appearance.
+
+Proof: axe, human.
+
+## semantics.keyboard
+
+All functionality is operable with a keyboard without traps.
+
+Proof: e2e, human.
+
+## semantics.keyboard.escape
+
+Escape closes the topmost dismissible overlay without activating its trigger.
+
+Proof: unit, e2e.
+
+## semantics.landmarks
+
+Use native landmarks and name repeated landmarks only when a name is required to distinguish them.
+
+Proof: axe, human.
+
+## semantics.live-status
+
+Important asynchronous status updates are exposed through a correctly scoped, non-duplicative live region.
+
+Proof: unit, e2e, human.
+
+## semantics.media-alternatives
+
+Prerecorded media provides applicable captions, transcripts, and audio description.
+
+Proof: human.
+
+## semantics.motion-control
+
+Respect reduced-motion preferences and provide controls for moving or time-limited content where required.
+
+Proof: e2e, human.
+
+## semantics.name-role-value
+
+Expose the correct accessible name, role, value, and state through the platform accessibility API.
+
+Proof: unit, axe, human.
+
+## semantics.native-dialog
+
+Use dialog semantics with a programmatic name and modal state only when interaction is modal.
+
+Proof: axe, e2e, human.
+
+## semantics.native-elements
+
+Use the native HTML element whose semantics and behavior match the control before adding ARIA.
+
+Proof: axe, human.
+
+## semantics.non-text-alternative
+
+Meaningful non-text content has an equivalent alternative and decorative content is ignored by assistive technology.
+
+Proof: axe, human.
+
+## semantics.roles-states-properties
+
+Apply only valid ARIA roles, states, and properties and keep exposed state synchronized with rendered behavior.
+
+Proof: unit, axe, e2e.
+
+## semantics.selected-state
+
+Selection widgets expose current selection with the state required by their role.
+
+Proof: unit, e2e.
+
+## semantics.target-size
+
+Pointer targets meet 24 by 24 CSS pixels or a WCAG 2.5.8 exception; 44 by 44 is an enhanced recommendation.
+
+Proof: e2e, human.
+
+## pattern.accordion
+
+Requires: semantics.native-elements, semantics.accessible-name, semantics.expanded-state, semantics.keyboard, semantics.focus.visible.
+
+Behavior:
+- Toggle only the controlled panel
+- Preserve DOM and focus order
+
+Evidence: unit, axe, e2e, human.
+
+## pattern.alert
+
+Requires: semantics.alert.
+
+Behavior:
+- Announce once without moving focus
+
+Evidence: unit, human.
+
+## pattern.carousel
+
+Requires: semantics.accessible-name, semantics.keyboard, semantics.focus.visible, semantics.motion-control, semantics.live-status.
+
+Behavior:
+- Pause rotation on interaction
+- Provide named controls and current position
+
+Evidence: unit, axe, e2e, human.
+
+## pattern.combobox
+
+Requires: semantics.accessible-name, semantics.expanded-state, semantics.selected-state, semantics.keyboard, semantics.live-status.
+
+Behavior:
+- Keyboard controls popup, option, and input independently
+
+Evidence: unit, axe, e2e, human.
+
+## pattern.consequential-submission
+
+Requires: semantics.consequential-action, semantics.form-error, semantics.keyboard.
+
+Behavior:
+- Support review, correction, confirmation, or reversal
+
+Evidence: e2e, human.
+
+## pattern.dialog
+
+Requires: semantics.native-dialog, semantics.accessible-name, semantics.keyboard.escape, semantics.focus.initial, semantics.focus.return.
+
+Behavior:
+- Manage initial, contained, and return focus
+- Dismiss topmost dialog with Escape
+
+Evidence: unit, axe, e2e, human.
+
+## pattern.disclosure
+
+Requires: semantics.native-elements, semantics.accessible-name, semantics.expanded-state, semantics.keyboard.
+
+Behavior:
+- Control toggles one region
+
+Evidence: unit, axe, e2e.
+
+## pattern.dynamic-status
+
+Requires: semantics.live-status.
+
+Behavior:
+- Announce meaningful changes once
+
+Evidence: unit, e2e, human.
+
+## pattern.field
+
+Requires: semantics.form-label, semantics.form-required, semantics.focus.visible.
+
+Behavior:
+- Expose label, instructions, and requiredness before interaction
+
+Evidence: unit, axe, human.
+
+## pattern.image
+
+Requires: semantics.non-text-alternative.
+
+Behavior:
+- Alternative follows image purpose
+
+Evidence: axe, human.
+
+## pattern.listbox
+
+Requires: semantics.accessible-name, semantics.selected-state, semantics.keyboard, semantics.focus.visible.
+
+Behavior:
+- Arrow keys move active option
+- Selection follows declared model
+
+Evidence: unit, axe, e2e, human.
+
+## pattern.media-player
+
+Requires: semantics.media-alternatives, semantics.accessible-name, semantics.keyboard, semantics.focus.visible, semantics.motion-control.
+
+Behavior:
+- Provide keyboard-operable named controls and required alternatives
+
+Evidence: axe, e2e, human.
+
+## pattern.menu-button
+
+Requires: semantics.accessible-name, semantics.expanded-state, semantics.keyboard, semantics.focus.initial, semantics.focus.return.
+
+Behavior:
+- Open and navigate menu by keyboard
+
+Evidence: unit, e2e, human.
+
+## pattern.pagination
+
+Requires: semantics.native-elements, semantics.accessible-name, semantics.landmarks, semantics.focus.visible.
+
+Behavior:
+- Expose current page and named navigation
+
+Evidence: unit, axe, human.
+
+## pattern.popover
+
+Requires: semantics.native-elements, semantics.accessible-name, semantics.keyboard.escape, semantics.focus.return.
+
+Behavior:
+- Dismiss without trapping focus
+
+Evidence: unit, e2e, human.
+
+## pattern.progress
+
+Requires: semantics.name-role-value, semantics.live-status.
+
+Behavior:
+- Expose value and completion changes without announcement noise
+
+Evidence: unit, axe, human.
+
+## pattern.tabs
+
+Requires: semantics.accessible-name, semantics.selected-state, semantics.keyboard, semantics.focus.visible.
+
+Behavior:
+- Arrow keys move between tabs
+- Selection and activation follow the documented model
+
+Evidence: unit, axe, e2e, human.
+
+## pattern.tooltip
+
+Requires: semantics.accessible-name, semantics.keyboard.escape.
+
+Behavior:
+- Available on hover and focus
+- Never contains interactive content
+
+Evidence: unit, e2e, human.
+
+## pattern.validation
+
+Requires: semantics.form-error, semantics.live-status, semantics.focus.initial.
+
+Behavior:
+- Identify, associate, summarize, and focus errors deterministically
+
+Evidence: unit, axe, e2e, human.