Contrast-Safe Color Palette Widget
Component Detail
Description
A Flutter ThemeData color scheme built exclusively from contrast-verified token pairs. Exposes foreground/background pairs guaranteed to meet 4.5:1 for normal text and 3:1 for large text and UI components, eliminating runtime color composition that could violate WCAG 2.2 AA.
contrast-safe-color-palette
Summaries
The Contrast-Safe Color Palette Widget eliminates an entire class of accessibility compliance failures by pre-validating every color combination used in the application against WCAG 2.2 AA contrast ratios before any code ships to production. This proactively reduces legal exposure from accessibility litigation, avoids costly post-launch UI remediation cycles, and provides auditable compliance evidence required by enterprise procurement processes. Supporting both light and dark modes with verified contrast ensures all users — including those with visual impairments — receive a consistent, high-quality experience, strengthening brand equity and broadening market reach across regulated industries.
This shared, medium-complexity component depends on both design-token-provider and contrast-ratio-validator, making it downstream of two foundational services and schedule-sensitive to both. Plan to deliver it only after those dependencies reach stability. Because it is shared and affects every screen's color rendering, a late-breaking token change can cascade visually across the entire application simultaneously. Testing requires light and dark mode coverage for all semantic color roles (onSurface, onPrimary, etc.) plus automated contrast ratio verification in CI.
The `exportPaletteManifest()` interface produces design-handoff artifacts that reduce back-and-forth with stakeholders and provide a compliance paper trail for accessibility audits.
Built as a Flutter ThemeData color scheme builder. `buildColorScheme(Brightness)` reads pre-validated token pairs from design-token-provider and constructs a Material 3 ColorScheme. `getContrastPair(String backgroundToken)` returns a ContrastPair struct carrying guaranteed ratio metadata alongside the color values. `validatePairRatio(Color fg, Color bg)` delegates directly to contrast-ratio-validator's luminance algorithm to avoid duplicating calculation logic.
The architecture deliberately prevents ad-hoc color composition — all colors must flow through semantic accessors, enforced by making raw color constants package-private. `exportPaletteManifest()` serializes the full palette as a structured map suitable for CI auditing scripts. Maintain strict one-to-one mappings between semantic keys and token identifiers to prevent design-code drift over release cycles.
Responsibilities
- Build ColorScheme from pre-validated contrast-safe token pairs
- Provide semantic color accessors (onSurface, onPrimary, etc.) with guaranteed ratios
- Prevent ad-hoc color composition outside the token system
- Support both light and dark mode palettes with verified contrast
Interfaces
buildColorScheme(Brightness brightness) → ColorScheme
getContrastPair(String backgroundToken) → ContrastPair
validatePairRatio(Color fg, Color bg) → double
getSemanticColor(String semanticKey) → Color
exportPaletteManifest() → Map<String, dynamic>
Relationships
Dependencies (2)
Components this component depends on
Related Data Entities (1)
Data entities managed by this component