Color science for LEDs

Designing colors for physical RGB LEDs is not the same as designing for screens. LEDs are point light sources viewed directly; the eye sees the raw emitted spectrum, not reflected light. Getting this wrong is the difference between effects that look stunning and effects that look like a washed-out mess.

This page is the practical guide. Everything here is distilled from LED color science research, analysis of 210 community HTML effects, and the Hypercolor engine’s rendering pipeline. It applies to every authoring path, whether you write a TypeScript canvas effect, a GLSL shader, or a native Rust renderer.

🔗LEDs are not screens

RGB LEDs create color through additive mixing: three discrete dies (red, green, blue) combine their light output. More channels active means brighter and less saturated. All three at full power produces white, not a richer color.

Key constraints unique to emissive light:

• You cannot make dark colors. There is no “brown” or “black” in emissive space. These require subtractive mixing or surrounding context.
• Each channel has wildly different perceived brightness. The human eye’s luminous efficiency peaks at ~555nm (green). Green appears roughly 6x brighter than blue at the same power level.

This asymmetry is the root cause of most LED color problems.

🔗The hue tier list

Not all hues are created equal on RGB LEDs. They fall into tiers based on how well the hardware can reproduce them.

The safe vivid range is 180-330° (cyan through magenta). This blue-anchored region produces deep, saturated colors reliably.

The danger zone is 30-90° (orange through yellow-green). Mixing red and green at similar intensities produces colors that read as washed-out, greenish, or disproportionately bright.

🔗Saturation: go hard or go home

Analysis of 210 community effects shows a binary saturation strategy:

• 58.5% of static HSL calls use S=100%
• 31.2% use S=0% (pure white or gray)
• Only 5.9% fall between 10-90%

That isn’t laziness. It’s practical wisdom. LEDs reward high saturation; at medium saturation, RGB LEDs without a dedicated white channel produce muddy, indistinct results. The community learned this empirically.

Default to HSV saturation 85-100% for vivid effects. Drop to 70-85% only when building multi-color palettes where colors need to coexist without competing.

🔗Brightness and the whiteness trap

The most common LED color mistake is pushing lightness too high and causing colors to blow out to white. High lightness in additive color means “add more of all channels,” which converges on white.

In HSL:

• L=50% is peak color vividness (the pure hue)
• L=60-70% starts washing out
• L=75%+ is pastel territory, mostly white with a hint of color
• L=90%+ is effectively white on LEDs

In HSV:

• V=100%, S=100% is peak vividness
• Reducing S while keeping V high adds white (washout)
• Reducing V while keeping S high makes colors darker and richer without washing out

🔗The whiteness ratio test

For any RGB color, compute min(R,G,B) / max(R,G,B). Keep this below 0.3 for vivid LED colors.

Never run all three channels above 200/255 simultaneously unless you want white. For any vivid color, at least one channel should be at or near 0.

🔗Gamma correction

LED hardware does not share the gamma curve of monitors. Most addressable LEDs have a roughly linear brightness response to PWM duty cycle, while human brightness perception is roughly logarithmic. Without gamma correction, the bottom 50% of brightness values appears nearly identical (dim) and the top 50% changes too rapidly.

The math:

corrected = 255 * (input / 255) ^ gamma

Gamma 2.2 is the standard starting point. Use 2.8 for high-brightness environments, 1.8 for dim rooms.

Key values at gamma 2.2:

Perceptual 50% brightness is PWM 55/255, not 128/255. This is why uncorrected fades look wrong.

TypeScript implementation:

function gammaCorrect(value: number, gamma = 2.2): number {
  return Math.pow(value / 255, gamma) * 255;
}

Or use OKLCH, which has perceptually uniform lightness built in. Changes in the L component produce visually proportional brightness changes on hardware.

🔗Color space hierarchy

Pick the right space for the job.

Never interpolate between distant colors in RGB. Red to blue in RGB passes through dim purple with a brightness dip at midpoint; yellow to blue passes through literal gray. Interpolate in Oklab for perceptually smooth transitions, or use HSV hue rotation for rainbow sweeps.

The built-in palette system uses Oklab interpolation automatically. See Palettes for the details.

🔗Patterns that work on LEDs

From 210 community effects, these survive the low-resolution sampling from canvas to LED grid:

These patterns fail because the detail lives below what LEDs can resolve:

• Bloom/glow post-processing (no sub-pixel blending between separated LEDs)
• Ray marching / complex 3D (detail below LED resolution is wasted)
• Film grain / single-pixel noise (invisible at LED density)
• Fine fractals (alias to mush)
• Thin lines / sharp geometry (below Nyquist, lines alias or vanish)
• Text rendering (illegible at keyboard-scale LED density)

🔗The Nyquist rule

The maximum detail that survives sampling to an LED grid is limited by 1 / (2 * LED_spacing). On a keyboard with ~18mm key pitch, the finest visible feature spans about two keys. Design with broad strokes, not fine detail.

🔗Animation timing

From stage lighting and community practice:

Always base animation on elapsed time (time in seconds), not frame count. The render loop retunes FPS adaptively; frame-counted animation speeds up and slows down unpredictably.

🔗The trail/fade technique

The single most common animation technique across community effects: overlay a semi-transparent dark rectangle each frame before drawing new elements.

ctx.fillStyle = "rgba(0, 0, 0, 0.15)";
ctx.fillRect(0, 0, ctx.canvas.width, ctx.canvas.height);
// then draw new foreground

The alpha value controls trail length:

Pair this with globalCompositeOperation = 'lighter' when drawing multiple overlapping lights for natural-looking additive glow.

🔗Composite modes

'lighter' is the most important for LED work: it simulates how light from multiple emissive sources actually combines.

🔗How the compositor blends your layers

Everything above governs color inside a single effect surface. When you stack effects in a Studio zone, a second blend happens above your code: the compositor combines each layer’s surface into one canonical canvas before the spatial sampler maps it to LEDs.

That blend is not a naive sRGB lerp. The compositor decodes each pixel from sRGB to linear light, blends in linear space, then re-encodes to sRGB. Linear-light blending is the physically correct model for combining emitted light, so overlapping layers brighten the way real light does rather than dipping through a muddy midpoint. The blend modes exposed to layers map onto the same math used by the per-frame canvas:

Native Rust effects receive color controls already converted to linear RGBA (0.0–1.0), not sRGB. The UI picker is sRGB and the daemon converts before delivery, so convert back to sRGB bytes only when you write the final canvas. See the native effect authoring path for the full color-type vocabulary and transfer functions.

🔗Practical tips

1. Test on hardware, not just the preview. The studio is a guide, not ground truth. What looks good in the browser may look different on your LEDs.
2. Use fewer colors at higher saturation rather than many colors at medium saturation. Three vivid colors beat seven muddy ones.
3. Keep brightness moderate for ambient effects. Full brightness is great for reactive accents but fatiguing for background lighting. V=60-80% is the sweet spot for ambient.
4. Embrace darkness. LEDs off is a valid and powerful design element. Negative space makes lit areas pop.
5. Avoid pure white backgrounds. White draws maximum power, produces maximum heat, and washes out any colored accents. Dark backgrounds with colored highlights always win.

🔗Color scheme hierarchy

The 80/20 rule: one color dominates, the other accents. The most admired setups use one or two coordinated colors.

🔗See also

• Palettes — the built-in palette registry and its Oklab interpolation.
• Audio API — drive color and brightness from spectrum data.
• GLSL shader effects — color math in WebGL2 fragment shaders (rendered via Servo, not wgpu).
• TypeScript canvas effects — the canvas() authoring surface these techniques target.

Building a compiled-in native renderer instead? The native Rust effect path lives in crates/hypercolor-core/src/effect/builtin/, registered through that module’s mod.rs. It ships the real color vocabulary (Rgba, RgbaF32, Oklab, Oklch) with working sRGB-to-linear transfer functions, so the linear-light rules on this page apply directly in code.