← Notebook

Deriving a tenant palette from one brand colour

Take a single colour per tenant and generate an accessible interaction palette nobody has to review.

Verified Oct 13, 2026 · culori 4.x

multi-tenancycolordesign tokensaccessibility

Before you begin

Outcome: You can accept one brand colour per tenant and generate every interaction state from it, with text contrast that holds without anyone reviewing each tenant by hand.

Prerequisites

  • A component layer that reads its colours from CSS custom properties rather than hard-coded hex values.
  • Somewhere to store one brand colour per tenant and emit it into the page.
  • No colour theory. The guide explains everything it uses.

You run one product for many organisations and each wants it to look like theirs. The usual answer is a stylesheet per tenant. It works for three and collapses at thirty, because every new component becomes thirty pieces of work and a broken tenant surfaces as a complaint rather than a failing test.

The alternative is to accept exactly one colour per tenant and compute everything else. The hard part is not the plumbing. It is making the computed colours legible for a brand colour nobody on your team ever looked at.

This guide assumes you know what multi-tenancy is and nothing at all about colour. Everything else it explains.

Why this is not a CSS problem#

The instinct is to write something like "hover is 20% darker than the button". In CSS that means operating on a hex code, and a hex code is three numbers: how much red, how much green, how much blue.

Those three numbers describe how to light up a screen. They do not describe how a colour looks to a person. Nothing in them means "how light is this" or "how intense is this", so you cannot adjust either one directly. When you darken #4a5f8f by 20% you are scaling three unrelated quantities and hoping the result reads as the same button in a pressed state.

For one hand-picked brand this is fine, because a designer looked at it. Across thirty unreviewed brands it is not, and the failure is specific: the same percentage change produces a different amount of visible change depending on the colour.

Take a navy and a yellow and lighten both by the same amount in RGB. The navy moves noticeably. The yellow barely shifts, because it was already near the top of what the screen can do in that direction. One tenant gets an obvious hover state; another gets one nobody can see. No amount of tuning the percentage fixes this, because the right percentage differs per hue.

Three numbers you can actually reason about#

OKLCH is a different way of writing the same colours. Instead of three channel amounts it gives you three properties, and each one means something you can describe in words:

  • L — lightness. How light the colour appears, from 0 (black) to 1 (white). This is the one you will use most.
  • C — chroma. How colourful it is, from 0 upward. Chroma 0 is grey. Higher is more vivid. A dusty sage has low chroma; a traffic-cone orange has high chroma.
  • H — hue. Which colour it is, as an angle from 0 to 360 degrees. Roughly: 30 is red, 150 is green, 260 is blue. Hue is the part you almost never change, because changing it means changing the tenant's brand.

The useful property is that L is close to perceptually uniform. Moving lightness from 0.50 to 0.58 looks like about the same size of change whether the hue is navy or yellow. That is the entire reason to use it: it makes "slightly lighter" mean one thing across every brand you will ever onboard.

In CSS you write it directly:

css
.button {
  /* lightness 0.52, chroma 0.09, hue 264 degrees */
  background: oklch(0.52 0.09 264);
}

So the plan is: read the tenant's one brand colour once (call it the seed, since everything else grows from it), pull out those three numbers, and build every state by changing L while leaving H alone.

Step 1: read the seed#

Use a conversion library rather than writing the maths. culori is small and does this well.

js
import { converter } from "culori";

const toOklch = converter("oklch");

export function readSeed(hex) {
  const { l, c, h } = toOklch(hex);
  // Pure greys have no meaningful hue, so culori returns undefined.
  return { l, c, h: h ?? 0 };
}

readSeed("#4a5f8f");  // { l: 0.49, c: 0.082, h: 265 }

Step 2: decide what text the colour needs#

A button is a colour with a label on it, and the label decides more than it seems. Before choosing how hover and active should look, work out whether this brand needs dark text or light text.

That is a question about contrast. Contrast ratio is a number between 1 and 21 describing how different two colours are in brightness. The Web Content Accessibility Guidelines (WCAG), the accessibility standard most regulations point to, ask for at least 4.5:1 for normal text. Below that, people with low vision cannot reliably read it. (WCAG allows 3:1 for large text, but this guide holds every pair to 4.5:1.)

This brightness is not the L from earlier. WCAG measures relative luminance, an older formula that counts green far more than red and red far more than blue. Two colours with the same L can have quite different contrast against black or white, so the question has to be answered by measuring contrast, not by reading lightness:

js
import { wcagContrast } from "culori";

// Which reads better on this colour: black text or white text?
export function wantsDarkText(colour) {
  const black = wcagContrast("#000000", colour);
  const white = wcagContrast("#ffffff", colour);
  return black >= white;
}

The obvious shortcut says "if the colour is lighter than 0.6, use dark text". It fails on mid-tones. A mid-grey like #808080 sits just under that line, gets white text, and white on mid-grey is 3.95:1 — below the threshold. Black on the same grey is 5.32:1. Asking which extreme reads better removes the guess.

There is always an answer. The contrast ratio between two colours is (lighter + 0.05) ÷ (darker + 0.05), where each is its relative luminance, from 0 for black to 1 for white. Against a colour of luminance Y, black scores (Y + 0.05) ÷ 0.05 and white scores 1.05 ÷ (Y + 0.05). Multiply the two and Y cancels out: the product is always exactly 21, so the better of the two can never fall below √21 ≈ 4.58. Colours of middling luminance sit right on that floor, a dusty teal like #4b7d87 among them, and even there one of the two clears 4.5:1.

Step 3: step away from the text#

Here is the mistake that breaks real deployments. You write "hover is slightly darker", ship it, and a tenant signs up with a near-black brand colour. Darker than near-black is black, and their hover state disappears. Flip it to "slightly lighter" and a pale mint tenant breaks the same way from the other end. Lightness stops at 0 and at 1. Any step that runs into either limit gets clamped, and two states that both clamp come out as the same colour.

So the direction has to be chosen per tenant, and the label from Step 2 says which way. Every step toward the text eats into the label's contrast; every step away from it adds to it. Dark text means step lighter, light text means step darker, so pressing a button only ever makes its label clearer.

That leaves the end of the scale. The largest step in the next section is 0.11, so if stepping away leaves less than 0.11 of room, step the other way:

js
// Step away from the text, so each state only gains contrast,
// unless that runs out of scale; then the other side has room.
function directionAwayFromText(seed, darkText) {
  const away = darkText ? 1 : -1;
  const room = away > 0 ? 1 - seed.l : seed.l;
  return room >= 0.11 ? away : -away;
}

This comes with a guarantee worth knowing. Either the away side has at least 0.11 of room, or it has less and the other side has more than 0.89. A step of at most 0.11 never runs out of scale, so nothing clamps and no two states can collapse into the same colour — for any brand colour a tenant can send you.

Step 4: derive the states#

Now each state is the seed with lightness moved by a fixed amount in that direction. Keep the hue. Keep the chroma too, except where the screen cannot show it, for a reason covered in the next section.

js
import { clampChroma, formatCss } from "culori";

export function buildPalette(seedHex) {
  const seed = readSeed(seedHex);
  const dir = directionAwayFromText(seed, wantsDarkText(seedHex));

  const step = (dl) =>
    formatCss(clampChroma({
      mode: "oklch",
      l: Math.min(1, Math.max(0, seed.l + dir * dl)),
      c: seed.c,
      h: seed.h
    }, "oklch"));

  return {
    base:   step(0),
    hover:  step(0.06),
    active: step(0.11)
  };
}

Math.min and Math.max never change a lightness here, because of the guarantee above; they only absorb rounding, since converting #ffffff gives a lightness a hair above 1.

The numbers are a starting point, not a law. What matters is that they are offsets in a perceptual space, so they behave the same for every tenant.

Why chroma sometimes has to give way#

A colour near white or near black physically cannot be very colourful. There is no such thing as a vivid near-white: as lightness approaches either end, the range of possible chroma collapses toward zero. How much chroma a screen can show also depends on the hue: at middling lightness a screen can make a far more intense blue than yellow, while near white the reverse is true.

So moving lightness while keeping chroma fixed can ask for a colour that does not exist. Left alone, the browser clips it to one that does, and because that clipping depends on hue, two tenants can get visibly different results from the same instruction. It is not a rare edge: for vivid brands, even the small hover and active steps can leave the screen's range.

clampChroma handles it. It takes any state the screen cannot show and lowers its chroma until it can, leaving lightness and hue exactly where they were. Only chroma ever gives way, so the guarantee from Step 3 still holds.

Step 5: give every surface its own text colour#

Step 2 chose dark or light text. Now pick the exact colour, in the brand's hue, and measure it against the surface it will actually sit on. Designers call a text colour its ink, and the code does too:

js
// Walk lightness away from the background until the text passes.
// Builds on clampChroma, formatCss and wantsDarkText from above.
export function readableInk(backgroundCss, hue, minimum = 4.5) {
  const goingDark = wantsDarkText(backgroundCss);
  let l = goingDark ? 0.25 : 0.95;
  const delta = goingDark ? -0.02 : 0.02;

  for (let i = 0; i < 40; i++) {
    const candidate = clampChroma(
      { mode: "oklch", l, c: 0.02, h: hue },
      "oklch"
    );
    if (wcagContrast(candidate, backgroundCss) >= minimum) {
      return formatCss(candidate);
    }
    l += delta;
    if (l < 0 || l > 1) break;
  }
  // No brand-hue ink passed. At 4.5:1, black or white always will.
  return goingDark ? "#000000" : "#ffffff";
}

Two details decide whether this works in practice.

The fallback is a proof, not a hope, up to a point. Because black or white always reaches √21 ≈ 4.58:1, returning one of them is safe at 4.5:1. The guarantee stops there: ask for WCAG's stricter 7:1 and some mid-tones have no passing text colour at all, so a stricter caller has to check what comes back.

Measure against the real surface. The label on a button sits on the base colour, then on hover, then on active, so measure it on each. For a brand that steps away from its text, the base's ink can only gain contrast as the button is pressed. A brand with too little room has to step toward its text instead, and there the label loses contrast with every step. In a sweep of 5,832 seed colours, 398 are like that, and the base's ink still passed on all three surfaces for every one of them. That is a measurement, not a guarantee, and measuring each surface costs three calls instead of one, so measure each.

Step 6: expose meaning, never the seed#

Components must never see the brand colour. They see what a state means:

css
:root {
  --action:            oklch(0.49 0.082 265);
  --action-hover:      oklch(0.43 0.082 265);
  --action-active:     oklch(0.38 0.082 265);
  --action-ink:        oklch(0.95 0.020 265);
  --action-hover-ink:  oklch(0.95 0.020 265);
  --action-active-ink: oklch(0.95 0.020 265);
}

.button {
  background: var(--action);
  color: var(--action-ink);
}
.button:hover {
  background: var(--action-hover);
  color: var(--action-hover-ink);
}
.button:active {
  background: var(--action-active);
  color: var(--action-active-ink);
}

This is what makes the system survive. A component written today works for a tenant onboarded next year, because it never knew that tenant's colour existed.

Generate the block on the server and inline it in the document head:

js
export function themeStyle(seedHex) {
  const p = buildPalette(seedHex);
  const { h } = readSeed(seedHex);
  return `:root{
    --action:${p.base};
    --action-hover:${p.hover};
    --action-active:${p.active};
    --action-ink:${readableInk(p.base, h)};
    --action-hover-ink:${readableInk(p.hover, h)};
    --action-active-ink:${readableInk(p.active, h)};
  }`;
}

Computing this in the browser after load costs a flash of the default palette on every page, which is the exact thing white-labelling exists to prevent.

This guide derives the colours a label sits on. Colours that sit on the page instead, such as an outline or a pale tinted panel, are a different problem, measured against the page rather than a label, and it is not solved here.

Verify with the seeds that break things#

Do not test with pleasant brand colours. Test with the ones designed to fail:

SeedWhat it catches
#ffffffA derivation that only lightens
#000000A derivation that only darkens
#c3ffc3A pale brand that is not pure white, where an "always lighter" rule clamps hover and active into one colour; a rule that only special-cases white would miss it
#ff0000A vivid brand whose nearby states fall outside what a screen can show
#808080Mid-tones, where choosing text by a lightness cut-off fails, and an undefined hue

For each one: every state visibly distinct and displayable, every ink at 4.5:1 or better against the surface it sits on, and no component stylesheet edited. If a per-tenant override is needed to pass, the derivation is not finished — you have just moved the per-tenant stylesheet somewhere less visible.

Five seeds catch the known failures, but they are not proof. Because the whole derivation is a pure function of one colour, you can afford the stronger check: step through the colour space and assert every property for every seed. A coarse grid of a few thousand colours runs in a couple of seconds. It is how this guide's own earlier mistakes were found: its first version passed every hand-picked seed it was tested with, and the sweep still found 87 pale colours where two states collapsed into one. A later sweep found that a single ink, measured on the base, failed on hover for a quarter of all seeds, which is what led to stepping away from the text.

What this costs#

Tenants get less control than they will ask for. Someone will want one button in one exact shade, and the answer has to be no. The moment a value is hand-picked it stops participating in the derivation, and it becomes the thing that breaks the next time the system changes.

That is the trade. You give up per-tenant art direction, and in exchange onboarding a tenant is one colour and no new work.

Verify the result

Set the seed to each of #ffffff, #000000, #c3ffc3, #ff0000 and #808080 in turn. Every interaction state must stay distinguishable and displayable, and the label must clear 4.5:1 on each surface it sits on (base, hover and active), without editing a single component stylesheet.

Troubleshooting

Hover states are obvious for one tenant and invisible for another.

You are mixing colours in RGB. The same percentage change produces a different amount of visible change depending on the hue. Convert to OKLCH and change the lightness number there instead.

A tenant picks a near-white brand colour and the interface loses all structure.

Your derivation steps in one fixed direction, so light brands run into the top of the scale and clamp. Choose the direction per tenant: step away from the label's text colour, and the other way only when that side has less room than your largest step.

Text passes contrast in the design file but fails in the running product.

You are measuring the wrong pair. If the surface behind the text is itself tinted per tenant, the check must use that tinted value, not white.

The button label passes on the base colour but fails on hover or active.

You measured the label once, against the base, and reused it. Measure the text against each surface it sits on and give base, hover and active their own ink.

Vivid tenants' hover states look different from the same instruction.

Some of those colours cannot be shown at that lightness, and the browser clips them differently per hue. Pass each state through clampChroma, which lowers chroma until the screen can show it and leaves lightness and hue alone.

A tenant asks for one specific button in one exact shade.

This is a product decision, not a technical one. Granting it means that button stops participating in the derivation, and it becomes the thing that breaks the next time the system changes.