Color Contrast Core Library
Relevant source files
The following files were used as context for generating this wiki page:
The Color Contrast Core Library (@siluat/color-contrast) is a high-performance, pure computation engine designed for Web Content Accessibility Guidelines (WCAG) compliance auditing. It provides zero-dependency utilities for color parsing, color space conversion, relative luminance calculation, and contrast ratio grading.
The library is designed to be environment-agnostic, maintaining compatibility with both browsers and Node.js by avoiding I/O and environment-specific APIs. It serves as the foundational computation layer for the @siluat/color-contrast-cli and various documentation tools.
Sources: packages/color-contrast/CLAUDE.md:12-16, packages/color-contrast/package.json:2-17
Architecture and Core Principles
The library follows a "pure computation" architecture. It processes raw string inputs or color objects and returns numerical or structured compliance data without side effects.
Computation Pipeline
The internal logic flows from raw input strings through a multi-stage normalization process before calculating the final contrast ratio:
This diagram illustrates the transformation of color data from input to accessibility grading.
Sources: packages/color-contrast/README.md:95-103, packages/color-contrast/CLAUDE.md:12-14
Core Functionality
The library exposes several primary APIs for different stages of color analysis.
Contrast and Compliance
The primary functions calculate the ratio between two colors (foreground and background) and determine if they meet WCAG 2.1 thresholds.
| Function | Input | Returns | Description |
|---|---|---|---|
contrastRatio | (fg: string, bg: string) | number | Returns a ratio from 1 to 21, rounded to 2 decimal places. |
checkContrast | (fg: string, bg: string) | ContrastResult | Returns ratio and compliance levels (AAA, AA, Fail) for normal/large text. |
validateColors | (fg: string, bg: string) | string[] | Validates both inputs upfront and returns a list of error messages. |
Sources: packages/color-contrast/README.md:16-56, packages/color-contrast/src/index.test.ts:101-107
Color Suggestion Engine
The suggestForeground function identifies the closest accessible alternative for a failing color pair. It specifically adjusts only the Lightness in the OkLCH color space to preserve the original hue and saturation, ensuring the suggested color remains visually related to the original.
Sources: packages/color-contrast/README.md:38-48, packages/color-contrast-cli/CHANGELOG.md:43-45
Supported Color Spaces and Formats
The library supports a wide array of CSS Color Level 4 formats, including wide-gamut spaces.
| Category | Supported Formats |
|---|---|
| Legacy/Standard | HEX (#RGB, #RRGGBB, #RGBA), RGB/RGBA, HSL/HSLA, HWB |
| Wide-Gamut/Modern | LAB, LCH, OKLAB, OKLCH |
| Named | 148 CSS named colors (e.g., navy, rebeccapurple) and transparent |
Sources: packages/color-contrast/README.md:78-87, packages/color-contrast/src/parse/index.test.ts:7-130
Handling Complex Color Data
- Alpha Compositing: Colors with transparency are resolved against a background (defaulting to white for the root background) to simulate how they appear to the user.
- Gamut Mapping: For wide-gamut colors (like OKLCH) that exceed sRGB limits, the library implements the CSS Color Level 4 gamut mapping algorithm (Section 13.2) using chroma binary search.
Sources: packages/color-contrast/README.md:98-111, packages/color-contrast-cli/CHANGELOG.md:79-81
Data Structures
The library utilizes several key interfaces for returning structured analysis:
type ComplianceLevel = 'AAA' | 'AA' | 'Fail';
interface ContrastResult {
ratio: number;
normalText: ComplianceLevel;
largeText: ComplianceLevel;
}
interface SuggestResult {
suggested: string | null;
result: ContrastResult | null;
}
Sources: packages/color-contrast/README.md:61-73
Technical Specifications
WCAG 2.1 Thresholds
The library enforces the following standard thresholds for compliance grading:
| Level | Normal Text | Large Text |
|---|---|---|
| AAA | ≥ 7:1 | ≥ 4.5:1 |
| AA | ≥ 4.5:1 | ≥ 3:1 |
Sources: packages/color-contrast/README.md:70-76
Implementation Detail: Parser
The parser (found in src/parse/) is responsible for decomposing string inputs into raw components. It supports both comma-separated and space-separated functional notations.
// Example of parsed sRGB internal structure
{
space: 'srgb',
r: 1, // Range 0-1
g: 0,
b: 0,
alpha: 1
}
Sources: packages/color-contrast/src/parse/index.test.ts:7-14, packages/color-contrast-cli/CHANGELOG.md:89-94
Summary
The Color Contrast Core Library provides a robust, standardized implementation of WCAG contrast mathematics. By centralizing complex logic like alpha compositing and wide-gamut mapping into a zero-dependency package, it enables consistent accessibility auditing across CLI tools and web applications.