Color Contrast CLI
Relevant source files
The following files were used as context for generating this wiki page:
The Color Contrast CLI (@siluat/color-contrast-cli) is a command-line tool designed to verify WCAG (Web Content Accessibility Guidelines) color contrast ratios. It serves as a specialized wrapper around the @siluat/color-contrast computation engine, providing features such as batch processing, automated color suggestions, and CI-ready exit codes.
Sources: packages/color-contrast-cli/README.md:1-5, packages/color-contrast-cli/CHANGELOG.md:18-25
Architecture and Components
The CLI is architected to separate computation logic from user interface concerns. Since version 1.0.0, all mathematical computations, color parsing, and gamut mapping reside in the core @siluat/color-contrast package, while the CLI package manages argument parsing, output formatting (JSON/Text), and batch stream processing.
Sources: packages/color-contrast-cli/CHANGELOG.md:18-25, packages/color-contrast-cli/package.json:34-36
System Logic Flow
The following diagram illustrates how the CLI processes a typical contrast check request, including optional suggestion logic.
Core Features
1. Contrast Verification
The CLI evaluates the contrast between two colors against WCAG 2.1 thresholds. It supports multiple compliance levels (AA, AAA) and font sizes (normal, large).
| Threshold | 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:105-110, packages/color-contrast-cli/README.md:32-40
2. Color Suggestion Algorithm
When the --suggest flag is used, the system attempts to find the closest accessible foreground color. This is achieved by converting the color to the OkLCH color space and adjusting only the lightness (L) coordinate. This method ensures that the original hue and saturation are preserved while reaching the target contrast ratio.
Sources: packages/color-contrast-cli/CHANGELOG.md:50-54, packages/color-contrast-cli/README.md:48-55
3. Batch Processing
The CLI can process multiple color pairs via stdin using the --batch flag. This is optimized for design system audits. It supports comments (//), blank lines, and various delimiters (space, tab).
Command Options and Exit Codes
The CLI uses specific exit codes to facilitate integration with Continuous Integration (CI) pipelines.
| Exit Code | Meaning |
|---|---|
| 0 | Success (Colors pass the specified WCAG level) |
| 1 | Failure (Colors do not meet the WCAG level) |
| 2 | Error (Invalid color formats or argument errors) |
Sources: packages/color-contrast-cli/README.md:120-135, packages/color-contrast-cli/src/batch/process-batch.ts:137-140
Key Arguments
| Flag | Description |
|---|---|
--json | Outputs results as a structured JSON object. |
--level <AA|AAA> | Sets the target compliance level for exit code checks. |
--size <normal|large> | Adjusts thresholds for large text. |
--suggest | Recommends an accessible color if the pair fails. |
--batch | Enables processing multiple pairs from stdin. |
--verbose | Shows the full conversion pipeline trace (gamut mapping, alpha compositing). |
Sources: packages/color-contrast-cli/README.md:15-115, packages/color-contrast-cli/CHANGELOG.md:65-75
Technical Implementation Details
Supported Formats
The CLI inherits support for various color formats from the core library, resolving them to opaque sRGB before calculation:
- HEX:
#RGB,#RRGGBB,#RGBA,#RRGGBBAA - Functional:
rgb(),rgba(),hsl(),hsla(),hwb() - Wide-Gamut:
lab(),lch(),oklab(),oklch()(utilizing CSS Color Level 4 gamut mapping) - Named: 148 CSS named colors including
transparent
Sources: packages/color-contrast/README.md:120-140, packages/color-contrast-cli/CHANGELOG.md:85-110
Alpha Compositing
If colors contain an alpha channel, the CLI simulates browser rendering by compositing the background over white, and then the foreground over the resulting background to produce opaque values for the WCAG formula.
Sources: packages/color-contrast/README.md:150-160, packages/color-contrast-cli/README.md:100-110
Visual Verification
A development script visual-check.ts is used to generate HTML reports that visually compare original colors against suggested alternatives, ensuring that the suggestion algorithm's lightness adjustments look natural across different color families.
Sources: packages/color-contrast-cli/scripts/visual-check.ts:10-50, packages/color-contrast-cli/scripts/README.md:5-15
The Color Contrast CLI provides a robust, CI-ready environment for ensuring web accessibility. By combining OkLCH-based color suggestions with flexible batch processing, it bridges the gap between design requirements and technical compliance.