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

• Go 1.21+
• Node.js 18+

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