# Universal Color Code Converter (HEX, RGB, HSL, CMYK): Technical Architecture & Colorimetry Guide

Digital color representation is situated at the intersection of electromagnetic radiation physics, biological human perception, and display hardware engineering. In modern full-stack web development, design token systems, mobile application architecture, and print prepress workflows, software engineers must continuously convert between additive emissive color models (sRGB, HEX), cylindrical perceptual coordinate systems (HSL, HSV/HSB), and physical subtractive ink models (CMYK).

Navigating these color models requires strict algorithmic accuracy. Shifting between non-linear gamma-corrected color spaces, cylindrical transformations, and subtractive ink limits presents complex edge cases—including floating-point quantization errors, out-of-gamut clipping, hue singularities at zero saturation, and non-linear relative luminance calculations for accessibility audits.

The ToolsAA Universal Color Code Converter provides a zero-latency, production-grade online color picker, hex to rgb converter, rgb to hsl engine, and cmyk color converter. Built from the ground up on a pure client-side architecture ("use client"), 100% of string parsing, matrix transforms, gamma-corrected relative luminance calculations, and tonal palette generations execute directly inside your browser memory sandbox. Zero bytes of proprietary design tokens, enterprise brand assets, or user telemetry ever leave your workstation or touch an external network proxy.

# Comprehensive Overview & Real-World Use Cases

Digital displays and printing presses communicate chromatic data through distinct mathematical abstractions. Understanding the underlying mechanics of each color model is foundational to architecting responsive design systems and cross-media asset pipelines.

+-----------------------------------------------------------------------------------+
|                        ToolsAA In-Browser Color Pipeline                          |
|         (100% Client-Side Execution | Zero Network Calls | In-Memory Sandbox)      |
+-----------------------------------------------------------------------------------+
                                         │
               Input Stream (Hex, RGB, HSL, HSV, CMYK, CSS Keywords)
                                         │
                                         ▼
                    ┌─────────────────────────────────────────┐
                    │      High-Performance Color Parser      │
                    │   - Hex Normalization (3, 4, 6, 8-char) │
                    │   - Canvas 2D Fallback Rasterization    │
                    │   - Alpha Channel Extraction            │
                    └─────────────────────────────────────────┘
                                         │
                                         ▼
                    ┌─────────────────────────────────────────┐
                    │    Canonical sRGB Float Representation  │
                    │      r, g, b in [0.0, 1.0] | a in [0,1] │
                    └─────────────────────────────────────────┘
                                         │
        ┌───────────────────┬────────────┴───────┬───────────────────┐
        ▼                   ▼                    ▼                   ▼
┌──────────────┐    ┌──────────────┐     ┌──────────────┐    ┌──────────────┐
│  HEX / sRGB  │    │  HSL / HSV   │     │  CMYK Ink    │    │  WCAG 2.1    │
│  8-bit / Hex │    │  Cylindrical │     │  Subtractive │    │  Luminance   │
│  Bit Shifting│    │  Chroma Math │     │  Key Density │    │  Contrast CR │
└──────────────┘    └──────────────┘     └──────────────┘    └──────────────┘

# The Core Color Spaces Explained

• HEX (Hexadecimal Notation): A compact base-16 string serialization of standard 8-bit additive sRGB channels. A standard six-digit hex code (#RRGGBB) packs three 8-bit bytes ($2^{24} \approx 16.78\text{ million}$ colors). Modern specifications (CSS Color Module Level 4) introduce eight-digit hex codes (#RRGGBBAA), incorporating an additional 8-bit alpha transparency channel.
• RGB / RGBA (Red, Green, Blue): The foundational additive color model utilized by cathode-ray tubes (CRTs), liquid-crystal displays (LCDs), and organic light-emitting diodes (OLEDs). Colors are produced by emitting wavelengths at peak intensities of approximately 700 nm (Red), 546.1 nm (Green), and 435.8 nm (Blue). Each integer channel spans $0$ to $255$.
• HSL (Hue, Saturation, Lightness): Developed in the 1970s to project Cartesian RGB cubes into a double-cone cylindrical coordinate system. Lightness ($L \in [0\%, 100\%]$) spans pure black ($0\%$) to pure white ($100\%$), with pure chromatic primaries residing exactly at $L = 50\%$. This makes HSL exceptionally suited for creating programmatic UI states (tints, shades, active states) by adjusting a single scalar.
• HSV / HSB (Hue, Saturation, Value / Brightness): A single-cone cylindrical projection where Value ($V \in [0\%, 100\%]$) measures the maximum intensity of any single RGB channel. Value $100\%$ contains both pure white and pure vibrant chromatic colors. HSV is the standard mathematical model powering visual color picker spectrums, saturation-brightness pickers, and digital illustration tools (e.g., Photoshop, Figma).
• CMYK (Cyan, Magenta, Yellow, Key / Black): A subtractive four-color printing model. Unlike emissive displays, physical ink absorbs (subtracts) specific wavelengths from white ambient light. Cyan absorbs red, magenta absorbs green, and yellow absorbs blue. Because combining real-world chemical impurities in C, M, and Y yields an imperfect muddy brown rather than optical black, a dedicated Key (black) plate is introduced to increase optical density and reduce ink volume.

# High-Impact Engineering Use Cases

• Design System Tokenization & Dynamic Theming: Engineering design systems (e.g., Tailwind CSS, Material Design) requires decomposing base hex codes into HSL or RGB channel variables. Decoupling hue and saturation enables developers to synthesize dark mode variants, hover overlays, and disabled states by dynamically interpolating lightness or applying CSS rgba() alpha overlays.
• Cross-Media Digital-to-Print Hand-offs: Preparing digital vector assets, branding packages, or SVG graphics for commercial print requires verifying whether screen sRGB colors map within ISO 12647-2 print gamuts. An online cmyk color converter allows designers to detect out-of-gamut clipping early, preventing costly color shifts during four-color offset printing.
• Automated Accessibility & WCAG Compliance: Design teams must ensure contrast compliance under W3C WCAG 2.1 Level AA (4.5:1 for regular text, 3:1 for large text) and Level AAA (7:1 for regular text). Converting colors to linear photometric values enables instant mathematical contrast auditing against arbitrary backgrounds.
• WebGL, HTML5 Canvas & GPU Shader Pipelines: Fragment shaders in WebGL and WebGPU ingest color inputs as 32-bit floating-point vectors (vec4(r, g, b, a)) normalized to $[0.0, 1.0]$. Frontend graphics pipelines utilize real-time converters to map CSS hex strings into typed arrays (Float32Array) without garbage collection overhead.
• Native Mobile Cross-Compilation: Cross-platform frameworks require divergent syntax: Android Jetpack Compose utilizes 0xAARRGGBB 32-bit integers, Flutter consumes Color(0xFFRRGGBB), and iOS SwiftUI requires fractional components Color(red:green:blue:). Converting color formats instantaneously bridges platform incompatibilities.

# Zero-Knowledge Architecture: Why Privacy Matters in Color Utilities

Design tokens, unpublished brand rebrands, internal design systems, and enterprise design prototypes often embody proprietary intellectual property under strict non-disclosure agreements (NDAs). Transmitting color palettes to cloud-hosted APIs exposes unreleased product styling, campaign themes, and application designs to server access logs and third-party tracking cookies.

ToolsAA eliminates this attack vector entirely. All parsing, mathematical conversions, palette generators, and contrast algorithms execute locally within your browser's V8 or JavaScriptCore runtime. No analytics payloads, websocket sessions, or external HTTP requests are generated. Your proprietary color data remains strictly isolated in your machine's volatile memory.

# Technical Architecture & How It Works Under The Hood

High-precision color conversion requires strict adherence to international colorimetry standards and rigorous mathematical formulation. Below is the comprehensive technical breakdown of how the ToolsAA color engine processes color spaces under the hood.

# 1. Foundational Standards & Specifications

• W3C CSS Color Module Level 3 & Level 4: Standardizes comma-separated legacy notations (rgb(255, 0, 0)) alongside modern space-separated notations with slash alpha syntax (rgb(255 0 0 / 0.5), hsl(180deg 100% 50% / 80%)).
• IEC 61966-2-1 (sRGB): Standardizes the default color space of the web, calibrated to the CIE Standard Illuminant D65 white point ($x = 0.3127, y = 0.3290$) with an average display gamma of $\gamma \approx 2.2$.
• CIE 1931 $XYZ$ Color Space: The standard observer color space developed by the International Commission on Illumination, forming the bridge between human tri-stimulus spectral responses and digital coordinate models.
• W3C Web Content Accessibility Guidelines (WCAG) 2.1: Formulates relative luminance ($L$) and contrast ratios using linearized sRGB channels.

# 2. Mathematical Formulations & Transfer Functions

# A. Hexadecimal to RGB Decomposition

Hexadecimal color strings represent binary channel bytes in base-16. Parsing begins by stripping any # or 0x prefixes and evaluating string length:

• 3-digit shorthand (#RGB): Expanded to 6 digits by duplicating each nibble:

$$R = R1 R1{16} = R1 \times 17, \quad G = G1 G1{16} = G1 \times 17, \quad B = B1 B1{16} = B1 \times 17$$

• 4-digit shorthand with alpha (#RGBA): Similarly expanded:

$$A = (A_1 \times 17) / 255$$

• 6-digit standard (#RRGGBB): Parsed via bitwise operations:

$$\text{Value} = \text{parseInt}(\text{hex}, 16)$$ $$R = (\text{Value} \gg 16) \ \& \ 255, \quad G = (\text{Value} \gg 8) \ \& \ 255, \quad B = \text{Value} \ \& \ 255$$

• 8-digit standard (#RRGGBBAA): The trailing byte yields alpha:

$$A = (\text{Value} \ \& \ 255) / 255$$

# B. RGB to HSL Transformation

Let normalized coordinates be $r = R/255$, $g = G/255$, and $b = B/255$, such that $r, g, b \in [0, 1]$.

1. Determine extrema:

$$M = \max(r, g, b), \quad m = \min(r, g, b), \quad \Delta = M - m$$

1. Compute Lightness ($L$):

$$L = \frac{M + m}{2}$$

1. Compute Saturation ($S$):

$$\text{If } \Delta = 0, \quad S = 0 \quad (\text{achromatic gray})$$ $$\text{If } \Delta \neq 0, \quad S = \frac{\Delta}{1 - |2L - 1|}$$

1. Compute Hue ($H \in [0^{\circ, 360}\circ)$):

$$\text{If } \Delta = 0, \quad H = 0^\circ$$ $$\text{If } M = r, \quad H = 60^\circ \times \left( \frac{g - b}{\Delta} \pmod 6 \right)$$ $$\text{If } M = g, \quad H = 60^\circ \times \left( \frac{b - r}{\Delta} + 2 \right)$$ $$\text{If } M = b, \quad H = 60^\circ \times \left( \frac{r - g}{\Delta} + 4 \right)$$ If $H < 0^{\circ$, add $360}\circ$.

# C. HSL to RGB Inverse Transformation

Given $H \in [0, 360)$, $S \in [0, 1]$, and $L \in [0, 1]$:

1. Compute Chroma ($C$) and intermediate scalar ($X$):

$$C = (1 - |2L - 1|) \times S$$ $$H' = \frac{H}{60^\circ}$$ $$X = C \times (1 - |(H' \pmod 2) - 1|)$$

1. Match lightness baseline ($m$):

$$m = L - \frac{C}{2}$$

1. Assign raw coordinates $(r1, g1, b_1)$ along the hexagonal sector:

$$(r1, g1, b_1) = \begin{cases} (C, X, 0) & 0 \le H' < 1 \\ (X, C, 0) & 1 \le H' < 2 \\ (0, C, X) & 2 \le H' < 3 \\ (0, X, C) & 3 \le H' < 4 \\ (X, 0, C) & 4 \le H' < 5 \\ (C, 0, X) & 5 \le H' < 6 \end{cases}$$

1. Reconstruct 8-bit RGB channels:

$$R = \text{round}((r1 + m) \times 255), \quad G = \text{round}((g1 + m) \times 255), \quad B = \text{round}((b_1 + m) \times 255)$$

# D. RGB to CMYK Transformation (Subtractive Plate Model)

In commercial four-color printing, physical subtractive pigments absorb light. The fundamental mathematical conversion from normalized additive $r, g, b \in [0, 1]$ to subtractive $C, M, Y, K \in [0, 1]$ uses Under Color Removal (UCR):

1. Compute black key ink fraction ($K$):

$$K = 1 - \max(r, g, b)$$

1. Handle pure black singularity:

$$\text{If } K = 1, \quad C = 0, \ M = 0, \ Y = 0$$

1. Otherwise, isolate chromatic inks by removing black key contribution:

$$C = \frac{1 - r - K}{1 - K}, \quad M = \frac{1 - g - K}{1 - K}, \quad Y = \frac{1 - b - K}{1 - K}$$ To convert CMYK back to RGB: $$R = \text{round}(255 \times (1 - C) \times (1 - K))$$ $$G = \text{round}(255 \times (1 - M) \times (1 - K))$$ $$B = \text{round}(255 \times (1 - Y) \times (1 - K))$$

# E. Relative Luminance & WCAG 2.1 Contrast Ratio

The human eye does not perceive green, red, and blue photons with equal brightness due to the spectral response of retinal cone cells (photopic luminosity function $V(\lambda)$). Standard 8-bit sRGB values are non-linear; they must first undergo gamma expansion to linear photometric space before luminance can be computed.

1. Linearize RGB channels (Inverse sRGB Companding):

$$\text{For } c \in \{r, g, b\}: \quad c_{\text{linear}} = \begin{cases} \frac{c}{12.92} & c \le 0.03928 \\ \left( \frac{c + 0.055}{1.055} \right)^{2.4} & c > 0.03928 \end{cases}$$

1. Compute Relative Luminance ($L$) according to IEC 61966-2-1:

$$L = 0.2126 \times r{\text{linear}} + 0.7152 \times g{\text{linear}} + 0.0722 \times b_{\text{linear}}$$

1. Compute Contrast Ratio ($CR$):

Given two colors with relative luminances $L1$ and $L2$, where $L1 \ge L2$: $$CR = \frac{L1 + 0.05}{L2 + 0.05}$$ The resulting ratio ranges from $1:1$ (identical colors) to $21:1$ (pure black against pure white).

# 3. Browser Web APIs, Native EyeDropper & Canvas Fallback

ToolsAA leverages modern browser Web APIs to achieve high accuracy and seamless user experience:

• W3C EyeDropper API: For Chromium-based browsers, ToolsAA connects to window.EyeDropper. This allows users to sample exact RGB hex values from any pixel on their display screen—including operating system UI, desktop wallpapers, and external application windows—without violating the browser security boundary.
• HTML5 Canvas 2D Parser Fallback: To parse obscure CSS named color keywords (e.g., rebeccapurple, papayawhip, cornflowerblue) or browser-specific color definitions without maintaining a bloated multi-megabyte lookup dictionary, ToolsAA uses an in-memory OffscreenCanvas or detached CanvasRenderingContext2D:

```javascript const ctx = document.createElement("canvas").getContext("2d"); ctx.fillStyle = inputString; const computedHex = ctx.fillStyle; // Browser engine parses and resolves string ```

• Memory Management & Typed Arrays: To ensure zero memory leakage and 60fps responsiveness during real-time slider drags, all channel transformations are computed using primitive scalar arithmetic and reusable Uint8ClampedArray buffers, avoiding garbage collection overhead.

# Step-by-Step Practical Usage Guide

Follow these clear, practical steps to convert, manipulate, and audit color values using the ToolsAA Universal Color Code Converter:

# Step 1: Inputting Any Color String or Format

Enter your color string into the unified search and input box. The intelligent parser auto-detects:

• Standard Hex: #6366f1, #38bdf8, ec4899
• Hex with Alpha: #6366f180, #10b981cc
• Functional CSS: rgb(99, 102, 241), rgba(236, 72, 153, 0.8)
• Modern Space-Separated CSS: rgb(99 102 241 / 0.5), hsl(240deg 84% 67%)
• Subtractive CMYK: cmyk(59%, 58%, 0%, 5%)
• CSS Named Keywords: crimson, royalblue, forestgreen, transparent

# Step 2: Sampling Pixels via Native EyeDropper or Interactive Spectrum

• Click the Eyedropper icon (Pipette) to activate OS-level pixel sampling. Click anywhere on your screen to extract an exact color value.
• Alternatively, use the interactive 2D Saturation-Value box and 1D Hue slider to intuitively explore color nuances and tweak brightness.

# Step 3: Inspecting Instant Multiformat Conversions

Once a color is loaded, the tool instantaneously displays synchronized representations:

• HEX: 6-digit #RRGGBB and 8-digit #RRGGBBAA with alpha channel.
• RGB: Comma-separated rgb(r, g, b) and CSS Level 4 space-separated syntax.
• HSL: Perceptually intuitive cylindrical degrees and percentages (hsl(h, s%, l%)).
• HSV: Ideal for graphic design parameters (hsv(h, s%, v%)).
• CMYK: Print prepress ink percentages (cmyk(c%, m%, y%, k%)).
• One-click copy buttons allow instant copying of any format directly to your clipboard.

# Step 4: Generating Tonal Palettes, Shades, and Harmonies

Explore programmatic color relationships generated automatically:

• Shades & Tints Scale: An 11-step tonal ramp (from 50 to 950) generated by interpolating the base color with pure white (#ffffff) and pure black (#000000), formatted identically to Tailwind CSS color scales.
• Harmonic Palettes: Inspect complementary (opposite $180^{\circ$ hue), analogous ($\pm 30}\circ$), triadic ($\pm 120^\circ$), and split-complementary color combinations for UI theming.

# Step 5: Auditing WCAG 2.1 Accessibility & Contrast Compliance

Review the integrated accessibility audit table:

• Evaluate contrast ratios computed against pure white (#ffffff) and deep obsidian black (#09090b).
• Verify whether your color passes WCAG AA ($4.5:1$ for body text, $3:1$ for large text/icons) and WCAG AAA ($7.0:1$ for enhanced text).
• When testing semi-transparent colors, the tool executes alpha blending math over standard backdrops to deliver true rendered contrast ratios.

# Code Implementations in Modern TypeScript/JavaScript and Python

To integrate bidirectional color conversion into your own backend APIs, CLI build tools, or frontend component libraries, use the following production-grade implementations.

# 1. Modern TypeScript / JavaScript Implementation

This self-contained TypeScript module provides strict type definitions, robust regex parsing for 3, 4, 6, and 8-digit hex codes, full RGB/HSL/HSV/CMYK conversions, and WCAG 2.1 contrast calculations.

/**
 * ToolsAA Colorimetry Engine - Production TypeScript Implementation
 * Pure client-side mathematical color conversions and accessibility audits.
 */

export interface RGBA {
  r: number; // 0 - 255
  g: number; // 0 - 255
  b: number; // 0 - 255
  a: number; // 0 - 1
}

export interface HSL {
  h: number; // 0 - 360
  s: number; // 0 - 100
  l: number; // 0 - 100
  a: number; // 0 - 1
}

export interface HSV {
  h: number; // 0 - 360
  s: number; // 0 - 100
  v: number; // 0 - 100
  a: number; // 0 - 1
}

export interface CMYK {
  c: number; // 0 - 100
  m: number; // 0 - 100
  y: number; // 0 - 100
  k: number; // 0 - 100
}

/** Clamps a numeric value within inclusive bounds */
function clamp(val: number, min: number, max: number): number {
  return Math.max(min, Math.min(max, val));
}

/** Converts an 8-bit hex string (3, 4, 6, or 8 characters) to RGBA */
export function hexToRgb(hex: string): RGBA | null {
  const cleanHex = hex.trim().replace(/^#/, "");

  // Shorthand: #RGB (3) or #RGBA (4)
  if (cleanHex.length === 3 || cleanHex.length === 4) {
    const r = parseInt(cleanHex[0] + cleanHex[0], 16);
    const g = parseInt(cleanHex[1] + cleanHex[1], 16);
    const b = parseInt(cleanHex[2] + cleanHex[2], 16);
    const a = cleanHex.length === 4 ? parseInt(cleanHex[3] + cleanHex[3], 16) / 255 : 1;
    if (isNaN(r) || isNaN(g) || isNaN(b) || isNaN(a)) return null;
    return { r, g, b, a: Number(a.toFixed(3)) };
  }

  // Standard: #RRGGBB (6) or #RRGGBBAA (8)
  if (cleanHex.length === 6 || cleanHex.length === 8) {
    const r = parseInt(cleanHex.substring(0, 2), 16);
    const g = parseInt(cleanHex.substring(2, 4), 16);
    const b = parseInt(cleanHex.substring(4, 6), 16);
    const a = cleanHex.length === 8 ? parseInt(cleanHex.substring(6, 8), 16) / 255 : 1;
    if (isNaN(r) || isNaN(g) || isNaN(b) || isNaN(a)) return null;
    return { r, g, b, a: Number(a.toFixed(3)) };
  }

  return null;
}

/** Converts RGBA to 6-digit or 8-digit Hex string */
export function rgbToHex(rgba: RGBA, includeAlpha: boolean = false): string {
  const r = clamp(Math.round(rgba.r), 0, 255).toString(16).padStart(2, "0");
  const g = clamp(Math.round(rgba.g), 0, 255).toString(16).padStart(2, "0");
  const b = clamp(Math.round(rgba.b), 0, 255).toString(16).padStart(2, "0");

  if (includeAlpha || rgba.a < 1) {
    const a = clamp(Math.round(rgba.a * 255), 0, 255).toString(16).padStart(2, "0");
    return `#${r}${g}${b}${a}`.toUpperCase();
  }
  return `#${r}${g}${b}`.toUpperCase();
}

/** Converts RGBA to Cylindrical HSL */
export function rgbToHsl(rgba: RGBA): HSL {
  const r = clamp(rgba.r, 0, 255) / 255;
  const g = clamp(rgba.g, 0, 255) / 255;
  const b = clamp(rgba.b, 0, 255) / 255;

  const max = Math.max(r, g, b);
  const min = Math.min(r, g, b);
  const delta = max - min;
  const l = (max + min) / 2;

  let h = 0;
  let s = 0;

  if (delta !== 0) {
    s = l > 0.5 ? delta / (2 - max - min) : delta / (max + min);
    switch (max) {
      case r: h = ((g - b) / delta + (g < b ? 6 : 0)) / 6; break;
      case g: h = ((b - r) / delta + 2) / 6; break;
      case b: h = ((r - g) / delta + 4) / 6; break;
    }
  }

  return {
    h: Math.round(h * 360),
    s: Math.round(s * 100),
    l: Math.round(l * 100),
    a: rgba.a,
  };
}

/** Converts HSL back to RGBA */
export function hslToRgb(hsl: HSL): RGBA {
  const h = (hsl.h % 360) / 360;
  const s = clamp(hsl.s, 0, 100) / 100;
  const l = clamp(hsl.l, 0, 100) / 100;

  if (s === 0) {
    const val = Math.round(l * 255);
    return { r: val, g: val, b: val, a: hsl.a };
  }

  const hue2rgb = (p: number, q: number, t: number) => {
    let tNorm = t;
    if (tNorm < 0) tNorm += 1;
    if (tNorm > 1) tNorm -= 1;
    if (tNorm < 1 / 6) return p + (q - p) * 6 * tNorm;
    if (tNorm < 1 / 2) return q;
    if (tNorm < 2 / 3) return p + (q - p) * (2 / 3 - tNorm) * 6;
    return p;
  };

  const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
  const p = 2 * l - q;

  return {
    r: Math.round(hue2rgb(p, q, h + 1 / 3) * 255),
    g: Math.round(hue2rgb(p, q, h) * 255),
    b: Math.round(hue2rgb(p, q, h - 1 / 3) * 255),
    a: hsl.a,
  };
}

/** Converts RGBA to Subtractive CMYK */
export function rgbToCmyk(rgba: RGBA): CMYK {
  const r = clamp(rgba.r, 0, 255) / 255;
  const g = clamp(rgba.g, 0, 255) / 255;
  const b = clamp(rgba.b, 0, 255) / 255;

  const k = 1 - Math.max(r, g, b);
  if (k >= 0.9999) {
    return { c: 0, m: 0, y: 0, k: 100 };
  }

  return {
    c: Math.round(((1 - r - k) / (1 - k)) * 100),
    m: Math.round(((1 - g - k) / (1 - k)) * 100),
    y: Math.round(((1 - y - k) / (1 - k)) * 100),
    k: Math.round(k * 100),
  };
}

/** Calculates WCAG 2.1 relative luminance using sRGB gamma expansion */
export function getRelativeLuminance(rgba: RGBA): number {
  const linearize = (channel: number) => {
    const c = clamp(channel, 0, 255) / 255;
    return c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
  };

  const rLin = linearize(rgba.r);
  const gLin = linearize(rgba.g);
  const bLin = linearize(rgba.b);

  return 0.2126 * rLin + 0.7152 * gLin + 0.0722 * bLin;
}

/** Computes WCAG 2.1 contrast ratio between two colors (ranges from 1.0 to 21.0) */
export function getContrastRatio(colorA: RGBA, colorB: RGBA): number {
  const lumA = getRelativeLuminance(colorA);
  const lumB = getRelativeLuminance(colorB);
  const brighter = Math.max(lumA, lumB);
  const darker = Math.min(lumA, lumB);
  return Number(((brighter + 0.05) / (darker + 0.05)).toFixed(2));
}

# 2. Modern Python 3 Implementation

This Python 3 script uses standard library type hinting and @dataclass decorators to provide robust color space conversions and WCAG contrast ratio calculations for backend data processing and automated testing.

"""
ToolsAA Colorimetry Engine - Production Python 3 Implementation
Bidirectional color conversion and WCAG 2.1 contrast calculations.
"""

from dataclasses import dataclass
import math
import re
from typing import Optional, Tuple


@dataclass(frozen=True)
class RGBA:
    r: int  # 0 to 255
    g: int  # 0 to 255
    b: int  # 0 to 255
    a: float = 1.0  # 0.0 to 1.0


@dataclass(frozen=True)
class HSL:
    h: int  # 0 to 360 degrees
    s: int  # 0 to 100 percent
    l: int  # 0 to 100 percent
    a: float = 1.0


@dataclass(frozen=True)
class CMYK:
    c: int  # 0 to 100 percent
    m: int  # 0 to 100 percent
    y: int  # 0 to 100 percent
    k: int  # 0 to 100 percent


def hex_to_rgb(hex_code: str) -> Optional[RGBA]:
    """Parses 3, 4, 6, or 8-digit hexadecimal color string into an RGBA object."""
    hex_clean = hex_code.strip().lstrip("#")

    if len(hex_clean) == 3:  # Shorthand #RGB
        r = int(hex_clean[0] * 2, 16)
        g = int(hex_clean[1] * 2, 16)
        b = int(hex_clean[2] * 2, 16)
        return RGBA(r, g, b, 1.0)

    if len(hex_clean) == 4:  # Shorthand #RGBA
        r = int(hex_clean[0] * 2, 16)
        g = int(hex_clean[1] * 2, 16)
        b = int(hex_clean[2] * 2, 16)
        a = round(int(hex_clean[3] * 2, 16) / 255.0, 3)
        return RGBA(r, g, b, a)

    if len(hex_clean) == 6:  # Standard #RRGGBB
        r = int(hex_clean[0:2], 16)
        g = int(hex_clean[2:4], 16)
        b = int(hex_clean[4:6], 16)
        return RGBA(r, g, b, 1.0)

    if len(hex_clean) == 8:  # Standard #RRGGBBAA
        r = int(hex_clean[0:2], 16)
        g = int(hex_clean[2:4], 16)
        b = int(hex_clean[4:6], 16)
        a = round(int(hex_clean[6:8], 16) / 255.0, 3)
        return RGBA(r, g, b, a)

    return None


def rgb_to_hex(color: RGBA, include_alpha: bool = False) -> str:
    """Formats an RGBA dataclass into an uppercase hex string."""
    r_hex = f"{max(0, min(255, color.r)):02X}"
    g_hex = f"{max(0, min(255, color.g)):02X}"
    b_hex = f"{max(0, min(255, color.b)):02X}"

    if include_alpha or color.a < 1.0:
        a_int = max(0, min(255, round(color.a * 255)))
        return f"#{r_hex}{g_hex}{b_hex}{a_int:02X}"
    return f"#{r_hex}{g_hex}{b_hex}"


def rgb_to_hsl(color: RGBA) -> HSL:
    """Converts RGBA coordinates to cylindrical HSL."""
    r = color.r / 255.0
    g = color.g / 255.0
    b = color.b / 255.0

    c_max = max(r, g, b)
    c_min = min(r, g, b)
    delta = c_max - c_min
    lum = (c_max + c_min) / 2.0

    if delta == 0:
        return HSL(0, 0, round(lum * 100), color.a)

    sat = delta / (2.0 - c_max - c_min) if lum > 0.5 else delta / (c_max + c_min)

    if c_max == r:
        hue = ((g - b) / delta + (6 if g < b else 0)) / 6.0
    elif c_max == g:
        hue = ((b - r) / delta + 2.0) / 6.0
    else:
        hue = ((r - g) / delta + 4.0) / 6.0

    return HSL(
        h=round(hue * 360),
        s=round(sat * 100),
        l=round(lum * 100),
        a=color.a
    )


def rgb_to_cmyk(color: RGBA) -> CMYK:
    """Converts RGBA coordinates to subtractive CMYK ink percentages."""
    r = color.r / 255.0
    g = color.g / 255.0
    b = color.b / 255.0

    k = 1.0 - max(r, g, b)
    if k >= 0.9999:
        return CMYK(0, 0, 0, 100)

    c = (1.0 - r - k) / (1.0 - k)
    m = (1.0 - g - k) / (1.0 - k)
    y = (1.0 - b - k) / (1.0 - k)

    return CMYK(
        c=round(c * 100),
        m=round(m * 100),
        y=round(y * 100),
        k=round(k * 100)
    )


def relative_luminance(color: RGBA) -> float:
    """Computes WCAG 2.1 relative luminance using sRGB gamma expansion."""
    def linearize(val: int) -> float:
        c = val / 255.0
        return c / 12.92 if c <= 0.03928 else math.pow((c + 0.055) / 1.055, 2.4)

    r_lin = linearize(color.r)
    g_lin = linearize(color.g)
    b_lin = linearize(color.b)

    return 0.2126 * r_lin + 0.7152 * g_lin + 0.0722 * b_lin


def wcag_contrast_ratio(c1: RGBA, c2: RGBA) -> float:
    """Calculates WCAG 2.1 contrast ratio between two colors (ranges from 1.0 to 21.0)."""
    l1 = relative_luminance(c1)
    l2 = relative_luminance(c2)
    brighter = max(l1, l2)
    darker = min(l1, l2)
    return round((brighter + 0.05) / (darker + 0.05), 2)


if __name__ == "__main__":
    # Test execution: Electric Indigo (#6366F1)
    indigo = hex_to_rgb("#6366F1")
    assert indigo is not None
    print(f"Loaded Color: {rgb_to_hex(indigo)}")
    print(f"HSL: {rgb_to_hsl(indigo)}")
    print(f"CMYK: {rgb_to_cmyk(indigo)}")

    white = RGBA(255, 255, 255)
    ratio = wcag_contrast_ratio(indigo, white)
    print(f"Contrast against White: {ratio}:1 (WCAG AA: {'PASS' if ratio >= 4.5 else 'FAIL'})")

# Common Pitfalls, Edge Cases & Troubleshooting Guide

Implementing and consuming color conversions often reveals unexpected behavioral quirks across browser engines and display profiles. Below are the most critical pitfalls and architectural solutions.

# 1. Gamut Clipping in Additive sRGB to Subtractive CMYK Conversions

• The Problem: Computer monitors emit light across the expansive sRGB or Display P3 color gamuts, while four-color offset presses reproduce colors using reflected light absorbed by physical inks. Highly saturated additive colors—such as electric neon green (#00FF00) or deep cyan (#00FFFF)—fall outside the physical reach of CMYK inks.
• The Impact: Mathematical CMYK conversion clips values to $100\%$, producing dull, muddy prints that do not match the on-screen design.
• The Solution: Understand that pure mathematical RGB-to-CMYK conversion is an idealized approximation. Commercial production workflows require color management engines (such as LittleCMS or Adobe ACE) applying ICC device color profiles (e.g., US Web Coated SWOP v2 or ISO Coated v2) with perceptual or relative colorimetric rendering intents to compress out-of-gamut tones smoothly.

# 2. Shorthand Hexadecimal Parsing Gotchas

• The Problem: Developers frequently assume that shorthand #123 expands by appending zeros (#123000) or left-padding (#000123).
• The Impact: Severe chromatic distortion in dynamic CSS stylesheets.
• The Solution: CSS specifications mandate nibble replication. Each single character must be doubled: #123 represents #112233. Similarly, 4-character hex strings with alpha (#1238) expand to #11223388, where 88 represents an alpha channel of approximately $136/255 \approx 53.3\%$ opacity.

# 3. Calculating Relative Luminance Without Gamma Expansion

• The Problem: A common rookie error in calculating WCAG contrast ratios is applying the photopic weights directly to uncorrected 8-bit integers:

$$L_{\text{incorrect}} = 0.2126 \times \frac{R}{255} + 0.7152 \times \frac{G}{255} + 0.0722 \times \frac{B}{255}$$

• The Impact: This produces drastically incorrect contrast scores, failing accessibility audits and misclassifying readable text as inaccessible.
• The Solution: You must apply the piecewise inverse sRGB transfer function ($\text{threshold} = 0.03928$, power exponent $2.4$) to linearize photons before taking the weighted sum.

# 4. Hue Singularities at Zero Saturation (Achromatic Grays)

• The Problem: When $R = G = B$ (pure white, gray, or black), the delta between maximum and minimum channels is $\Delta = 0$. In cylindrical formulas, this causes a division by zero:

$$H = 60^\circ \times \frac{g - b}{0} \implies \text{NaN}$$

• The Impact: Color picker UI sliders snap unexpectedly to red ($0^\circ$) whenever saturation or lightness hits zero, resetting user hue adjustments.
• The Solution: Treat hue as undefined for achromatic values. When building interactive color pickers, cache the previously selected hue in state so that dragging the saturation or lightness slider to zero does not wipe out the user's active hue selection.

# 5. Alpha Compositing & Transparency Layering in Contrast Audits

• The Problem: Evaluating the contrast ratio of semi-transparent text (rgba(0, 0, 0, 0.6)) directly yields misleading results if the alpha channel is simply ignored.
• The Impact: Under-reporting accessibility violations for faint, low-contrast text overlays.
• The Solution: Apply Porter-Duff source-over alpha blending against the intended background before calculating luminance:

$$C{\text{composite}} = \text{round}(\alpha \times C{\text{foreground}} + (1 - \alpha) \times C_{\text{background}})$$ Evaluate the resulting opaque RGB color against the background luminance.

# 6. Cascading Quantization Loss Across Round-Trip Conversions

• The Problem: Repeatedly converting a color between integer 8-bit RGB and floating-point HSL introduces compounding rounding truncation:

$$\text{RGB}(128, 64, 32) \longrightarrow \text{HSL}(19^\circ, 60\%, 31\%) \longrightarrow \text{RGB}(126, 63, 32)$$

• The Impact: Colors visibly drift over time in stateful graphic manipulation tools.
• The Solution: Store the master canonical color state as high-precision floating-point numbers or 64-bit normalized floats. Derive formatted strings (Hex, RGB integers, HSL integers) strictly as projection outputs, never using truncated strings as intermediate state stores.

# 7. CSS Named Colors Historical Inconsistencies

• The Problem: The W3C CSS named color palette contains legacy artifacts from X11 color specifications. For instance, gray (#808080) has a lightness of $50\%$, whereas darkgray (#A9A9A9) has a lightness of $66\%$—making darkgray paradoxically lighter than gray.
• The Solution: Avoid relying on CSS named strings for mathematical styling. Always resolve names to definitive hex codes or HSL values prior to performing algorithmic color adjustments.

# Detailed FAQ Section

# Q1: How does a hex to rgb converter calculate RGB values from 3, 4, 6, and 8-digit hex codes?

Answer: Hexadecimal color codes represent byte values in base-16. For a 6-digit hex code (#RRGGBB), the string is split into three 2-character pairs, each converted to an integer from $0$ to $255$ via parseInt(pair, 16). For an 8-digit hex code (#RRGGBBAA), the fourth pair represents alpha transparency, calculated as $\text{byte} / 255$ to yield a decimal between $0.0$ and $1.0$.

For 3-digit shorthand (#RGB), CSS specifications mandate nibble replication: each character is doubled (#F80 becomes #FF8800, yielding $R=255, G=136, B=0$), rather than appending trailing zeros. For 4-digit shorthand (#RGBA), the fourth nibble is similarly duplicated to determine the alpha channel (#F80C becomes #FF8800CC).

# Q2: What is the core mathematical difference between the HSL and HSV (HSB) color spaces?

Answer: While both models map RGB onto cylindrical coordinates sharing the exact same Hue ($H \in [0^{\circ, 360}\circ)$), they model brightness and saturation fundamentally differently:

• In HSL (Lightness), the cylinder is a bi-cone. Pure white occurs exclusively at $L = 100\%$, pure black at $L = 0\%$, and maximum chromatic saturation resides halfway at $L = 50\%$. Lightness represents the midpoint of the extreme channels: $L = (\max + \min) / 2$.
• In HSV (Value / Brightness), the geometry is an inverted single cone. Value represents the maximum component alone: $V = \max(r, g, b)$. Consequently, $V = 100\%$ contains both pure white and fully saturated chromatic primaries (e.g., pure red #FF0000 has $V = 100\%$ and pure white #FFFFFF also has $V = 100\%$). HSV is preferred for graphical color pickers because varying saturation horizontally and brightness vertically aligns with physical paint mixing intuition.

# Q3: Can a mathematical cmyk color converter accurately predict physical print results?

Answer: Pure mathematical RGB-to-CMYK conversion (Under Color Removal / UCR) is an idealized formula that assumes perfect chemical pigments absorbing $100\%$ of targeted light wavelengths. In physical reality, real-world inks (printing on offset presses or digital dye-sublimation machines) contain chemical impurities, ink absorption characteristics, dot gain on paper stock, and maximum ink limit constraints (Total Area Coverage / TAC).

Furthermore, the additive sRGB screen gamut includes vibrant blues, greens, and neon highlights that physically cannot be rendered using subtractive CMYK pigments. To achieve accurate print proofs, graphic workflows rely on ICC color profiles (e.g., SWOP, GRACoL, FOGRA39) that apply non-linear gamut mapping and black generation algorithms (GCR/UCR).

# Q4: How is WCAG 2.1 color contrast calculated using relative luminance?

Answer: Under W3C WCAG 2.1, contrast ratio is calculated using relative luminance ($L$), defined as the perceived photometric brightness of a surface normalized from $0.0$ (black) to $1.0$ (white). Because sRGB display channels are non-linear, each 8-bit channel is first linearized via inverse gamma expansion: $$c_{\text{linear}} = c / 12.92 \quad \text{if } c \le 0.03928, \quad \text{else } ((c + 0.055) / 1.055)^{2.4}$$ Relative luminance is then computed using the human spectral sensitivity coefficients: $$L = 0.2126 \times R{\text{linear}} + 0.7152 \times G{\text{linear}} + 0.0722 \times B_{\text{linear}}$$ The contrast ratio between two colors is: $$\text{Contrast Ratio} = \frac{L{\text{brighter}} + 0.05}{L{\text{darker}} + 0.05}$$ A minimum ratio of $4.5:1$ is required for normal text (WCAG Level AA), and $7.0:1$ for enhanced contrast (WCAG Level AAA).

# Q5: How does the browser Native EyeDropper API work, and what are its security constraints?

Answer: The W3C EyeDropper API (window.EyeDropper) provides a standardized browser interface allowing users to sample pixels from their screen. When triggered via user interaction (e.g., a button click), calling eyeDropper.open() suspends regular browser events, shifts the cursor to an interactive magnifying loupe, and yields screen coordinates directly from the operating system compositor.

To prevent malicious websites from silently surveilling user screens or sniffing desktop contents, the EyeDropper API enforces strict security constraints: it requires transient user activation (must be triggered by a genuine user click), can be aborted by the user via the Escape key, and returns pixel data only after the user explicitly clicks a target pixel.

# Q6: Why do some online color pickers produce slight rounding errors when converting between RGB and HSL?

Answer: Standard RGB uses discrete 8-bit integers ($0$ to $255$), representing exactly $256^3 = 16,777,216$ points. In contrast, HSL operates across continuous floating-point spaces ($H \in [0, 360)$, $S, L \in [0, 100]$). Converting an 8-bit RGB coordinate to HSL and rounding to integer degrees and percentages introduces quantization error.

When that rounded HSL is converted back to RGB, the inverse calculation may yield a channel value differing by $\pm 1$ or $\pm 2$ units (e.g., #6366F1 drifting to #6466F1). The ToolsAA engine prevents this drift by maintaining unrounded 64-bit double-precision floating-point representations in its internal state, applying rounding strictly at the presentation layer.

# Q7: What are the key improvements introduced in W3C CSS Color Module Level 4 and Level 5?

Answer: CSS Color Module Level 4 and Level 5 fundamentally modernize web color by moving beyond legacy 8-bit sRGB:

1. Modern Functional Syntax: Space-separated arguments and slash alpha delimiters (rgb(255 100 50 / 0.8), hsl(180deg 50% 60% / 0.5)).
2. Wide-Gamut Color Spaces: Native support for Display P3 (color(display-p3 1 0 0)), containing $50\%$ more chromatic volume than sRGB for modern OLED and Retina screens.
3. Perceptually Uniform Color Spaces: Support for CIE lab(), lch(), Oklab (oklab()), and Oklch (oklch()). In Oklch, uniform numerical adjustments produce uniform perceived changes in brightness and chroma, eliminating the unpredictable hue shifts common to HSL.
4. Color Mixing Function: The color-mix() functional notation allows programmatic interpolation between colors across designated color spaces directly in CSS.

# Q8: Why does ToolsAA execute color conversions 100% on the client side without server APIs?

Answer: ToolsAA is committed to a strict Privacy-First Architecture. Executing all color parsing, matrix mathematics, palette synthesis, and contrast calculations inside your browser's local JavaScript runtime guarantees:

• Absolute Privacy: Proprietary design tokens, unreleased branding palettes, and client mockups are never transmitted over the Internet or logged on remote servers.
• Zero Latency: Eliminating HTTP request-response round-trips ensures instant, 60fps UI responsiveness when scrubbing visual color sliders.
• Offline Resilience: The converter functions seamlessly in offline environments, intermittent network conditions, and secure air-gapped engineering environments.

# Technical Comparison Matrix: Color Models & Specifications

The following matrix compares the core characteristics, coordinate ranges, hardware domains, and native web platform support across major color spaces:

# Conclusion

Color computation forms the visual backbone of modern digital experiences. Bridging the gap between physical display hardware, biological human vision, and physical ink chemistry demands absolute mathematical precision. Whether decomposing hex strings into normalized floating-point coordinates, interpolating harmonic design tokens in HSL, calculating subtractive CMYK ink separations, or auditing WCAG relative luminance, selecting the appropriate color space and conversion algorithm is critical.

The ToolsAA Universal Color Code Converter unites technical rigor with privacy-first engineering. By performing 100% of parsing, colorimetric conversions, accessibility compliance checks, and palette synthesis directly within your local browser sandbox, ToolsAA delivers instant, reliable results while ensuring your proprietary design assets remain entirely private.