Cognitive Accessibility Audit Utility
Component Detail
Description
Development-time utility that inspects widget trees and route configurations for cognitive accessibility violations. Runs as a Flutter test helper and as an optional debug overlay. Reports violations such as missing labels, icon-only buttons, wizard steps exceeding five, and missing back navigation.
cognitive-accessibility-audit
Summaries
The Cognitive Accessibility Audit Utility is a development-time safeguard that prevents the app from shipping with user interface patterns known to cause confusion, abandonment, or errors among users with cognitive disabilities or lower digital literacy. By automatically detecting issues such as icon-only buttons, wizard flows that are too long, and screens without back navigation, the tool reduces the risk of accessibility-related regulatory exposure, app store rejection, and negative press. Catching these issues during development is dramatically cheaper than fixing them post-launch in response to user complaints or legal challenges. For a product serving a broad Norwegian user base, meeting cognitive accessibility standards is both a legal obligation and a competitive differentiator.
The Cognitive Accessibility Audit Utility is a medium-complexity development and CI tool with a dependency on the CognitiveLoadRuleEngine. It does not ship in production builds, so it carries no runtime risk, but it must be integrated into the CI pipeline early enough to catch violations before they accumulate into large refactoring work. The main scheduling risk is that audit failures discovered late in a sprint may require UX changes that push feature delivery. Mitigation is to run the audit from the first sprint so violations are caught immediately.
QA and developers must agree on a policy for treating audit violations — whether they are blocking or advisory — and this policy should be documented. The audit report output should be part of every PR review process.
The Cognitive Accessibility Audit Utility integrates with Flutter's test framework via `auditWidgetTree(BuildContext)` and `auditWizardConfig(config)`, delegating rule evaluation to the `CognitiveLoadRuleEngine`. `assertCompliant(BuildContext)` throws a test failure with a structured message if violations are found, enabling direct use in widget tests with a single assertion. `runFullAudit()` traverses the entire navigable route graph, not just a single widget tree. `generateReport()` serializes the `AuditReport` to a human-readable string suitable for CI log output or PR comments.
The debug overlay path renders violations as an in-app banner during development builds, using a conditional compile guard to ensure zero overhead in release mode. New rule types are added by extending the `CognitiveLoadRuleEngine`, keeping this component's interface stable across rule additions.
Responsibilities
- Scan widget trees for icon-only navigation buttons
- Verify all wizard configurations via CognitiveLoadRuleEngine
- Assert back navigation is available on all non-root screens
- Generate a human-readable audit report for CI integration
Interfaces
auditWidgetTree(BuildContext): AuditReport
auditWizardConfig(config): AuditReport
runFullAudit(): AuditReport
assertCompliant(BuildContext)
generateReport(): String