Color conversion, color spaces, and rounding

Representative automated fixture coverage

Hue Codex imports versioned JSON fixtures and tests the corresponding pure production functions directly. The groups below are the representative regression evidence most relevant to this methodology.

• Parsing fixtures: Accepted CSS color syntax, alpha behavior, clamping, invalid input, and out-of-gamut fallback cases. View the JSON fixtures.
• Conversion fixtures: sRGB, XYZ, Lab/LCH, OKLab/OKLCH conversion values, round trips, and precision boundaries. View the JSON fixtures.

What a pass means. A passing group confirms the named vectors and tested properties still match the documented implementation. It does not prove every possible input, final browser rendering, full accessibility conformance, profile-aware print output, or every downstream export consumer.

Hue Codex accepts concrete CSS color notation, including short, long, and alpha HEX; fixed CSS named colors; transparent; rgb()/rgba(); hsl()/hsla(); hwb(); lab(); lch(); oklab(); oklch(); and supported color() profiles where a tool exposes typed input. Unsupported, contextual, or incomplete input is rejected instead of guessed.

Alpha values remain part of the parsed color. Swatches, share state, and alpha-capable exports preserve them; contrast calculations composite translucent colors over an identified canvas before applying thresholds.

CSS Color 4 defines a larger <color> grammar than Hue Codex uses for typed conversion. Hue Codex follows the distinction between modern space-separated syntax and legacy comma syntax, then narrows the accepted set to concrete values that can resolve without cascade, custom-property, system-theme, or element context.

Modern syntax uses whitespace between color components and a slash before alpha, such as rgb(65 105 225 / 50%) or oklch(55.98% 0.188 266.4). Legacy comma syntax is accepted only for rgb(), rgba(), hsl(), and hsla(). Commas in hwb(), lab(), lch(), oklab(), or oklch() are rejected.

Hue values accept unitless degrees plus deg, grad, rad, and turn angle units. Hue values are converted to degrees before conversion. The none keyword is not accepted in typed conversion, even though CSS Color 4 defines it for missing components, because Hue Codex resolves every typed input to a concrete fallback color.

Fixed CSS named colors, transparent, and supported color() profiles are accepted. Context-dependent values such as currentcolor, system colors, var(), relative color syntax, color-mix(), light-dark(), and unsupported keywords are rejected because a standalone field cannot resolve their cascade or environment.

CSS Color 4 treats some hue components as powerless because the hue cannot affect the final color. In these achromatic cases the standard semantics treat hue as missing: HSL saturation at or below 0.001, HWB whiteness plus blackness at or above 99.999, LCH chroma at or below 0.0015, and OKLCH chroma at or below 0.000004.

Hue Codex typed conversion does not preserve CSS none or missing-hue markers in resolved fallback colors. When the resolved fallback is achromatic or below the polar chroma threshold, the methodology treats hue as neutral/powerless. Current derived fallback strings may serialize that neutral marker as 0, but that is not evidence that the authored neutral color had a meaningful red hue.

Palette, adjustment, and interpolation tools should therefore avoid inferring a source hue from grayscale or zero-chroma inputs. When a later workflow needs a hue, Hue Codex treats that as a product decision or seed fallback, not as standards-derived color information.

Canonical sRGB HEX means the resolved display fallback, not necessarily the full authored color. For sRGB-compatible input, the authored value and fallback describe the same color and only notation or rounding changes.

For Lab, LCH, OKLab, OKLCH, Display P3, or XYZ input outside sRGB, Hue Codex preserves the authored functional value for source reporting, capable-browser swatches, share state, gamut messaging, and alpha-capable exports. Tools whose math is defined only for sRGB use the separately labeled clipped fallback or a rendered composite rather than silently relabeling the authored coordinates.

That clipped fallback is a Hue Codex display/export decision: it produces a browser-safe value, but it is not a color-managed or perceptual gamut-mapping result.

Hue Codex is therefore not claiming that an out-of-gamut authored Lab or OKLCH value survives unchanged through every tool. The preserved authored value explains the source and the loss; the resolved fallback is what most downstream calculations operate on.

Hue Codex labels component scales explicitly because CSS authored syntax, internal conversion math, and display cards do not all use the same units. These ranges describe the scale used for conversion and display; out-of-gamut or theoretically unbounded components can still occur before sRGB fallback clamping.

• HEX is normalized to six uppercase sRGB digits for the canonical display color.
• sRGB channels are linearized before XYZ, Lab, OKLab, luminance, or contrast math.
• XYZ D65 is derived from linear sRGB with the exact linear sRGB-to-XYZ D65 matrix listed below.
• Lab and LCH are calculated from D50 XYZ after linear Bradford chromatic adaptation from D65; reverse conversion uses the D50-to-D65 Bradford matrix.
• OKLab and OKLCH are calculated from D65 XYZ with the listed XYZ-to-LMS and LMS-to-OKLab matrices, then converted between Cartesian and polar forms for chroma and hue.

Hue Codex rounds display strings according to the selected precision mode. The rule is a maximum decimal-place rule: trailing zeroes are not padded because the shared round() helper returns numeric values before string interpolation.

Rounding is applied at output boundaries. Tool checks such as contrast pass/fail use the raw values from the calculation path whenever the threshold matters.

The Color Converter and Color Picker expose Quick, CSS, Precise, and Token modes. The internal rounded mode is an alias of Quick, and the internal tokens mode is an alias of Token.

One export-specific exception: the converted-color CSS variable block writes the HSL custom property with two decimal places for hue, saturation, and lightness even when another precision mode is selected; the format cards, JSON, token JSON, SCSS module, documentation summary, and all-format summary use the selected mode.

When a perceptual or device-independent value converts back to sRGB for Hue Codex display cards, HEX/RGB copying, or fallback exports, output channels are clipped to the 0 to 255 display range. This makes a browser-safe fallback, but it can hide lost chroma or hue detail from the authored color.

This clamping is not a full perceptual gamut-mapping strategy. Hue Codex does not run a color appearance model, ICC profile transform, rendering intent, MINDE-style OKLCH search, or press-proof workflow on the Color Conversion page.

The gamut methodology page explains why this is different from profile-aware color management or print proofing.

Hue Codex normalizes to sRGB HEX first, then derives the requested color-space views. These equations list the transfer functions, matrices, adaptation steps, and polar conversions used for sRGB, XYZ, D50 Lab/LCH, and D65 OKLab/OKLCH.

# Inputs r8, g8, and b8 are encoded sRGB channels in [0, 255].
srgb_to_linear(c8):
  v = c8 / 255
  if v <= 0.04045: return v / 12.92
  return ((v + 0.055) / 1.055) ^ 2.4

linear_to_srgb_channel(c):
  if c <= 0.0031308:
    encoded = 12.92 * c
  else:
    encoded = 1.055 * (c ^ (1 / 2.4)) - 0.055
  return round(clamp(encoded, 0, 1) * 255)

M_srgb_to_xyz_d65 = [
  [506752/1228815, 87881/245763, 12673/70218],
  [87098/409605, 175762/245763, 12673/175545],
  [7918/409605, 87881/737289, 1001167/1053270],
]

M_xyz_d65_to_srgb_linear = [
  [12831/3959, -329/214, -1974/3959],
  [-851781/878810, 1648619/878810, 36519/878810],
  [705/12673, -2585/12673, 705/667],
]

rgb_to_xyz_d65(r8, g8, b8):
  rgb_linear = [srgb_to_linear(r8), srgb_to_linear(g8), srgb_to_linear(b8)]
  return M_srgb_to_xyz_d65 * rgb_linear

xyz_d65_to_rgb(X, Y, Z):
  rgb_linear = M_xyz_d65_to_srgb_linear * [X, Y, Z]
  return [
    linear_to_srgb_channel(rgb_linear[0]),
    linear_to_srgb_channel(rgb_linear[1]),
    linear_to_srgb_channel(rgb_linear[2]),
  ]

D50 = [0.3457/0.3585, 1, (1 - 0.3457 - 0.3585)/0.3585]
D65 = [0.3127/0.3290, 1, (1 - 0.3127 - 0.3290)/0.3290]

M_d65_to_d50 = [
  [1.0479297925449969, 0.022946870601609652, -0.05019226628920524],
  [0.02962780877005599, 0.9904344267538799, -0.017073799063418826],
  [-0.009243040646204504, 0.015055191490298152, 0.7518742814281371],
]

M_d50_to_d65 = [
  [0.955473421488075, -0.02309845494876471, 0.06325924320057072],
  [-0.0283697093338637, 1.0099953980813041, 0.021041441191917323],
  [0.012314014864481998, -0.020507649298898964, 1.330365926242124],
]

xyz_d65_to_d50(X, Y, Z):
  return M_d65_to_d50 * [X, Y, Z]

xyz_d50_to_d65(X, Y, Z):
  return M_d50_to_d65 * [X, Y, Z]

xyz_d50_to_lab(X, Y, Z):
  Xn, Yn, Zn = D50
  epsilon = 216/24389
  kappa = 24389/27
  f(t) = t > epsilon ? cbrt(t) : (kappa*t + 16)/116
  fx = f(X / Xn)
  fy = f(Y / Yn)
  fz = f(Z / Zn)
  L = 116*fy - 16
  a = 500*(fx - fy)
  b = 200*(fy - fz)
  return L, a, b

lab_to_xyz_d50(L, a, b):
  Xn, Yn, Zn = D50
  epsilon = 216/24389
  kappa = 24389/27
  fy = (L + 16)/116
  fx = a/500 + fy
  fz = fy - b/200
  finv(f) = (f^3 > epsilon) ? f^3 : (116*f - 16)/kappa
  return [Xn*finv(fx), Yn*finv(fy), Zn*finv(fz)]

lab_to_lch(L, a, b):
  C = sqrt(a*a + b*b)
  if C <= 0.0015:
    H_standard = missing
    H_display = 0
  else:
    H_standard = normalize_degrees(atan2(b, a) * 180 / pi)
    H_display = H_standard
  return L, C, H_display

lch_to_lab(L, C, H):
  if H is missing: return [L, 0, 0]
  return [L, C*cos(H*pi/180), C*sin(H*pi/180)]

M_xyz_d65_to_lms = [
  [0.8190224379967030, 0.3619062600528904, -0.1288737815209879],
  [0.0329836539323885, 0.9292868615863434, 0.0361446663506424],
  [0.0481771893596242, 0.2642395317527308, 0.6335478284694309],
]

M_lms_to_oklab = [
  [0.2104542683093140, 0.7936177747023054, -0.0040720430116193],
  [1.9779985324311684, -2.4285922420485799, 0.4505937096174110],
  [0.0259040424655478, 0.7827717124575296, -0.8086757549230774],
]

M_oklab_to_lms_prime = [
  [1.0000000000000000, 0.3963377773761749, 0.2158037573099136],
  [1.0000000000000000, -0.1055613458156586, -0.0638541728258133],
  [1.0000000000000000, -0.0894841775298119, -1.2914855480194092],
]

M_lms_to_xyz_d65 = [
  [1.2268798758459243, -0.5578149944602171, 0.2813910456659647],
  [-0.0405757452148008, 1.1122868032803170, -0.0717110580655164],
  [-0.0763729366746601, -0.4214933324022432, 1.5869240198367816],
]

xyz_d65_to_oklab(X, Y, Z):
  lms = M_xyz_d65_to_lms * [X, Y, Z]
  lms_prime = [cbrt(lms[0]), cbrt(lms[1]), cbrt(lms[2])]
  return M_lms_to_oklab * lms_prime

oklab_to_xyz_d65(L, a, b):
  lms_prime = M_oklab_to_lms_prime * [L, a, b]
  lms = [lms_prime[0]^3, lms_prime[1]^3, lms_prime[2]^3]
  return M_lms_to_xyz_d65 * lms

oklab_to_oklch(L, a, b):
  C = sqrt(a*a + b*b)
  if C <= 0.000004:
    H_standard = missing
    H_display = 0
  else:
    H_standard = normalize_degrees(atan2(b, a) * 180 / pi)
    H_display = H_standard
  return L, C, H_display

oklch_to_oklab(L, C, H):
  if H is missing: return [L, 0, 0]
  return [L, C*cos(H*pi/180), C*sin(H*pi/180)]

These vectors validate normalization, RGB-family conversion, Lab conversion, OKLab conversion, and a round trip back to the canonical sRGB HEX value.

CSS lab() lightness may be written as a number or percentage; Hue Codex serializes this page's vectors as lab(46.800061 17.782586 -66.657521).

Tools using this methodology

These Hue Codex tools link to this methodology because they depend on the formulas, assumptions, limits, or data policy described here.

Report a calculation issue

If a result does not match the documented formula or fixture, send the exact input, tool settings, displayed result, expected result, precision mode, and browser details. Please do not include private images, personal information, or secrets.