Expense Registration Screen — WCAG 2.2 AA audit
epic-travel-expense-registration-ui-task-012 — Run a full WCAG 2.2 AA audit of the expense registration screen using the accessibility test harness. Verify focus traversal order, Semantics labels on all interactive controls, contrast ratios for all text and icon combinations, touch target sizes, and live-region announcements for error states and status changes. Fix all failures and document residual issues with justification.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 6 - 158 tasks
Can start after Tier 5 completes
Implementation Notes
Structure the audit in two passes: (1) automated pass using flutter_test Semantics assertions — run these as a dedicated test file `expense_registration_screen_a11y_test.dart`; (2) manual pass on device with VoiceOver. For contrast ratio checking, write a utility `contrast_check.dart` that imports AppColors design tokens and computes WCAG contrast ratios — this becomes a regression guard for future colour changes. Common issues to look for in this codebase: icon-only buttons without Semantics.label; custom gesture detectors without Semantics.onTap; TextField errorText that is visually shown but not announced to screen readers (set errorText on InputDecoration rather than a separate Text widget to get automatic announcement); step progress indicator with no semantic label. For any control that is visually obvious but lacks a programmatic label, add ExcludeSemantics only if the information is redundant — document the decision.
The audit report should be committed as `docs/a11y/expense-registration-screen-wcag22-audit.md`.
Testing Requirements
Automated: flutter_test with tester.getSemantics() assertions on every interactive widget in every step — verify label, hint, isButton, isTextField, isEnabled, isFocusable, liveRegion flags. Contrast ratio check: extract design token color values and calculate WCAG contrast ratios programmatically for all text/background combinations used in the screen (can be a Dart script). Touch target test: retrieve render box sizes for all tappable widgets and assert >= 44×44 dp. Manual: run through all steps on a physical iOS device with VoiceOver enabled and confirm all interactive elements are announced correctly and focus order is logical.
Use Xcode Accessibility Inspector to capture the final Semantics tree. Document every tested criterion in the audit report template.
The image_picker Flutter plugin requires platform-specific permissions (NSPhotoLibraryUsageDescription, camera permission) and behaves differently across iOS and Android versions. Permission denial or plugin misconfiguration can silently prevent receipt attachment.
Mitigation & Contingency
Mitigation: Configure all required permission strings in Info.plist and AndroidManifest.xml during initial plugin setup. Use the permission_handler package to check and request permissions before launching the picker, with clear user-facing explanations. Test on both platforms across at least two OS versions.
Contingency: If image_picker proves unreliable on a specific platform version, fall back to file_picker as an alternative that uses the OS document picker interface, which requires fewer permissions on some Android versions.
The expense form BLoC manages interconnected state across expense type selection, field visibility, receipt requirement, threshold evaluation, and submission flow. Incorrect state transitions can cause UI inconsistencies such as required receipt indicator not updating after amount change, or form appearing valid when mutual exclusion is violated.
Mitigation & Contingency
Mitigation: Model BLoC states as sealed classes with exhaustive pattern matching. Write state transition unit tests covering every combination of: type selection change, amount field change above/below threshold, receipt attachment/removal, and offline mode toggle. Use bloc_test for comprehensive state sequence assertions.
Contingency: If BLoC complexity becomes unmanageable, split into two BLoCs — one for type selection/exclusion state and one for field values/submission — coordinating via a parent provider, accepting the small overhead of inter-BLoC communication.
The expense type selector must enforce mutual exclusion visually by disabling options and showing conflict tooltips, while remaining fully accessible to screen reader users who cannot perceive visual disable states. Incorrect semantics labelling will fail WCAG 2.2 AA requirements critical for Blindeforbundet and HLF users.
Mitigation & Contingency
Mitigation: Use Flutter Semantics widgets to explicitly set disabled state and provide conflict explanations as semanticLabel strings on disabled options. Run accessibility audits with TalkBack and VoiceOver during widget development, not post-completion. Reference the project's accessibility test harness for required test coverage.
Contingency: If custom widget accessibility is difficult to certify, implement the selector as a standard Flutter Radio/Checkbox group with built-in accessibility semantics and an explanatory Text widget below each conflicting option, sacrificing visual elegance for guaranteed WCAG compliance.