ColorAssembly
High-performance WebAssembly color processing library for JavaScript/TypeScript applications
Overview
ColorAssembly is a comprehensive color manipulation library compiled from Go to WebAssembly. It provides extensive color space transformations, accessibility analysis tools, color generation utilities, and moreβall with zero dependencies and full TypeScript support.
Features
- π¨ 11 Color Spaces - Comprehensive support for modern and legacy color models
- βΏ Accessibility First - WCAG 2.1, APCA, color blindness simulation
- π― Color Generation - Harmonies, palettes, shades, tints, and variations
- π Color Matching - Match to 300+ named colors using Delta-E 2000
- β‘ High Performance - WebAssembly-powered for fast operations
- π¦ Zero Dependencies - Pure Go compiled to WASM
- π· TypeScript Native - Complete type definitions included
Installation
npm i@CymbolTech/colorassembly
Quick Start
import { loadColorAssembly } from '@cymbol/colorassembly';
const colorAssembly = await loadColorAssembly();
// Transform colors
const hsl = colorAssembly.transforms.rgbToHsl({ r: 255, g: 128, b: 0 });
// Check accessibility
const contrast = colorAssembly.analyze.contrastRatio(
{ r: 0, g: 0, b: 0 },
{ r: 255, g: 255, b: 255 }
); // 21
// Generate color harmonies
const triadic = colorAssembly.generate.triadic({ r: 255, g: 0, b: 0 });
Supported Color Spaces
ColorAssembly supports 11 different color spaces with full bidirectional conversion capabilities:
| Color Space |
Description |
Use Case |
| RGB |
Red, Green, Blue |
Web colors, displays |
| RGBA |
RGB with Alpha |
Transparency support |
| Hex |
Hexadecimal notation |
CSS, web development |
| HSL |
Hue, Saturation, Lightness |
Intuitive color manipulation |
| HSLA |
HSL with Alpha |
CSS colors with transparency |
| HSV |
Hue, Saturation, Value |
Color pickers, design tools |
| HSVA |
HSV with Alpha |
Transparent HSV colors |
| CMYK |
Cyan, Magenta, Yellow, Black |
Print design |
| LAB |
Lightness, A, B |
Perceptually uniform color |
| LCH |
Lightness, Chroma, Hue |
Perceptual color manipulation |
| XYZ |
CIE XYZ |
Color science foundation |
| OKLAB |
Modern perceptual color space |
Better perceptual uniformity |
| OKLCH |
Cylindrical OKLAB |
Modern color manipulation |
| LMS |
Long, Medium, Short cone response |
Color vision simulation |
| Linear RGB |
Gamma-corrected RGB |
Accurate color blending |
API Reference
Color Transformations (transforms)
All color space conversions with full bidirectional support:
RGB Conversions
// RGB β Hex
transforms.rgbToHex(rgb) transforms.hexToRgb(hex)
transforms.rgbaToHex(rgba) transforms.hexToRgba(hex)
// RGB β HSL
transforms.rgbToHsl(rgb) transforms.hslToRgb(hsl)
transforms.rgbaToHsla(rgba) transforms.hslaToRgba(hsla)
// RGB β HSV
transforms.rgbToHsv(rgb) transforms.hsvToRgb(hsv)
transforms.rgbaToHsva(rgba) transforms.hsvaToRgba(hsva)
// RGB β CMYK
transforms.rgbToCmyk(rgb) transforms.cmykToRgb(cmyk)
// RGB β XYZ
transforms.rgbToXyz(rgb) transforms.xyzToRgb(xyz)
// RGB β LAB
transforms.rgbToLab(rgb) transforms.labToRgb(lab)
// RGB β LCH
transforms.rgbToLch(rgb) transforms.lchToRgb(lch)
// RGB β OKLAB
transforms.rgbToOklab(rgb) transforms.oklabToRgb(oklab)
// RGB β OKLCH
transforms.rgbToOklch(rgb) transforms.oklchToRgb(oklch)
// RGB β LMS
transforms.rgbToLms(rgb) transforms.lmsToRgb(lms)
// RGB β Linear RGB
transforms.rgbToLinearRgb(rgb) transforms.linearRgbToRgb(linear)
Direct Conversions
// HSV β HSL
transforms.hsvToHsl(hsv) transforms.hslToHsv(hsl)
// LAB β LCH
transforms.labToLch(lab) transforms.lchToLab(lch)
// LAB β XYZ
transforms.labToXyz(lab) transforms.xyzToLab(xyz)
// OKLAB β OKLCH
transforms.oklabToOklch(oklab) transforms.oklchToOklab(oklch)
Color Analysis (analyze)
Luminance & Brightness
analyze.relativeLuminance(rgb) // WCAG relative luminance (0-1)
analyze.brightness(rgb) // Simple brightness (0-255)
analyze.perceivedBrightness(rgb) // Perceptual brightness
analyze.isLight(rgb) // Is color light?
analyze.isDark(rgb) // Is color dark?
analyze.lightOrDark(rgb) // "light" or "dark"
WCAG Contrast Analysis
analyze.contrastRatio(fg, bg) // Contrast ratio (1-21)
analyze.checkContrast(fg, bg) // Full WCAG compliance report
analyze.meetsContrastAA(fg, bg) // Normal text AA (4.5:1)
analyze.meetsContrastAAA(fg, bg) // Normal text AAA (7:1)
analyze.meetsLargeTextAA(fg, bg) // Large text AA (3:1)
analyze.meetsLargeTextAAA(fg, bg) // Large text AAA (4.5:1)
analyze.contrastWithWhite(rgb) // Contrast with white
analyze.contrastWithBlack(rgb) // Contrast with black
analyze.suggestTextColor(bg) // Best text color (black/white)
analyze.findAccessibleShade(color, bg, ratio) // Find accessible variant
APCA (Modern Contrast)
analyze.apcaContrast(text, bg) // APCA Lc value
analyze.checkApca(text, bg) // Full APCA report
analyze.meetsApcaBodyText(text, bg) // Body text minimum
analyze.meetsApcaLargeText(text, bg) // Large text minimum
analyze.meetsApcaNonText(text, bg) // UI components minimum
Color Difference (Delta-E)
analyze.deltaE2000(color1, color2) // CIE Delta-E 2000
analyze.analyzeColorDifference(c1, c2) // Full difference report
analyze.areColorsSimilar(c1, c2) // Similar colors?
analyze.areColorsIdentical(c1, c2) // Identical colors?
Adaptive Colors
analyze.adaptiveTextColor(bg) // Adaptive text color
analyze.ensureContrast(fg, bg, minContrast) // Ensure minimum contrast
analyze.generateContrastingColors(bg, count, min) // Multiple contrasting colors
analyze.blendWithBackground(fg, bg, opacity) // Blend with alpha
analyze.isSafeForColorBlind(c1, c2) // Color blind safe pair?
analyze.generateAccessiblePairs(base, count) // Accessible color pairs
Validation
analyze.isValidHex(hex) // Quick hex validation
analyze.validateHex(hex) // Detailed hex validation
analyze.validateColorString(str) // Validate any color string
analyze.normalizeHex(hex) // Normalize hex format
analyze.isGrayscale(rgb) // Is grayscale?
analyze.isNearGrayscale(rgb, tol) // Near grayscale?
analyze.colorType(rgb) // "grayscale", "chromatic", etc.
Color Generation (generate)
Shades, Tints & Scales
generate.shades(rgb, count) // Darker shades
generate.tints(rgb, count) // Lighter tints
generate.tones(rgb, count) // Muted tones
generate.scale(rgb, shades, tints) // Complete scale
generate.perceptualShades(rgb, count) // Perceptually uniform shades
generate.perceptualTints(rgb, count) // Perceptually uniform tints
Color Harmonies
generate.harmony(rgb, type) // Generic harmony generator
generate.complementary(rgb) // 2 colors (180Β°)
generate.analogous(rgb) // 3 colors (Β±30Β°)
generate.triadic(rgb) // 3 colors (120Β°)
generate.tetradic(rgb) // 4 colors (rectangular)
generate.splitComplementary(rgb) // 3 colors (150Β°, 210Β°)
generate.square(rgb) // 4 colors (90Β°)
generate.monochromatic(rgb) // Variations of same hue
Variations
generate.hueVariations(rgb, count, step) // Hue shifts
generate.saturationVariations(rgb, count) // Saturation range
generate.lightnessVariations(rgb, count) // Lightness range
generate.subtleVariations(rgb, count) // Subtle changes
generate.dramaticVariations(rgb, count) // Dramatic changes
Color Adjustments
generate.adjustHue(rgb, degrees) // Shift hue
generate.adjustSaturation(rgb, amount) // Adjust saturation
generate.adjustLightness(rgb, amount) // Adjust lightness
generate.saturate(rgb, amount) // Increase saturation
generate.desaturate(rgb, amount) // Decrease saturation
generate.lighten(rgb, amount) // Make lighter
generate.darken(rgb, amount) // Make darker
generate.invert(rgb) // Invert color
generate.grayscale(rgb) // Convert to grayscale
generate.mix(color1, color2, weight) // Mix two colors
Color Blindness Simulation
generate.simulateColorBlindness(rgb, type) // Simulate specific type
generate.simulateAllColorBlindness(rgb) // All types at once
Supported Types: protanopia, deuteranopia, tritanopia, protanomaly, deuteranomaly, tritanomaly, achromatopsia, achromatomaly
Color Matching
generate.findClosestColor(rgb) // Find closest named color
generate.findClosestColors(rgb, count) // Find N closest colors
generate.getColorCategories() // List all categories
generate.findColorsByCategory(category) // Colors in category
Categories: Red, Orange, Yellow, Green, Blue, Purple, Pink, Brown, Gray, White, Black
Palette Generation
generate.semanticPalette(rgb, mode) // Complete UI palette
generate.primaryScale(rgb) // 10-step primary scale
generate.neutralScale(rgb) // 10-step neutral scale
generate.darkModeColor(rgb) // Dark mode variant
generate.lightModeColor(rgb) // Light mode variant
Theme Modes: light, dark
Utility Functions
ColorAssembly also provides convenient utility functions:
import { Color, parseToRGB, detectFormat, css, batch } from '@cymbol/colorassembly';
// Parse any color format to RGB
const rgb = parseToRGB('#FF5733');
const rgb2 = parseToRGB('hsl(30, 100%, 50%)');
// Detect color format
const format = detectFormat('#FF5733'); // "hex"
// Convert to CSS string
const cssColor = css({ r: 255, g: 87, b: 51 }); // "rgb(255, 87, 51)"
// Chainable Color API
const result = new Color('#FF5733')
.lighten(20)
.saturate(10)
.rotate(30)
.toHex();
// Batch operations
const results = batch([
{ r: 255, g: 0, b: 0 },
{ r: 0, g: 255, b: 0 },
{ r: 0, g: 0, b: 255 }
], (color, api) => api.transforms.rgbToHsl(color));
Framework Integration
React
import { useEffect, useState } from 'react';
import { loadColorAssembly, ColorAssemblyAPI } from '@cymbol/colorassembly';
function useColorAssembly() {
const [api, setApi] = useState<ColorAssemblyAPI | null>(null);
useEffect(() => {
loadColorAssembly().then(setApi);
}, []);
return api;
}
function ColorPicker() {
const colorAssembly = useColorAssembly();
if (!colorAssembly) return <div>Loading...</div>;
// Use colorAssembly.transforms, .analyze, .generate
}
Vue
<script setup lang="ts">
import { ref, onMounted } from 'vue';
import { loadColorAssembly, type ColorAssemblyAPI } from '@cymbol/colorassembly';
const colorAssembly = ref<ColorAssemblyAPI | null>(null);
onMounted(async () => {
colorAssembly.value = await loadColorAssembly();
});
</script>
Performance
- WASM Size: ~870KB gzipped / ~3.1MB uncompressed
- Load Time: <100ms (with caching)
- Operations: <1ms for most conversions
- Batch Processing: Highly optimized for multiple colors
The relatively large binary size includes the Go runtime but enables high-performance execution and is downloaded once per deployment.
Browser Support
- Chrome 57+
- Firefox 52+
- Safari 11+
- Edge 79+
- Node.js 16+ (with WASM support)
Building from Source
Prerequisites
Build
# Install dependencies
npm install
# Build WASM + TypeScript
npm run build
# Run tests
npm test
Contributing
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
License
MIT License - see LICENSE for details.
Acknowledgments
Based on industry standards and scientific research:
- W3C CSS Color Level 4 Specification
- WCAG 2.1 Accessibility Guidelines
- APCA (Accessible Perceptual Contrast Algorithm)
- CIE Color Difference Formulas (Delta-E 2000)
- Brettel et al. Color Blindness Simulation
- Oklab Color Space (BjΓΆrn Ottosson)
Made with β€οΈ by Cymbol Technologies