Token architecture

Every project chooses an architecture when you create it: a self-contained standalone project, or a layered multi-level project that shares and consumes design-token modules. The choice is per project — different projects in the same organisation can use different architectures.

Standalone vs. multi-level#

Standalone is the simplest model and works on every plan. The project owns its full token stack — primitives, semantics, compositions, and components — with no links to other projects. If you maintain one design system for one product, this is all you need.

Multi-level splits a design system into reusable modules. A Foundation holds shared primitives, a Brand layers brand-specific values and themes, and a Product consumes those modules and adds its own product-level tokens. One foundation can power many brands; one brand can power many products. Multi-level is a Business plan feature.

Project types#

The New Project dialog offers four types. The three multi-level types require the Business plan; Standalone Product is available everywhere.

Foundation

A foundation is the base of a multi-level system — your raw palette, spacing scale, and radii, shared once and reused everywhere. Foundations hold primitives, the default semantic aliases every brand inherits (like text.primary), and shared composition bundles (like a default card surface or type scale). A foundation can own themes too, for the primitives that genuinely vary by mode — a surface ramp that flips in dark. They are consumed by brands and products, never the other way around.

Brand

A brand layers brand-specific decisions on top of a foundation — its own primitives, identity semantic aliases (like action.primary), and composition bundles (like a brand button recipe), which shadow the foundation's defaults by path — and owns its named themes (e.g. Light / Dark, or per-sub-brand variants). Products that consume a brand inherit its themes by default, and can pin which of them to take — see Themes & modes.

Product (consumes modules)

A consumer product links any number of foundations and brands — one shared foundation is the common case, but a product can layer several of each — and adds its own semantic, composition, and component tokens. Component tokens stay product-only: they bind the shared language to concrete product UI. This is where a shared design language becomes a shippable product theme.

How layering resolves#

When a product resolves its tokens, modules are composited in precedence order: foundation layers sit at the bottom, brand layers stack on top, and the product's own tokens win last. Within each group the order is yours — drag module references into precedence order in Project → Token modules. A product can therefore override any inherited value without editing the upstream module.

Pinned releases & updates#

A product consumes each module at a pinned release, not its live branch — so upstream edits never change your product until you choose to adopt them. A module with no published release cannot be linked at creation.

When a module publishes a newer release, the product shows an update available prompt. You review a diff (and any conflicts with your own overrides) and accept the update deliberately — it is never applied automatically. See Project → Token modules in the Studio.