CLI

Installation

Global

npm install -g @siluat/color-contrast-cli

This registers the ccr command globally.

Run without installing

npx @siluat/color-contrast-cli '#000' '#fff'
# or
bunx @siluat/color-contrast-cli '#000' '#fff'

Basic Usage

`ccr <foreground> <background>`

Calculate the WCAG 2.1 contrast ratio between two CSS colors.

ccr '#333' '#fff'

Contrast ratio: 12.63:1
Normal text: AAA ✓
Large text:  AAA ✓

When a pair fails, the output indicates the failure:

ccr '#999' '#fff'

Contrast ratio: 2.85:1
Normal text: Fail ✗
Large text:  Fail ✗

Options

Option	Description
`--json`	Output result as JSON
`--verbose`	Show full conversion pipeline trace
`--level AA\|AAA`	Check compliance level (exit code 0 on pass, 1 on fail)
`--size normal\|large`	Text size for compliance check (default: `normal`)
`--suggest`	Suggest an accessible foreground color (requires `--level`)
`--batch`	Process multiple color pairs from stdin
`--help`	Show help
`--version`	Show version

JSON Output

`ccr <foreground> <background> --json`

Output the result as a JSON object for scripting and CI/CD integration.

ccr '#333' '#fff' --json

{"ratio":12.63,"normalText":"AAA","largeText":"AAA"}

Compliance Level Check

`ccr <foreground> <background> --level <AA|AAA>`

Check whether a color pair meets a specific WCAG compliance level. Exits with code 0 on pass, 1 on fail.

ccr '#333' '#fff' --level AA
ccr '#333' '#fff' --level AAA

Use --size large to check against large text thresholds (AA ≥ 3, AAA ≥ 4.5). WCAG defines "large text" as 18pt (24px) or above, or 14pt (18.66px) bold or above:

ccr '#777' '#fff' --level AA --size large
# exit code: 0 (ratio 4.48 >= 3)

Combine with --json to get structured output alongside the exit code:

ccr '#333' '#fff' --level AA --json
# stdout: {"ratio":12.63,"normalText":"AAA","largeText":"AAA"}
# exit code: 0

Color Suggestion

`ccr <foreground> <background> --suggest --level <AA|AAA>`

Suggest the closest accessible foreground color when a pair fails the target level. Adjusts only the OkLCH lightness, preserving hue and saturation for minimal perceptual distance.

ccr '#777' '#fff' --suggest --level AA

Suggested foreground: #767676
Contrast ratio: 4.54:1 (AA)

With --json:

ccr '#777' '#fff' --suggest --level AA --json

{"original":{"ratio":4.48,"normalText":"Fail","largeText":"AA"},"suggested":{"color":"#767676","ratio":4.54,"normalText":"AA","largeText":"AAA"}}

If the pair already passes, no suggestion is made. If the target cannot be met, the CLI reports this and exits with code 1.

Batch Mode

`ccr --batch`

Process multiple color pairs from stdin. Useful for design system palette audits.

echo -e "#000 #fff\n#333 #ccc\n#666 #999" | ccr --batch

#000 #fff → 21:1 AAA / AAA
#333 #ccc → 7.87:1 AAA / AAA
#666 #999 → 2.02:1 Fail / Fail

With --json:

echo -e "#000 #fff\n#333 #ccc" | ccr --batch --json

[{"foreground":"#000","background":"#fff","ratio":21,"normalText":"AAA","largeText":"AAA"},{"foreground":"#333","background":"#ccc","ratio":7.87,"normalText":"AAA","largeText":"AAA"}]

Use --level to check all pairs with a single exit code (0 if all pass, 1 if any fail):

echo -e "#000 #fff\n#666 #999" | ccr --batch --level AA
# exit code: 1 (second pair fails)

Combine with --suggest to get suggestions for failing pairs:

echo -e "#777 #fff\n#333 #fff" | ccr --batch --suggest --level AA

#777 #fff → Suggested: #767676 4.54:1 (AA)
#333 #fff → Already passes AA

Input format

Input supports comments (//), blank lines, and tab or space-separated pairs. Functional colors like rgb() and oklch() are handled by bracket-aware splitting:

// Design system palette audit
#000 #fff
rgb(255, 0, 0) white
oklch(60% 0.15 50)	#ffffff

Invalid lines are reported as errors and processing continues. Exit code 2 indicates at least one parse error (takes priority over level failure).

Note: --verbose cannot be combined with --batch.

Verbose Mode

`ccr <foreground> <background> --verbose`

Show the full conversion pipeline trace — parsed values, color space conversions, alpha compositing, luminance, and contrast evaluation.

ccr 'oklch(60% 0.15 50)' white --verbose

Foreground: oklch(60% 0.15 50)
  -> Parsed as OKLCH: L=0.6, C=0.15, H=50
  -> Gamut mapped to sRGB: rgb(196, 96, 22)
Background: white
  -> Parsed as NAMED: rgb(255, 255, 255)
Alpha compositing: not needed (both opaque)
Relative luminance: fg=0.2017, bg=1
Contrast ratio: 4.17:1
Normal text: Fail ✗
Large text:  AA ✓

Combine with --suggest to see OkLCH adjustment details:

ccr '#777' '#fff' --suggest --level AA --verbose

Foreground: #777
  -> Parsed as HEX: rgb(119, 119, 119)
Background: #fff
  -> Parsed as HEX: rgb(255, 255, 255)
Alpha compositing: not needed (both opaque)
Relative luminance: fg=0.1845, bg=1
Contrast ratio: 4.48:1
Normal text: Fail ✗
Large text:  AA ✓
Suggestion:
  Original OkLCH: L=0.5693, C=0, H=180
  Suggested OkLCH: L=0.5658, C=0, H=180
  Direction: darker
  Suggested foreground: #767676
  Contrast ratio: 4.54:1 (AA)

Note: --verbose cannot be combined with --json.

Exit Codes

Code	Meaning
`0`	Success (or compliance check passed)
`1`	Compliance check failed (`--level`) or suggestion impossible (`--suggest`)
`2`	Invalid input (parse error)

Error Handling

The CLI prints error messages to stderr and exits with code 2.

ccr 'not-a-color' '#fff'

Error: Invalid color: "not-a-color"
  Supported formats: #hex, named colors (red, blue, ...), rgb(), hsl(), hwb(), lab(), lch(), oklab(), oklch()

When the intended format can be detected, the hint is more specific:

ccr '#gg0000' '#fff'

Error: Invalid color: "#gg0000"
  Hex colors use characters 0-9 and a-f. Example: #ff0000

With --json, errors are still printed to stderr as plain text.

Supported Color Formats

The CLI supports the same CSS color formats as the Library API:

Format	Examples
Hex	`#rgb`, `#rrggbb`, `#rgba`, `#rrggbbaa`
Named colors	`red`, `navy`, `rebeccapurple`, `transparent`
RGB	`rgb(255 0 0)`, `rgb(255, 0, 0)`, `rgba(255 0 0 / 0.5)`
HSL	`hsl(120 100% 50%)`, `hsl(120, 100%, 50%)`, `hsla(120 100% 50% / 0.5)`
HWB	`hwb(0 0% 0%)`
LAB	`lab(50% 40 59.5)`
LCH	`lch(52.2% 72.2 50)`
OKLAB	`oklab(0.6 0.1 0.1)`
OKLCH	`oklch(60% 0.15 50)`

CLI

On this page