Building Scalable Multi-Brand Design Systems with Tailwind and React

Primitive tokens hold raw values — a palette expressed in OKLCH, a spacing scale, a type ramp. Semantic tokens express intent: surface, surface-raised, content-primary, border-subtle, action-primary. Component tokens, used sparingly, express local exceptions. Components consume only the semantic tier, which means a new brand is a new set of semantic assignments rather than a code change.

In Tailwind v4 this maps cleanly onto CSS custom properties declared in the theme layer. Brands become CSS scopes applied at the document root, and every utility resolves through the same variable names regardless of which brand is active.

Because tokens are CSS variables, brand and color-scheme switching requires no re-render and no JavaScript recalculation. The one hazard is the initial paint: a server-rendered page that resolves the brand on the client will flash. Resolve the brand server-side from the request host or route segment and emit the scoping class in the initial HTML.

Keep the variable contract stable. Renaming a semantic token is a breaking change for every brand simultaneously, so treat the semantic layer as a public API with deprecation windows.

Components should expose variant and size props, never color props. A `Button` that accepts `color="purple"` guarantees drift; a `Button` with `variant="primary"` guarantees consistency. Where a brand genuinely needs a different visual treatment, model it as a variant available to all brands and let token values differentiate it.

Governance is what keeps this durable: automated checks that reject raw hex values and hardcoded utility colors in application code, visual regression snapshots per brand, and a contribution path that routes new patterns through the system rather than around it. Documentation should show every component rendered in every brand, because the screenshot grid is where inconsistency becomes obvious.