🎨 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.

🚀 Quick Start

``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);
`

🌟 Why Color Utils?

$3

| 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 |

$3

| 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 |

📊 Library Comparison

| 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 |

📚 Documentation

- 🎯 Examples
- 🔄 Migration Guide
- 🐛 Troubleshooting
- ⚠️ Known Issues
- 📏 Range Standards
- 📖 TypeScript Definitions

✅ Production-Ready Features

- sRGB, Lab/LCh, Oklab/OkLCh conversions (100% test coverage)
- XYZ color space transformations with clear range documentation
- Adaptive Oklab with comprehensive edge case handling
- WCAG contrast calculations
- Hex color parsing and formatting
- Display P3 and Rec. 2020 conversions
- CSS Color Level 4 parsing
- CIECAM16 and CAM16-UCS color appearance modeling
- Chromatic adaptation (Bradford, CAT02, CAT16, Von Kries)
- Basic gamut mapping

⚠️ Beta Features

- CUSP Gamut Mapping (partial implementation)
- Advanced interpolation methods
- Some edge cases in extreme color ranges

> Note: Core functionality is stable and well-tested (95.6% test coverage)

🎨 Complete Feature Set

$3

- sRGB - Standard RGB with gamma correction and hex utilities
- CIELAB/LCH - Perceptually uniform color spaces
- Oklab/OkLCh - Modern perceptually uniform spaces with improved hue uniformity
- XYZ - CIE 1931 color space (D65 illuminant)
- Display P3 - Wide gamut RGB for modern displays
- Rec. 2020 - Ultra-wide gamut for UHDTV and HDR content

$3

- Adaptive Oklab (AOkLab) - Novel surround-adapted Oklab implementation
- Adjusts for white, gray, and dark viewing conditions
- Maintains hue uniformity while adapting lightness and chroma
- CIECAM16 - Complete color appearance model
- Accounts for chromatic adaptation and viewing conditions
- Predicts appearance correlates (Lightness J, Chroma C, Hue h)
- CAM16-UCS - Perceptually uniform version of CIECAM16
- Better color difference calculations
- Uniform color interpolation

$3

- WCAG Contrast - Web Content Accessibility Guidelines contrast ratios
- CIEDE2000 - Advanced perceptual color difference formula
- Relative Luminance - CIE relative luminance calculations
- Oklch Difference - Perceptual difference in Oklch space

$3

- Chroma Control - Sophisticated chroma adjustment with WCAG contrast targeting
- Find maximum chroma for target luminance
- Adjust colors to meet specific contrast requirements
- Integration with Adaptive Oklab for surround-aware adjustments
- Gamut Mapping - CSS Color Module Level 4 compliant algorithms
- Binary search for maximum in-gamut chroma
- CUSP-based mapping for saturation preservation
- Adaptive mapping with rendering intents
- Chromatic Adaptation - Transform colors between illuminants
- Bradford, CAT02, CAT16, Von Kries transforms
- Standard illuminants (D50, D65, A, F series)
- CCT calculation and white point utilities
- CSS Color Parsing - Full CSS Color Level 4 support
- Parse modern syntax: lab(), lch(), oklab(), oklch(), color()
- Legacy formats: hex, rgb(), hsl(), named colors
- Format colors to any CSS notation

💻 Installation & Usage

$3

`bash
npm install @markgorzynski/color-utils


or

yarn add @markgorzynski/color-utils

or

pnpm add @markgorzynski/color-utils
`

$3

`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);
`

$3

`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');
`

📚 API Highlights

$3


`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 test

Run with coverage

npm run test:coverage

Run 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