Branding
The library is neutral on purpose. Nothing in a component knows it belongs to Ivim — no green, no hex, no brand name lives in the catalog. Brand identity is loaded from the outside, through one seam, and every color you see is the far end of a short chain that starts there. That is what makes the system rebrandable: you swap the near end, and the whole surface follows without a single component being touched.
Neutral by default
Components are written against roles, not colors.
A component asks for the background that means "brand-solid" or the text that means "brand-primary" — never for #86af61. The brand literal is confined to a single ramp in @ivim/isomorphic/branding; everything downstream deals in semantic aliases. Because the vocabulary a component speaks is roles, the same Button, Badge, and focus ring render correctly under any brand that fills those roles.
One rule keeps this true
No component may reference a brand ramp entry or a raw hex. If a component needs brand color, it reads a semantic alias (bgBrandSolid, textBrandPrimary, borderBrand). The token audit exists to keep that rule honest.
The indirection
Brand ramp → semantic alias → component.
Three hops separate a brand color from the pixel it paints. Each hop adds a layer of "don't care": the alias doesn't care which ramp fed it, and the component doesn't care which alias resolved to which value. The swatches below are painted with the aliases themselves — recolor the ramp and this diagram recolors too.
1
Brand ramp
@ivim/isomorphic/branding
A raw palette entry — a literal hex like ivimGreen (#86af61). This is the ONLY place a brand color is written down.
2
Semantic alias
tokens.color.bg.brandSolid
The ramp value is assigned a role, not a name. The theme maps that role onto the flat bgBrandSolid / textBrandPrimary / borderBrand aliases every component reads.
3
Component
Button, Badge, focus ring…
Components consume the alias. They never import a hex and never mention "green" — so they cannot know, or care, which brand is loaded.
The chain in code
The hex appears exactly once. Everything after it is a role.
// libs/isomorphic/branding — the brand ramp (one place)
const colors = { ivimGreen: '#86af61', /* … */ };
// tokens.constant.ts — the ramp is bound to a semantic role
bg: { brandSolid: colors.ivimGreen }
// theme.ts — the role becomes a flat alias
bgBrandSolid: designTokens.color.bg.brandSolid
// any component — reads the alias, never the ramp
<Button variant="primary" /> // fills with bgBrandSolid
Rebranding is a ramp swap
Change the near end; the surface follows.
To rebrand, you replace the ramps in @ivim/isomorphic/branding — the brand hues, and the semantic bindings that decide which ramp value plays which role. That is the entire edit. Components stay byte-for-byte identical, because they were never told a color; they were told a role, and the role now resolves to a different value. A partner brand, a seasonal theme, or a whole second product can be dropped in without reopening a single component file. Light and dark are the same trick run twice: the dark theme is just a second set of role bindings over the same ramps.
Proof: the live token editor
You don't have to take the diagram on faith.
The /tokens editor is the claim made runnable. Edit bgBrandSolid, or any color in the ramp, and every surface in the app — this page included — repaints live, with no component rebuilt and no source changed. That is the rebrand happening in front of you, at the seam this page describes. If recoloring the system required editing a component, the editor could not work.
Open the token editor →
Recolor the brand ramp and watch the whole catalog follow — the rebrand, live.
The contract, in one line
Brand lives in one ramp; components speak only in roles; the editor proves the two are wired together. Neutral until told otherwise — and told in exactly one place.