The Three-Variable Theme: Deconstructing Linear's System

Alright, let's talk about themes. Specifically, let's talk about the soul-crushing agony of managing themes, especially dark mode. You painstakingly pick 30 shades of grey, hand-tune your accent colors, ship it, and then your designer points out that one disabled button on that obscure settings page looks like mud against its slightly-less-muddy background. Sound familiar?

We've all been there. Tweaking hex codes, juggling --color-grey-700 vs --color-grey-800, praying the contrast checker passes. Then you add a second dark theme, or maybe user-selectable themes, and the whole house of cards threatens to collapse under the weight of its own CSS variables. There has to be a better way.

The "Aha!" Moment - Linear's Approach

What if, instead of defining hundreds of colors, you could define the essence of your theme with just three variables? That's the core idea behind the system Linear recently showcased in their approach to theme generation.

Shortly after Linear announced their UI redesign and the concepts behind their new theme system, Andreas Eldh, one of the engineers involved, shared some fascinating background on how it came to be.

This isn't just your run-of-the-mill CSS-in-JS; it's a glimpse into a sophisticated, programmatic theme generation engine. Imagine you're tired of tweaking 50 shades of gray for dark mode, only to find your buttons have vanished because the contrast is shot. This approach offers a different path: define the essence of your theme, and let math handle the fiddly bits.

Note: The following code was de-obfuscated by Google Gemini from Linear's minified production code, with function and variable names reconstructed based on their purpose.

The Full Theme Generation Method

Breaking Down the Theme Generator Step by Step

Let's break down how this theme generation works:

1. The Inputs (themeConfig): The Magic Ingredients

The function takes a themeConfig object that serves as the "recipe card" for your theme:

• base: An array [L, C, H] representing the main background color in the LCH color space. LCH is crucial here – unlike HSL, changing Lightness (L) in LCH doesn't drastically alter the perceived hue, making it much better for generating related shades.
• accent: Another [L, C, H] array for the primary accent color.
• contrast: A number telling the engine how much visual separation you want between elements (higher number = generally more contrast).
• colorFormat: The desired output format (e.g., "RGB", "LCH", "Hex").
• baseTheme, elevation, _themeType, sidebarInput: These are used for generating variants of a theme (like elevated panels or sidebars) recursively.

2. Setting the Stage: Light vs. Dark & Edge Cases

First, it figures out if we're dealing with a light or dark theme based on the base color's Lightness value:

It also flags extreme cases (near-white or near-black with low color saturation) because these often need slightly different adjustment logic to look good.

For example, a very light theme with base color like #fcfcfc or a very dark theme with base color like #0a0a0c would be flagged for special handling.

3. The Secret Sauce: Contrast-Driven Adjustment Factors & Helpers

This is the core idea. Instead of magic numbers, the code calculates factors based on the input contrast and whether the theme is light or dark:

Notice these important aspects:

• Light/Dark Sign Flip: The isLight ? -1 : 1 pattern appears frequently. Dark themes usually need positive lightness adjustments to get lighter variations, while light themes need negative ones.
• Different Sensitivity: The factors divide the contrast input by different amounts (30, 70, 10), making some adjustments (like borders) less sensitive than others (like backgrounds).
• Helper Functions: The adjustColor* helpers take an LCH color and an object specifying how much to change L, C, or H (e.g., ' l: 2, c: -1 '), then apply the relevant contrast factor to those amounts before using a ColorUtils.adjust function.
• Smart Text Handling: The adjustTextColor is particularly clever: it first determines the ideal base text color (black/white) for the given background using ColorUtils.getTextColor, then applies contrast-driven adjustments.

4. Generating the Palette (generatedColorsLCH)

This is where the magic happens. The code uses the base/accent colors and the adjustment helpers to calculate dozens of specific colors needed for the UI:

For example, with a dark base of #121214 and an accent of #7c3aed , it might generate:

• bgBaseHover: #1c1c20 (slightly lighter)
• bgSub: #202024 (more elevated)
• bgBorder: #2c2c30 (visible but subtle)
• labelBase: #ebebeb (light text on dark)
• labelMuted: #a1a1aa (secondary text)
• controlPrimary: #7c3aed (accent color)
• controlPrimaryHover: #8b49fc (brighter accent)

5. Formatting and Final Assembly (finalThemeObject)

The final steps involve converting the LCH colors to CSS and assembling the complete theme:

The final theme object includes:

• Metadata: contrast level, color format, whether it's dark
• CSS Color Strings: all the semantic colors, formatted for CSS
• Shadow Definitions: pre-computed CSS shadow strings at different elevations
• Direct Style Values: other styling constants like padding
• Theme Variant Functions: methods to generate related themes

6. Recursive & Lazy Theme Variants

One of the most powerful aspects of this system is how it handles theme variants:

Functions like elevatedTheme(), subTheme(), sidebarTheme(), etc., are fascinating:

• Lazy Evaluation: They don't run immediately. They only calculate when called.
• Memoization: They check if they've already generated this variant (using the memoized variables).
• Recursion: If not previously generated, they call the main generateTheme() function again, but with modified inputs.
• Contextual Derivation: They modify the base color (e.g., using a lighter color for elevated panels) but maintain the relationship to the original theme.
• Linking: They set baseTheme: finalThemeObject to create a connection back to the parent theme.

This allows creating contextual variations (like a panel that's slightly lighter than the main background) that are still derived from the original base/accent/contrast inputs. The sidebarTheme() function shows even more sophistication, with logic to override specific control colors based on whether a custom sidebar input was given.

7. Memoization (Performance is Key!)

The final piece of the puzzle is performance optimization:

Since generating a theme involves many calculations, and theme variant functions might call each other recursively, calculating the same theme variant multiple times would be slow. The memoize() wrapper ensures that if generateTheme() is called again with the same inputs, the cached result is returned instantly.

Imagine defining your entire dark theme like this (conceptually):

• Base Color: A super dark, slightly cool grey #121214 (defined precisely using LCH).
• Accent Color: That vibrant Linear purple #7c3aed (again, LCH).
• Contrast Level: A number, say 33, dictating the overall visual separation.

From just these inputs, a magical function spits out everything: background shades, hover states, faint borders, solid borders, primary text, muted text, link colors, button backgrounds (normal, hover, selected), focus rings, even appropriately contrasted fixed palettes for things like tags (red, green, blue...).

Try It Yourself: Theme Generator

Want to see this in action? Use the controls below to set your base color, accent color, and contrast level, then watch how it generates an entire design system automatically.

Why This is Harder Than It Looks - Enter LCH and Contrast

"Okay," you say, "I'll just take my base color and make it 10% lighter for hover, 20% darker for a subdued background..." Stop right there. That's the path to Mudville.

Why? Because simple lightness adjustments in RGB or HSL often mess up the perceived hue and saturation. Making a vibrant blue "lighter" might make it look washed out or shift towards purple. This is where the LCH color space becomes our superhero. LCH stands for Lightness, Chroma (saturation), and Hue. Its magic power? Adjusting Lightness (L) preserves the perceived Chroma and Hue much better than HSL or RGB manipulations.

The second pillar is Contrast. The code doesn't just make things lighter or darker randomly; it calculates adjustment factors based on the target contrast. A higher contrast input means text colors will be pushed further away from background colors, hover states will be more distinct, etc. It's building accessibility and hierarchy right into the color generation.

How It Works (The Gist)

Think of the theme generator as a master chef. It takes the raw ingredients (base, accent, contrast) and applies a series of techniques:

1. Determine Theme Type: Is it a light or dark theme? Are we near black/white (these need special handling)?
2. Calculate Adjustments: Figure out how much to tweak colors based on the desired contrast.
3. Derive Colors:
   • Need a hover background? Adjust the base color's Lightness (and maybe Chroma) using the primary contrast factor.
   • Need muted text? Find the ideal text color first (black/white), then reduce its Lightness using the text contrast factor.
   • Need a border? Adjust the base color using the border contrast factor (which is less sensitive).
   • Need a primary button? Use the accent color. Need its hover state? Adjust the accent color slightly.
4. Semantic Naming: Store every derived color with a name describing its job: bgBase, bgBorderFaint, labelMuted. Forget names like grey-700-with-a-hint-of-blue.
5. Format & Package: Convert all those calculated LCH colors into usable CSS (like RGB strings) and bundle them up with metadata and shadow definitions.

Semantic Variables: The Unsung Hero

The generated theme object would then be used to populate CSS custom properties (variables) on your page:

Your components only use these semantic variables:

(Or, if using Tailwind, you configure it to map bg-control-primary to var(--color-control-primary)). Now, if you generate a completely different theme (say, high-contrast light mode) and update the CSS variables, the button Just Works™️, adapting its look perfectly without code changes.

Bonus Level: Contextual Variations

The system even handles generating theme variants. Need a panel that's slightly lighter than the main background?

The elevatedTheme() function calls the main generator again, but tells it to use a slightly lighter base color than the current theme and links back (baseTheme: currentTheme). This recursive generation allows for contextually appropriate, yet consistently derived, styles. Memoization ensures this doesn't kill performance.

The Payoff: Why Bother?

Is this complex? Absolutely. Is it overkill for your dog's photo blog? Probably. But for a complex application like Linear, the benefits are huge:

• Rock-Solid Consistency: Colors have mathematical relationships. No more guessing if grey-700 contrasts enough with grey-200.
• Rapid Iteration: Designers and developers can tweak the entire UI feel by playing with just 3 core inputs. Adding a new theme becomes trivial.
• Maintainability: Refactoring? Need to change all primary button hovers? Change the generation logic or the semantic variable, not 50 different components.
• Automatic Adaptation: Components inherently adapt to any theme thrown at them.

The Catch

This isn't magic. It requires:

• Serious Color Science Chops: Someone needs to understand LCH, contrast calculations, and how to derive pleasing palettes programmatically.
• Robust Tooling: You need those color utilities (or similar) functions to do the heavy lifting.
• Discipline: Your team needs to commit to using only the semantic variables in components.
• Upfront Investment: Building the generator is non-trivial.

Generating themes programmatically from minimal inputs, using LCH and contrast calculations, and applying them via semantic CSS variables is a powerful, sophisticated approach to UI theming. It trades upfront complexity for massive gains in consistency, speed, and maintainability down the line. It's taking the idea of a design system and pushing it further – defining not just components, but the rules that govern their appearance across any theme. It's painting your UI with math, and for complex applications, it might just be the future.