Contrast Ratio Validator Service
Component Detail
Description
Implements the WCAG 2.2 relative luminance and contrast ratio algorithms in Dart. Used both at runtime during token loading and by the CI lint pipeline to verify every color pair in the design token system meets the applicable threshold (4.5:1 normal text, 3:1 large text and UI components).
contrast-ratio-validator
Summaries
The Contrast Ratio Validator Service is the automated enforcement backbone of the application's WCAG 2.2 accessibility compliance strategy. By integrating color validation into both runtime token loading and the CI pipeline, it makes it structurally impossible for non-compliant color combinations to reach production undetected. This reduces legal and reputational risk, lowers QA costs by surfacing violations at development time rather than post-launch, and produces auditable compliance evidence required by enterprise clients and regulated-industry procurement processes. The result is a defensible, measurable accessibility posture that directly supports sales cycles where certification is a contract requirement.
This medium-complexity component has no dependencies, making it a safe, unblocking early deliverable that must be scheduled in the first development sprint since both contrast-safe-color-palette and the CI lint pipeline depend on it. It runs in mobile and CLI execution contexts, which constrains the implementation to pure Dart with no Flutter framework imports — verify this requirement with the platform team upfront. Testing requires a comprehensive golden dataset of known color pairs with expected contrast ratios validated against the WCAG specification document. The `validateTokenPairs()` and `getViolations()` batch interfaces are critical path for CI integration and must emit structured, machine-readable output for the lint reporter — define that output schema before implementation begins.
Pure Dart service implementing WCAG 2.2 relative luminance (IEC 61966-2-1 sRGB linearization) and the standard contrast ratio formula. `calculateLuminance(Color)` applies the piecewise linearization (divide by 12.92 below 0.04045, otherwise ((c+0.055)/1.055)^2.4) and returns a double in [0,1]. `calculateContrastRatio(Color fg, Color bg)` returns (L_lighter + 0.05) / (L_darker + 0.05). Compliance helpers compare against 4.5:1 (normal text), 3:1 (large text and UI components).
`validateTokenPairs(List
Responsibilities
- Calculate relative luminance for any sRGB color
- Compute contrast ratio for foreground/background pairs
- Classify compliance level (AA normal, AA large, AAA)
- Batch-validate all token pairs and return violation reports
Interfaces
calculateLuminance(Color color) → double
calculateContrastRatio(Color fg, Color bg) → double
isCompliantNormalText(Color fg, Color bg) → bool
isCompliantLargeText(Color fg, Color bg) → bool
isCompliantUiComponent(Color fg, Color bg) → bool
validateTokenPairs(List<TokenPair> pairs) → ValidationReport
getViolations(DesignTokens tokens) → List<ContrastViolation>
Relationships
Dependents (3)
Components that depend on this component