Bufdir Preview Accessibility Utilities
Component Detail
Description
Utility functions and constants supporting WCAG 2.2 AA compliance specifically within the Bufdir preview feature. Provides contrast-checked colour tokens for the three validation states (normal, warning, anomaly), semantic label builders for field rows, and live-region helpers that announce validation issue count changes to screen readers.
bufdir-accessibility-utils
Summaries
The Bufdir Preview Accessibility Utilities ensure that the report preview feature is fully usable by staff members who rely on assistive technologies such as screen readers, meeting WCAG 2.2 AA compliance standards. Accessibility compliance is increasingly a legal and reputational requirement for organizations receiving public funding, and delivering a reporting tool that excludes users with disabilities would create significant risk. By embedding compliance at the utility level rather than retrofitting it later, this component reduces the cost and risk of accessibility audits, avoids potential accessibility-related complaints, and demonstrates organizational commitment to inclusive design — a value aligned with the social sector mission of the organizations using this platform.
The Bufdir Preview Accessibility Utilities have low complexity and no external dependencies, making them a safe early-sprint deliverable that unblocks accessible UI implementation across the preview feature. Because these utilities must be used consistently across all preview UI components, their API should be finalized and reviewed with the design team before the main preview screens are built — retrofitting accessibility after UI implementation is substantially more expensive. Testing requires both automated tooling (axe, Lighthouse) and manual screen reader testing (VoiceOver, TalkBack, NVDA), which should be budgeted into the QA timeline. The live-region announcement helpers in particular require manual testing to verify screen reader announcement timing and verbosity.
Low risk overall, but late integration of these utilities into UI components is a common delivery anti-pattern to watch for.
The Bufdir Preview Accessibility Utilities is a frontend and mobile utility module with zero external dependencies, designed to enforce WCAG 2.2 AA compliance within the report preview feature. `getValidationStateColor(state)` returns contrast-verified color tokens for the three validation states (normal, warning, anomaly) — these must meet a minimum 4.5:1 contrast ratio against all background variants used in the preview UI. `getValidationStateSemanticLabel(state, fieldLabel, issue)` constructs screen-reader-friendly label strings that communicate both the field identity and its validation state in a single announcement. `announceValidationChange(issueCount)` writes to an ARIA live region to notify screen reader users when the number of validation issues changes after data refresh.
`focusNextIssue(currentFieldKey)` implements keyboard navigation between flagged fields, requiring knowledge of the current DOM order of field keys — this should be driven by the same ordered field list exposed by the report structure mapper to ensure consistency.
Responsibilities
- Define WCAG 2.2 AA compliant colour tokens for validation states
- Build accessible semantic labels for field rows and section headers
- Provide live-region announcement helpers for dynamic issue count updates
- Supply focus management utilities for navigating between flagged fields
Interfaces
getValidationStateColor(state)
getValidationStateSemanticLabel(state, fieldLabel, issue)
announceValidationChange(issueCount)
buildSectionSemanticLabel(sectionTitle, issueCount)
focusNextIssue(currentFieldKey)