Color Contrast Implementation Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
The Color Contrast implementation provides a robust system for calculating Web Content Accessibility Guidelines (WCAG) 2.1 contrast ratios, grading compliance, and suggesting accessible color alternatives. It is split into two primary components: a pure computation library (@siluat/color-contrast) and a command-line interface (@siluat/color-contrast-cli) for batch processing and CI integration.
Sources: packages/color-contrast/CLAUDE.md:10-15, packages/color-contrast-cli/README.md:1-5
Core Architecture and Data Flow
The system follows a strict pipeline where input color strings in various formats (Hex, RGB, HSL, OKLCH, etc.) are parsed, converted into a common sRGB space, and then processed for luminance and contrast calculation.
Computation Pipeline
The following diagram illustrates the data flow from raw input to compliance grading:
The pipeline handles alpha compositing by resolving transparent colors over the background (or white by default) before calculating luminance. Wide-gamut colors (LAB, LCH, OKLCH) are gamut-mapped to sRGB using the CSS Color Level 4 algorithm.
Sources: packages/color-contrast/src/index.ts:33-100, packages/color-contrast/README.md:120-135
Key Modules and Components
1. Computation Engine (@siluat/color-contrast)
This package contains pure logic with zero runtime dependencies. It provides the fundamental functions used by both the CLI and documentation components.
| Function | Description |
|---|---|
contrastRatio | Returns a numerical ratio (1 to 21) between two colors. |
checkContrast | Returns a ContrastResult with AA/AAA compliance levels. |
suggestForeground | Finds the closest accessible color by adjusting OKLCH lightness. |
validateColors | Pre-validates color strings and returns a list of diagnostic errors. |
checkContrastVerbose | Provides a full trace of the conversion and calculation steps. |
Sources: packages/color-contrast/src/index.ts:108-205, packages/color-contrast/README.md:95-112
2. Command Line Interface (ccr)
The CLI acts as a wrapper for batch processing and automated checks. It supports multiple output formats and process management.
- Batch Mode: Processes multiple pairs from stdin, supporting bracket-aware splitting for functional notations like
rgb(). - Suggestion Engine: When
--suggestis used, the CLI utilizes the library's suggestion logic to recommend colors that preserve the original hue and saturation. - Exit Codes:
0: Success (all colors pass the specified level).1: Level failure (one or more colors fail the WCAG threshold).2: Error (invalid color format or argument error).
Sources: packages/color-contrast-cli/src/batch/process-batch.ts:105-180, packages/color-contrast-cli/README.md:10-100
WCAG Compliance Standards
The implementation adheres to WCAG 2.1 thresholds for contrast minimums. Compliance is determined based on text size and target level.
| Level | Normal Text | Large Text (18pt+ / 14pt+ bold) |
|---|---|---|
| AA | >= 4.5:1 | >= 3:1 |
| AAA | >= 7:1 | >= 4.5:1 |
Sources: packages/color-contrast/README.md:113-118, apps/color-contrast-docs/components/color-checker.tsx:288-295
Color Suggestion Logic
The suggestForeground feature uses the OKLCH color space to ensure perceptual uniformity. It preserves the original Hue (H) and Chroma (C) while performing a binary search on Lightness (L) to meet the target ratio.
Error Handling and Validation
The system prioritizes actionable feedback. Instead of simple boolean checks, it provides diagnostic messages via validateColors and diagnoseColorError.
// Example: Validating both colors at once
const errors = validateColors('#gg0000', '#zz0000');
// Result:
// [
// 'Invalid color: "#gg0000"\n Hex colors use characters 0-9 and a-f...',
// 'Invalid color: "#zz0000"\n Hex colors use characters 0-9 and a-f...'
// ]
Sources: packages/color-contrast/src/index.ts:133-145, packages/color-contrast/README.md:76-88
Summary
The Color Contrast implementation is a modular system that bridges high-level CSS color specifications with rigorous mathematical accessibility standards. By leveraging modern color spaces like OKLCH and supporting wide-gamut gamut mapping, it ensures that contrast calculations remain accurate across different rendering contexts while providing tools for developers to automatically fix accessibility issues.