Theming and white label

How it works

Each customer brand is a brand pack: a token file that follows a closed schema and is processed at build time. A pack can change only the values it is allowed to (its colour ramps, its appearance choices and up to eight dark-mode exceptions); the names of the meaning and component tokens and the relations between them do not change. Each brand is built into separate, static CSS files for light and dark mode.

Product screens never load a theme at runtime. Brand and mode are chosen with the data-brand and data-theme attributes on the root element, and the values come from the built files.

Brands today

Brand	Purpose
neutral	Default pack: neutral primary actions, iris and peach accents
bigbang	Optional pack: a teal brand colour and primary actions in the brand colour (appearance.primary: brand)
fixture	Test brand: shows that components behave correctly when the brand changes

You can switch between the brands from the Appearance menu at the top right.

Appearance

The optional appearance field of a brand file makes two choices:

Field	Values	Effect
primary	neutral (default), brand	neutral makes primary actions near-black in light mode and near-white in dark mode; the brand colour stays in badges, accents and the brand tone. brand takes the primary action, the focus colour and links from the brand ramp.
radius	default, none, compact, soft, round	Changes the corner radius scale at once. default is the scale on a 10 px base; none squares the corners.

In the neutral appearance the link colour equals the text colour; the underline tells links apart.

Material

Glass is not part of a brand pack: the app turns it on with Provider material="glass", and every brand works with both materials. The glass tints, rim, edge and highlight are semantic tokens (color-material-glass-*) derived per mode, so a pack cannot change them. validateBrand checks glass text and icons for each pack over seven worst-case backdrops in both modes, so a brand whose ramps pass the gate also passes on glass. See Material.

Presets

applyPreset(file, { neutral, accent }) applies a ready-made neutral and accent ramp to a brand file. The neutral presets are zinc, stone, slate and gray, with their chroma pulled to the neutral cap. Each carries every step of the DS neutral ramp, including 75 (the light page) and 750 (the dark layer-2 and hover), in its own hue. The accent presets are blue, green, orange, rose, violet and teal. Every combination passes the contrast test. The theme generator offers the same presets and appearance choices.

Brand pack rules

Enforced today (pnpm --filter @bigbang/tokens run brand:validate, also run by every token build):

• The brand file follows a closed schema; an unknown key, ramp or step stops the build with its path.

• Every brand defines a brand and an accent ramp with 11 steps, 50 to 950. It may also replace the neutral ramp with all its steps, 0 to 1000 including 75 and 750 (chroma capped so neutrals never read as brand colour), the red, green, orange and blue status ramps and the violet, teal and pink category ramps, keeping their step names.

• appearance takes only the fields and values above.

• Ramp values are opaque #RRGGBB literals. A ramp that records its OKLCH seed must reproduce from it; every manual lightness move is listed under adjust.

• Dark-mode exceptions live under overrides.dark, point a semantic token at another ramp step, and are limited to eight.

• Contrast pairs run for every brand and mode with no rounding: text at least 4.5:1, borders and state indicators at least 3:1. A failing pair stops the build. A replaced violet, teal or pink ramp is also checked for its tag text on the page surface, where outline badges put it.

• Raw values and the ramps are not part of the built files; components only see meaning and component tokens.

• One signed output is produced per brand.

• Every asset in the pack (font, logo, image) carries an unlimited commercial licence and is recorded in the licence ledger.

Theme generator

The theme generator produces a candidate brand file from brand colours on this site, with the same validator the build runs. The file it produces goes through the normal brand pack process (schema, contrast test, signature); products still never load themes at runtime. Its Material switch previews the brand on solid or glass surfaces.