Color Contrast Docs & Tools
Relevant source files
The following files were used as context for generating this wiki page:
Color Contrast Docs & Tools is a collection of applications, command-line interfaces, and web-based components designed to compute and verify color contrast ratios against Web Content Accessibility Guidelines (WCAG) 2.1. The system provides developers and designers with tools to ensure visual accessibility through automated checks, batch processing of palettes, and intelligent color suggestions.
The project is structured as a monorepo, separating the core computation logic in @siluat/color-contrast from its consumer interfaces, including a CLI tool (@siluat/color-contrast-cli) and a documentation site built with Next.js and Fumadocs.
Sources: packages/color-contrast/README.md, packages/color-contrast-cli/README.md, apps/color-contrast-docs/package.json
Core Computation Engine
The @siluat/color-contrast package serves as the primary engine for all contrast-related operations. It is a zero-dependency, browser-compatible library that handles color parsing, color space conversion (including wide-gamut spaces like OKLCH and LAB), and WCAG compliance grading.
Key Capabilities
- Contrast Computation: Calculates the relative luminance of two colors to determine their ratio (1:1 to 21:1).
- Compliance Grading: Evaluates ratios against WCAG 2.1 thresholds for Normal and Large text.
- Color Suggestion: Uses the OKLCH color space to adjust lightness while preserving hue and chroma to find the closest accessible alternative.
- Alpha Compositing: Automatically resolves semi-transparent colors by compositing them over backgrounds (defaulting to white for the base).
Sources: packages/color-contrast/README.md:94-110, packages/color-contrast/src/index.test.ts
Compliance Thresholds (WCAG 2.1)
| Level | Normal Text | Large Text (18pt+ / 14pt+ bold) |
|---|---|---|
| AAA | >= 7.0:1 | >= 4.5:1 |
| AA | >= 4.5:1 | >= 3.0:1 |
Sources: packages/color-contrast/README.md:78-83, apps/color-contrast-docs/components/color-checker.tsx:210-215
Web-Based Tools
The project includes interactive React components used within the documentation site to provide real-time accessibility auditing.
Color Checker
The ColorChecker component allows users to input foreground and background colors (Hex, RGB, HSL, OKLCH, etc.) to receive an instant compliance report.
The component utilizes checkContrast for the initial grading and suggestForeground to offer a "Suggested Fix" when a pair fails the AA threshold.
Sources: apps/color-contrast-docs/components/color-checker.tsx:162-205
Batch Palette Audit
The BatchPaletteAudit component performs a matrix-style audit of an entire color palette. It calculates contrast for every possible foreground/background pair within a defined set.
- Contrast Matrix: A grid showing ratios and compliance levels for all combinations.
- Summary Statistics: A breakdown of the percentage of pairs meeting AAA, AA, or Fail criteria.
- Filtering: Users can filter the matrix to show only failing pairs or specific compliance levels.
Sources: apps/color-contrast-docs/components/batch-palette-audit.tsx:160-200
Command Line Interface (CCR)
The @siluat/color-contrast-cli (aliased as ccr) provides the same computation power for terminal-based workflows and CI/CD pipelines.
Execution Flow
CLI Features
- Batch Mode: Processes multiple pairs from stdin using bracket-aware splitting to handle functional notations like
rgb()oroklch(). - JSON Output: Provides structured data for integration with other tools via the
--jsonflag. - Verbose Mode: Shows the full conversion pipeline trace, including relative luminance values and gamut mapping details.
- CI Integration: Returns exit code 0 on pass and 1 on compliance failure (when using
--level).
Sources: packages/color-contrast-cli/README.md:40-100
Visual Verification Script
For development and algorithm testing, the project includes a visual-check.ts script. This tool generates a static HTML comparison page to verify the output of the --suggest feature.
- Side-by-Side Comparison: Displays original vs. suggested colors.
- Readability Samples: Renders text at 24px (bold), 16px, and 14px to assess visual quality.
- Hue Preservation: Allows developers to manually verify that the OKLCH-based suggestion preserves the original color's intent while reaching the target ratio.
Sources: packages/color-contrast-cli/scripts/visual-check.ts:50-100, packages/color-contrast-cli/scripts/README.md
Summary
Color Contrast Docs & Tools provides a multi-layered approach to accessibility. By decoupling the core logic into a pure computation library, the project ensures consistent contrast evaluation across web interfaces and command-line environments. The tools emphasize not just identifying failures, but providing actionable fixes through hue-preserving color suggestions.
Sources: packages/color-contrast/CLAUDE.md, packages/color-contrast-cli/README.md