🎨 Color Utils

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

npm install color-utils

import { AdaptiveOklab, parseCSS, calculateWcagContrast } from '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?

Exclusive Features You Won't Find Elsewhere

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

📦 Perfect For

| 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

Core Color Space Conversions

• 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

Advanced Color Models

• 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

Color Metrics & Analysis

• 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

Advanced Features

• 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

Installation

npm install color-utils
# or
yarn add color-utils
# or
pnpm add color-utils

Basic Usage

import { 
  parseSrgbHex, 
  srgbToLab, 
  calculateWcagContrast,
  AdaptiveOklab
} from '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);

Advanced Usage

import { parseCSS, gamutMapOklch, srgbToDisplayP3 } from '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

sRGB Module

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

CIELAB Module

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

Oklab Module

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

Adaptive Oklab

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

Color Metrics

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

✅ Completed

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

🚧 In Progress

• GitHub Actions CI/CD setup
• NPM package publication
• Performance optimizations
• Additional examples and tutorials

🔮 Future Features

• 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

# 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

• 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