WCAG 2.2 AA accessibility audit for form engine
epic-structured-post-session-report-form-engine-task-014 — Perform a systematic WCAG 2.2 AA accessibility audit of all form engine widgets: DynamicFieldRenderer, WayForwardSectionWidget, and SpeechToTextFieldOverlay. Verify with VoiceOver (iOS) and TalkBack (Android): correct semantic labels on all fields, live region announcements for recording state, focus order follows visual order, no keyboard trap in overlays, touch targets ≥44×44dp, contrast ratio ≥4.5:1 for all text. Document findings and fix all critical and serious violations before epic sign-off.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 4 - 323 tasks
Can start after Tier 3 completes
Implementation Notes
This task is split: ~3h audit (device + automated) and ~5h fixing violations. Common Flutter accessibility pitfalls to check: (1) Icon buttons missing Semantics label — fix with Semantics(label: '...', child: IconButton(...)). (2) Custom widgets not inheriting Semantics from children — fix by ensuring MergeSemantics or ExcludeSemantics is used correctly. (3) Live region not firing — in Flutter, set SemanticsProperties(liveRegion: true) on the container that changes, not a static parent.
(4) Bottom sheet focus trap: verify that FocusScope wraps the sheet and that the first focusable element receives focus on open. (5) Color contrast: check design token values for error red, status badge colors, and placeholder text against all background colors using the WebAIM contrast checker. For the Blindeforbundet-specific requirement: recording state announcements are especially critical — this organization has visually impaired users for whom VoiceOver is primary input.
Testing Requirements
Two-track testing: (1) Automated: flutter_test Semantics assertions verifying every field has a non-empty label, error fields have error semantics set, live region is present on recording state widget. Use tester.getSemantics(find.byType(X)) and verify SemanticsData properties. (2) Manual: device testing on a physical iPhone (VoiceOver) and physical Android (TalkBack). Use a structured manual test script covering: full form navigation, error state navigation, overlay focus trap check, and recording state announcement.
Document manual test results in a checklist. Both tracks must pass before task closure.
Dynamically rendered form fields built from runtime JSON schema are significantly harder to make accessible than statically declared widgets — Flutter's Semantics tree must be correct for every possible field type and every validation state. Failures here block the entire feature for Blindeforbundet's visually impaired peer mentors.
Mitigation & Contingency
Mitigation: Define WCAG 2.2 AA semantics requirements for each field type before implementation and write widget tests using Flutter's SemanticsController for every type. Include a real-device VoiceOver test session in the acceptance gate for this epic before marking it done.
Contingency: If dynamic semantics prove too difficult to get right generically, implement field-type-specific Semantics wrappers (one per supported field type) instead of a single generic renderer, accepting slightly more code duplication in exchange for reliable accessibility.
The report-form-orchestrator must manage a complex state machine — schema loading, draft persistence, per-field validation, submission retries, and error recovery — across multiple async operations. Incorrect state transitions could result in lost user data, double submissions, or UI freezes.
Mitigation & Contingency
Mitigation: Define all Bloc states and events explicitly as sealed classes before writing any logic. Use a state machine diagram reviewed by the team before implementation. Write exhaustive Bloc unit tests covering every state transition, including concurrent events and network interruption mid-submission.
Contingency: If Bloc complexity becomes unmanageable, extract draft persistence into a separate DraftManagerCubit and keep report-form-orchestrator focused solely on the submit workflow. The additional granularity makes each component independently testable.
Organisations may require field types beyond the five currently specified (text, multiline, checkbox group, radio, date). If a new type is discovered during pilot testing, the dynamic-field-renderer must be extended, potentially requiring changes across multiple layers.
Mitigation & Contingency
Mitigation: Design dynamic-field-renderer as a registry of field-type renderers with a clear extension point. Document the pattern for adding a new field type so that it can be done in one file without touching existing renderers.
Contingency: If an unhandled field type is encountered at runtime, dynamic-field-renderer renders a labelled plain-text fallback widget and logs a warning so the missing type is surfaced in monitoring, preventing a crash while making the gap visible.