WCAG AA Color Contrast Guarantee for UI Tokens
ChromUI enforces WCAG AA contrast ratios in all generated design tokens. Algorithm overview, edge cases, limitations, and FAQ.
What 'Guarantee' Means
The engine enforces minimum contrast ratios before token generation. All color pairs (text on background, primary on background, etc.) are validated against WCAG AA standards (4.5:1 for normal text, 3:1 for large text). If a generated color fails, the engine adjusts it automatically.
This is not a "checker only" tool. Contrast enforcement is built into the generation algorithm. You cannot export tokens that fail WCAG AA standards. This ensures all exported tokens are accessible by default.
Algorithm Overview
The engine calculates relative luminance for each color pair using the WCAG formula. If contrast falls below WCAG AA thresholds, colors are adjusted by modifying lightness values while preserving hue and saturation. The algorithm iterates until all required pairs meet the standard.
Color pairs validated include: text on background, primary on background, secondary on background, accent on background, onPrimary on primary, onSecondary on secondary, onAccent on accent, and textMuted on background.
Edge Cases & Limitations
Very dark backgrounds (near-black) or very light backgrounds (near-white) may limit color options. The engine prioritizes contrast over exact color matching. Some vibrant color combinations may be adjusted to meet accessibility standards.
Manual fine-tuning may be needed for specific brand color requirements. If your brand colors don't meet WCAG AA, you'll need to adjust them manually after export. The engine cannot override WCAG standards for brand compliance.
WCAG AAA compliance (7:1 contrast) is not enforced. The engine focuses on WCAG AA (4.5:1) for practical design system use. If you need AAA compliance, you'll need to adjust colors manually.
Contrast Validation Process
- Generate base color palette from vibe and seed
- Calculate relative luminance for each color
- Validate all required color pairs against WCAG AA thresholds
- Adjust failing pairs by modifying lightness values
- Re-validate until all pairs meet standards
- Export tokens with guaranteed contrast compliance
FAQ
What does 'guarantee' mean in ChromUI terms?
The engine enforces minimum contrast ratios before token generation. All color pairs (text on background, primary on background, etc.) are validated against WCAG AA standards (4.5:1 for normal text, 3:1 for large text). If a generated color fails, the engine adjusts it automatically.
How does the algorithm enforce contrast?
The engine calculates relative luminance for each color pair. If contrast falls below WCAG AA thresholds, colors are adjusted by modifying lightness values while preserving hue and saturation. The algorithm iterates until all required pairs meet the standard.
What are the edge cases and limitations?
Very dark backgrounds (near-black) or very light backgrounds (near-white) may limit color options. The engine prioritizes contrast over exact color matching. Some vibrant color combinations may be adjusted to meet accessibility standards. Manual fine-tuning may be needed for specific brand color requirements.
Does the guarantee apply to all exported tokens?
Yes. All exported formats (CSS variables, Tailwind config, JSON tokens) include colors that meet WCAG AA contrast. The guarantee applies to primary, secondary, accent, text, and background color pairs defined in the token set.
What about WCAG AAA compliance?
The engine enforces WCAG AA standards (4.5:1 for normal text). WCAG AAA requires 7:1 contrast, which is stricter and may limit color options significantly. ChromUI focuses on AA compliance for practical design system use.
Can I override the contrast enforcement?
No. Contrast enforcement is built into the generation engine. This ensures all exported tokens are accessible by default. If you need specific colors that don't meet WCAG AA, you'll need to adjust them manually after export.