The Three-Variable Theme: Deconstructing Linear's System

Managing themes is painful. You hand-pick 30 shades of grey, tune your accent colors, ship it, and then discover that one disabled button on an obscure settings page looks like mud against its slightly-less-muddy background. Add dark mode and the whole house of cards threatens to collapse under the weight of its own CSS variables.

What if you could define the essence of your theme with just three variables and let math derive the rest? That's exactly what Linear does. Three inputs. 98 colors out.

The Origin Story

Shortly after Linear announced their UI redesign, Andreas Eldh, one of the engineers involved, shared how the system came to be.

Try It Yourself

Before we dig into how it works, play with it. Pick a base color, an accent, and a contrast level. Watch how the entire palette updates.

Why LCH Changes Everything

The instinct when building a theme is to take your base color and make it 10% lighter for hover, 20% darker for a subdued background. In RGB or HSL, that leads to muddy, hue-shifted results. Making a vibrant blue "lighter" in HSL can wash it out or shift it toward purple.

LCH (Lightness, Chroma, Hue) solves this. Its key property: adjusting Lightness preserves the perceived Chroma and Hue. A dark navy adjusted to be lighter stays navy, not lavender. This is what makes programmatic theme generation viable — you can derive dozens of shades from a single color and have them all feel cohesive.

Linear's entire theme system operates in LCH. Every color is defined as a three-element array [L, C, H], manipulated in LCH space, and only converted to RGB at the very end for CSS output.

The Three Inputs

Here's the entire definition of Linear's default dark theme:

From these three values, the generator produces 98 semantic colors, shadow definitions, and functions to create contextual theme variants like elevated panels and sidebars.

How the Engine Works

Step 1: Light or Dark?

The first thing the generator does is classify the theme. A base Lightness above 50 means light mode. It also flags extreme cases — near-white and near-black — that need special treatment.

This classification drives everything downstream. In light themes, "darker" means moving away from the base; in dark themes, "lighter" means moving away. The sign of every adjustment flips accordingly.

Step 2: Contrast-Driven Adjustment Factors

This is the heart of the system. Instead of hard-coded color values, the generator calculates adjustment factors based on the contrast input. Different parts of the UI get different sensitivity levels:

Each factor powers a helper function that takes any LCH color and an adjustment recipe like { l: 2, c: -0.5 } and applies it scaled by the relevant contrast factor. The same recipe produces visually different results depending on whether you're in a light theme at contrast 20 vs. a dark theme at contrast 50.

Step 3: Deriving 98 Colors

With the factors defined, the generator derives every color the UI needs. Each color is named for its purpose, not its shade:

With a dark base of #121214 and a purple accent of #7c3aed , this produces:

• bgBaseHover: #1c1c20 — slightly lighter for hover feedback
• bgSub: #202024 — elevated panels and secondary surfaces
• bgBorder: #2c2c30 — visible but subtle separation
• labelBase: #ebebeb — primary text
• labelMuted: #a1a1aa — secondary, less prominent text
• controlPrimary: #7c3aed — buttons and active controls

All 98 colors are stored with their semantic names, then converted from LCH to the target CSS format (RGB, hex, etc.) in a single pass at the end.

Semantic Variables in Practice

The generated colors populate CSS custom properties:

Components reference these by purpose, never by shade number:

Swap in a completely different theme — high-contrast light mode, a warm sepia theme, whatever — and every component adapts automatically. No code changes needed.

Contextual Variations

One of the most elegant parts of the system: each theme can generate variants of itself. Need a panel that sits visually "above" the background?

This is recursive — elevatedTheme() calls the same generator with a modified base color, producing a full set of 98 colors tuned to that new base. Linear uses this for <Elevated> wrappers, sidebar panels, menu overlays, selection backgrounds, and focus states. Each variant is lazy-evaluated and memoized, so the cost of having six variant functions is effectively zero until they're actually needed.

The Payoff

For a complex application like Linear, this system delivers real benefits:

• Mathematical consistency: Colors have guaranteed relationships. No more eyeballing whether grey-700 contrasts enough with grey-200.
• Rapid iteration: Tweaking three variables reshapes the entire UI. Adding a new theme is a one-liner, not a week-long design sprint.
• Built-in contrast scaling: The contrast parameter adjusts the entire system proportionally. A high-contrast accessibility mode isn't a separate set of hand-tuned colors — it's contrast: 55 instead of contrast: 33.
• Maintainability at scale: Need to change how primary button hovers work? Adjust the generation logic once, not 50 components.
• Automatic adaptation: Components use semantic variables. They don't know or care which specific colors they're rendering — they adapt to any theme automatically.

The Catch

This is a powerful system, but it's not magic, and it's not for everyone.

• Color science expertise: Someone needs to understand LCH, perceptual contrast, and how to derive pleasing palettes programmatically. The contrast factor formulas aren't intuitive — they're the product of extensive iteration.
• Upfront investment: Building and tuning the generator is non-trivial. Linear's version evolved over five years and multiple hack weeks.
• Team discipline: Everyone must commit to using semantic variables only. One developer reaching for color: #666 breaks the contract.
• Diminishing returns at small scale: If your app has one theme and fewer than 20 themed components, hand-picked colors are simpler and faster. The payoff kicks in when you need multiple themes, dark mode, high-contrast modes, or user-customizable themes.
• Not a replacement for design judgment: The generator gets you 90% of the way. Linear's team still tweaks the generation code itself — the math produces a baseline, not a final product.

Generating themes programmatically from minimal inputs, using LCH and contrast calculations, and applying them via semantic CSS variables is a genuinely powerful approach. It trades upfront complexity for consistency, speed, and maintainability at scale. For complex applications that need to support multiple themes, it might be the only sane path forward.