Deriving a theme from your brand

Overview

The supported way to make opsinjs look like your product is to give it one colour. Not a palette, not a set of overrides. From that one colour the neutral system, the interactive system and the shape of the ramps are derived, and against it the two clinical axes are then checked for interference.

This page is about what happens at the boundary: which brand colours the engine takes cleanly, which ones it takes with a warning, and which ones it refuses. Being told no by a theme generator is a strange experience, so it is worth saying why it happens at all. A brand colour is a marketing decision. In a consumer health product it lands next to a number somebody may act on, and at that point it stops being only a marketing decision. The engine is where the two concerns are reconciled, and it reconciles them by treating the clinical axes as fixed and the brand as adjustable.

The thing this is most often confused with is restyling. Deriving a theme changes the palette. It does not change the density, the shape language or the type. Those are separate foundations, and Lyra and the docs chrome explains why this documentation site deliberately looks unlike the product it documents.

How it works

The workflow

What is derived, and what is not

The clinical axes are fixed because they are not decoration. A product whose "urgent" is purple because purple is on brand has repurposed a safety signal for identity, and the reader who has used any other health product in their life will read it wrong. The one supported change to the status axis is documented, reluctantly, on Status palettes.

Using it

The six brand colours that cause trouble

These are the recurring cases, in rough order of how often they come up. None of them is a bug; each is the engine surfacing a real conflict early.

1. A yellow, lime or chartreuse brand (roughly hue 75 to 130). Available chroma at those hues collapses at low lightness. The gamut boundary sits high and narrow, so the dark end of the ramp desaturates hard and your ink step will look grey rather than branded. There is no fix inside the engine, because lightening the ink to keep the chroma would break the contrast floor. The workable answer is to let the brand own --primary and the line role and let ink be neutral. Most brands in this family already do this in print without having noticed.

2. The brand sits in the status family (hues near 25, 55, 85 or 150). The engine will still derive a perfectly good theme, and the generator will still warn you, because the failure is semantic rather than numeric: a primary button in the same red as urgent teaches the reader that red means "press me" on one screen and "act now" on the next. If the brand cannot move, move the usage. Keep the brand out of any surface that reports a result, and rely on the fact that a status surface always carries a word and an icon.

3. A very low-chroma brand, such as greys, near-blacks and warm off-whites. Nothing breaks. The observation people make is that the status colours now dominate the screen. That is correct and it is the right outcome: in a health product the verdict should out-shout the identity. If it looks wrong, the problem is usually that too many things on the screen have a status at all.

4. Two brands, or a white-label product. Only one colour may own --primary. A second brand becomes a category-axis-style identity token, a logo, or nothing. Two primaries produce a screen where the reader cannot tell which coloured control is the action.

5. A brand supplied in Display-P3 or from a print reference. Accepted, and the sRGB fallback is chroma-clamped at constant lightness and hue, which means it desaturates rather than shifting. On an sRGB display the theme will therefore be duller than the swatch the designer approved on their studio monitor, and that is a real, visible difference you should surface to them before launch rather than after. See Gamut and Display-P3.

6. A brand that is nearly white or nearly black. These carry almost no hue information at all, so the derived ramps are effectively neutral and the theme comes out looking like the default. That is not a failure, but it usually means the colour handed over was a background rather than an accent. Ask for the action colour.

When you genuinely need to override one value

Do it in tokens/color.json and regenerate, never in the emitted CSS. The generated file carries a header saying so, pnpm check:generated fails the build when it has been edited by hand, and the reason for both is that an edited generated file is a lie that survives a code review. Adding your own tokens is the supported extension path.

Tokens

Accessibility impact

The derivation is the only place in the system where an accessibility property can be lost silently, because it is the only place a value is chosen by somebody outside this repository. Three guarantees hold across it:

• The floor is not negotiable by theme. Stage 7 adjusts or fails; it never emits a below-floor pair, and there is no configuration flag that relaxes it.
• Both themes are derived together. A brand colour that works in light and fails in dark fails the derivation, rather than producing a light theme now and a dark-mode bug report later.
• Adjustments are reported, not hidden. When stage 7 moves a foreground, the generator says which role it moved and by how much, so a designer can decide to change the brand input instead of accepting a colour they did not choose.

What the derivation cannot do for you: it does not know what you put the colour on. A brand-coloured button placed on a photograph is outside the model, and belongs to The contrast floor.

Related

• How the engine works has the eight stages, with the failure mode of each stated separately.
• Status palettes explains why the four clinical ramps are excluded from derivation, and what to do if your regulator disagrees.
• Category palettes is the supported way to add an identity colour for a measurement we did not anticipate.