Accessibility

Accessibility (WCAG)

Function	Description
relativeLuminance(color)	WCAG relative luminance (0–1)
contrastRatio(c1, c2)	WCAG contrast ratio (1–21)
wcagLevel(fg, bg)	Returns 'AAA' | 'AA' | 'AA-large' | 'fail'
bestTextColor(bg)	Returns '#000000' or '#ffffff' for best contrast on bg
bestContrastColor(bg, candidates)	Picks the most readable color from an array of candidates
bestContrastPalette(bg, palettes, opts?)	Picks the palette with best overall contrast. Returns { paletteIndex, palette, minContrastRatio, avgContrastRatio }
isReadableOnBackground(text, bg, opts?)	Checks readability on solid, semi-transparent, or gradient backgrounds. Returns { readable, minContrastRatio, wcagLevel }
isDark(color, threshold?)	true if luminance is below threshold (default 0.5)
isLight(color, threshold?)	Inverse of isDark

isReadableOnBackground — complex backgrounds

background can be a plain color string, a semi-transparent spec, or a gradient with multiple stops:

import { isReadableOnBackground } from 'color-value-tools'

// Solid background
isReadableOnBackground('#ffffff', '#3498db')
// → { readable: true, minContrastRatio: 3.05, wcagLevel: 'AA-large' }

// Semi-transparent overlay composited over white
isReadableOnBackground('#ffffff', {
  type: 'semi-transparent',
  color: 'rgba(52, 152, 219, 0.5)',
  underlay: '#f0f0f0',
})

// Gradient — worst stop is used for the result
isReadableOnBackground('#ffffff', {
  type: 'gradient',
  stops: ['#1a1a2e', '#e94560', '#f5a623'],
})

// AAA + large text
isReadableOnBackground('#000000', '#f0f0f0', { level: 'AAA', largeText: true })

bestContrastPalette — pick accessible palette

import { bestContrastPalette } from 'color-value-tools'

const result = bestContrastPalette('#1a1a2e', [
  ['#ffffff', '#f0f0f0', '#cccccc'],
  ['#ffff00', '#ffd700', '#ff8c00'],
])
// → { paletteIndex: 0, palette: [...], minContrastRatio: 12.1, avgContrastRatio: 14.3 }

Color Blindness Simulation

Simulates perception using Vienot 1999 matrices applied to linearized RGB.

Function	Description
simulateProtanopia(color)	No L-cones (red-blind)
simulateDeuteranopia(color)	No M-cones (green-blind)
simulateTritanopia(color)	No S-cones (blue-blind)
simulateColorBlindness(color, type)	Generic — type: 'protanopia' | 'deuteranopia' | 'tritanopia'

import { simulateColorBlindness } from 'color-value-tools'

simulateColorBlindness('#e74c3c', 'deuteranopia') // '#9a7b00'
simulateColorBlindness('#3498db', 'protanopia') // '#5282db'