WCAG 2.2 AA contrast and label audit for AppTextField
epic-email-password-login-ui-task-002 — Audit and update the shared AppTextField widget to meet WCAG 2.2 AA requirements: label contrast ratio ≥4.5:1, placeholder text contrast ≥3:1, focus indicator visible at ≥3:1, and associated label via Semantics or InputDecoration.labelText. Document any design token changes required in contrast-safe-color-palette.
Acceptance Criteria
Technical Requirements
Implementation Notes
Start with a colour audit spreadsheet or inline comments listing each current token value and its measured contrast ratio against the design background (#121212 dark / #FFFFFF light). Tools: use the WebAIM Contrast Checker or the Colour Contrast Analyser desktop app with the exact hex values from the design token file. Prioritise fixing label and error text first (both are ≥4.5:1 requirement) before placeholder (≥3:1). The focus indicator fix often only requires increasing focusedBorder width to 2px and ensuring the border colour token meets the non-text contrast threshold.
Blindeforbundet users rely heavily on screen readers and high-contrast modes, making this a critical accessibility requirement across all three organisations. Coordinate with the design token owner before changing colour values to ensure the palette update is reflected in Figma as well.
Testing Requirements
Widget tests: assert that AppTextField renders with a non-empty labelText or has a Semantics ancestor with a meaningful label. Use flutter_test's SemanticsController to verify each field has an accessible label in the semantics tree. Golden tests: update existing AppTextField golden snapshots after colour token changes to lock in the new accessible appearance. Manual verification step (documented in PR): run the app on a device with accessibility settings → Increase Contrast enabled and confirm fields remain legible.
Use an online contrast checker (e.g., WebAIM) or the Flutter accessibility_tools package to measure ratios during development.
Automated accessibility checks (e.g., flutter_accessibility_service) may pass while manual VoiceOver/TalkBack testing reveals focus-order issues, missing semantic roles, or live region announcements that fire too early or not at all. Discovering these late risks delaying the MVP release.
Mitigation & Contingency
Mitigation: Conduct manual VoiceOver and TalkBack testing on physical devices at the end of every sprint, not only at release. Define accessibility acceptance criteria per component and include them in the DoD. Use Semantics widgets explicitly rather than relying on implicit semantics from Flutter's default widgets for all interactive elements.
Contingency: Maintain a prioritized accessibility bug backlog separate from the main backlog. If critical VoiceOver issues are found close to release, create an explicit accessibility hotfix sprint before TestFlight distribution to Blindeforbundet testers.
Keyboard height varies significantly between iOS and Android, between device sizes (iPhone SE vs iPad), and with third-party keyboards. The KeyboardAwareLayout may not correctly adjust scroll offset in all combinations, causing input fields to remain hidden behind the keyboard on certain device/keyboard configurations.
Mitigation & Contingency
Mitigation: Test on a matrix of devices including iPhone SE (small viewport), a mid-size Android phone, and a tablet. Implement the layout using MediaQuery.viewInsets.bottom rather than a fixed padding value to correctly respond to any keyboard height. Include edge cases for floating keyboards on iPads.
Contingency: If device-specific issues are found after release, implement a bottom-padding fallback using BottomPadding inset and allow users to manually scroll. Log affected device/OS combinations for targeted fixes.
If the design token system's colour palette is updated without re-running contrast validation, form field labels, error messages, or placeholder text could fall below the WCAG 2.2 AA 4.5:1 ratio, causing a compliance regression.
Mitigation & Contingency
Mitigation: Integrate a contrast ratio validator (e.g., a CI lint step using the contrast-ratio-validator component) that checks all colour pairs used in the login form on every pull request. Document which token pairs are used for labels, errors, and backgrounds in the login form.
Contingency: If a contrast regression is detected post-merge, hot-patch the affected design token value. Do not ship a TestFlight build with known WCAG AA failures to Blindeforbundet testers.