The only color science library with adaptive visual perception modeling and accessibility-driven optimization.
npm install @markgorzynski/color-utils



๐ View Full Documentation | ๐ NPM Package
The only color science library with adaptive visual perception modeling and accessibility-driven optimization.
> ๐ฏ Unique Focus: While other libraries provide general color manipulation, Color Utils specializes in perceptually-aware color operations that adapt to viewing conditions and maintain accessibility standards.
``bash`
npm install @markgorzynski/color-utils
`javascript
import { AdaptiveOklab, parseCSS, calculateWcagContrast } from '@markgorzynski/color-utils';
// Adaptive color for dark mode
const adapter = new AdaptiveOklab({ surround: 'dark' });
const color = adapter.fromSrgb({ r: 0.5, g: 0.7, b: 0.3 });
// Parse modern CSS colors
const cssColor = parseCSS('oklch(70% 0.2 150deg)');
// Check accessibility
const contrast = calculateWcagContrast(color1, color2);
`
| Feature | What It Does | Why It Matters |
|---------|--------------|----------------|
| ๐จ Adaptive Oklab | Colors that adapt to viewing environment (dark/light/gray) | Industry first - no other library has this |
| โฟ Chroma Control | Maximize color vibrancy while guaranteeing WCAG compliance | Exclusive - automatic accessibility optimization |
| ๐ฌ CIECAM16 | Professional color appearance modeling | Complete implementation - rare in JavaScript |
| ๐๏ธ Surround Correction | Accurate color perception in different contexts | Unique - based on cutting-edge research |
| Use Case | Why Color Utils? |
|----------|------------------|
| ๐ Dark/Light Mode | Only library with surround-aware adaptation |
| โฟ Accessibility Apps | Automatic WCAG optimization without sacrificing design |
| ๐ฌ Color Grading | Cinema-quality CIECAM16 appearance modeling |
| ๐ Data Visualization | Perceptually uniform color scales with Oklab/OkLCH |
| ๐ฎ Gaming & VR | Adaptive colors for different viewing environments |
| ๐ฅ Medical Imaging | Accurate color reproduction with chromatic adaptation |
| Feature | Color Utils | Color.js | Culori | Chroma.js |
|---------|:-----------:|:--------:|:------:|:---------:|
| Adaptive Oklab | โ
| โ | โ | โ |
| WCAG Chroma Control | โ
| โ | โ | โ |
| CIECAM16 | โ
| โ
| โ | โ |
| CAM16-UCS | โ
| โ | โ | โ |
| Display P3 | โ
| โ
| โ
| โ |
| Rec. 2020 | โ
| โ
| โ
| โ |
| CSS Level 4 | โ
| โ
| โ
| โ |
| TypeScript | โ
| โ
| โ
| โ
|
| Zero Dependencies | โ
| โ | โ
| โ
|
| Bundle Size | ~45KB | ~150KB | ~50KB | ~35KB |
- ๐ฏ Examples
- ๐ Migration Guide
- ๐ Troubleshooting
- โ ๏ธ Known Issues
- ๐ Range Standards
- ๐ TypeScript Definitions
> Note: Core functionality is stable and well-tested (95.6% test coverage)
`bash`
npm install @markgorzynski/color-utilsor
yarn add @markgorzynski/color-utilsor
pnpm add @markgorzynski/color-utils
`javascript
import {
parseSrgbHex,
srgbToLab,
calculateWcagContrast,
AdaptiveOklab
} from '@markgorzynski/color-utils';
// Parse hex colors
const red = parseSrgbHex('#FF0000');
const white = parseSrgbHex('#FFFFFF');
// Convert to CIELAB
const labRed = srgbToLab(red);
console.log(labRed); // { L: 53.24, a: 80.09, b: 67.20 }
// Check WCAG contrast
const contrast = calculateWcagContrast(red, white);
console.log(contrast); // 3.99
// Use Adaptive Oklab for dark viewing conditions
const aokDark = new AdaptiveOklab({ surround: 'dark' });
const aokColor = aokDark.fromSrgb(red);
`
`javascript
import { parseCSS, gamutMapOklch, srgbToDisplayP3 } from '@markgorzynski/color-utils';
// Parse modern CSS colors
const cssColor = parseCSS('oklch(70% 0.2 150deg)');
const p3Color = parseCSS('color(display-p3 1 0 0.5)');
// Convert to wide gamut Display P3
const redP3 = srgbToDisplayP3(red);
// Gamut map out-of-gamut colors
const vibrant = { L: 0.7, C: 0.5, h: 30 };
const mapped = gamutMapOklch(vibrant, 'srgb');
`
javascript
import { parseSrgbHex, formatSrgbAsHex, srgbToLab, labToSrgb } from 'color-utils';// Parse and format hex colors
const color = parseSrgbHex('#FF5733'); // { r: 1, g: 0.341, b: 0.2 }
const hex = formatSrgbAsHex(color); // '#FF5733'
// Direct conversions
const lab = srgbToLab(color);
const srgb = labToSrgb(lab);
`$3
`javascript
import { srgbToLab, labToLch, lchToSrgb } from 'color-utils';// Convert between color spaces
const lab = srgbToLab({ r: 0.5, g: 0.5, b: 0.5 });
const lch = labToLch(lab);
const srgb = lchToSrgb(lch);
`$3
`javascript
import { srgbToOklab, oklabToOklch, oklchToSrgb } from 'color-utils';// Modern perceptually uniform conversions
const oklab = srgbToOklab({ r: 0.5, g: 0.7, b: 0.3 });
const oklch = oklabToOklch(oklab);
const srgb = oklchToSrgb(oklch);
`$3
`javascript
import { AdaptiveOklab } from 'color-utils';// Create instances for different viewing conditions
const aokWhite = new AdaptiveOklab({ surround: 'white' });
const aokGray = new AdaptiveOklab({ surround: 'gray' });
const aokDark = new AdaptiveOklab({ surround: 'dark' });
// Convert colors with surround adaptation
const adapted = aokDark.fromSrgb({ r: 0.5, g: 0.5, b: 0.5 });
const srgb = aokDark.toSrgb(adapted);
`$3
`javascript
import {
calculateWcagContrast,
isWcagContrastSufficient,
calculateCiede2000
} from 'color-utils';// WCAG contrast checking
const contrast = calculateWcagContrast('#FFFFFF', '#767676');
const meetsAA = isWcagContrastSufficient('#FFFFFF', '#767676', 'AA'); // true
// Perceptual color difference
const lab1 = srgbToLab(parseSrgbHex('#FF0000'));
const lab2 = srgbToLab(parseSrgbHex('#FF0505'));
const deltaE = calculateCiede2000(lab1, lab2); // Small difference
`๐ Development Roadmap
$3
- [x] Initialize Git repository
- [x] Create comprehensive .gitignore
- [x] Document current state
- [x] Make initial commit preserving everything- Code consolidation from 4 legacy versions
- State-of-the-art color science implementations
- Comprehensive testing suite (95.6% coverage)
- Full documentation and examples
- TypeScript definitions
$3
- GitHub Actions CI/CD setup
- NPM package publication
- Performance optimizations
- Additional examples and tutorials$3
- Multi-illuminant adaptation for different light sources
- CVD (color vision deficiency) optimization
- HDR color mapping with Oklab tone mapping
- Time-of-day adaptive colors
- Age-related vision adaptation
- WebAssembly performance module
- Color palette generation algorithms
- Machine learning-based color harmony
๐ฆ Module Architecture
| Module | Purpose | Key Exports |
|--------|---------|-------------|
|
srgb.js | sRGB conversions with gamma correction | parseSrgbHex, formatSrgbAsHex, srgbToLinearSrgb |
| cielab.js | CIELAB/LCH color spaces | srgbToLab, labToLch, lchToSrgb |
| oklab.js | Oklab/OkLCh modern spaces | srgbToOklab, oklabToOklch |
| aoklab.js | Adaptive Oklab with surround correction | AdaptiveOklab class |
| ciecam16.js | CIECAM16 appearance model | srgbToCiecam16 |
| color-metrics.js | Color difference and contrast metrics | calculateWcagContrast, calculateCiede2000 |
| chromaControl.js | Advanced chroma/luminance control | findMaxAokChromaForLabL, adjustAokColorToLabL |
| utils.js | Mathematical utilities | degreesToRadians, clamp, multiplyMatrixVector |๐งช Testing
`bash
Run tests
npm testRun with coverage
npm run test:coverageRun specific module tests
npm test -- srgb
`๐ค Contributing
Contributions are welcome! Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests.
๐ License
ISC License - see LICENSE file for details
๐ค Author
Mark Gorzynski
๐ Links
- ๐ Documentation
- GitHub Repository
- NPM Package
- Issue Tracker
๐ท๏ธ Keywords
color, colour, srgb, lab, lch, oklab, oklch, cielab, ciecam16, wcag, contrast, color-science, color-space, color-conversion, accessibility, a11y, color-difference, ciede2000, adaptive-oklab, color-appearance`---
๐จ Comprehensive โข ๐ Performant โข ๐ Well-Documented โข ๐ฌ Scientifically Accurate