Design system

A design system is its own metadata — a deployable skin of token values laid over the platform’s fixed token names, plus a small brand seam of assets (a mark and a wordmark). It is not bespoke CSS, and it is not part of any other package. A component does not carry its own appearance; it inherits the design system of the org it renders in, so the same component renders in each org’s identity with zero per-component change. This is the same posture the platform takes toward objects, fields, and layouts (see How the platform works): the thing that varies between two deployments is a piece of metadata, not a fork of the code that reads it.

The reframe worth stating first, because the previous platform generation got it backwards: the design system belongs to no surface it paints. It is not published by the shell, and it is not compiled into the engine. It is a standalone metadata generation the engine applies to every surface at once — the shell’s chrome, every routed page, and every component the interpreter renders. Rebranding an org is deploying a different design system. It never means reinstalling the shell and never means touching the engine.

Because appearance is metadata rather than code, three properties fall out that bespoke per-component styling can never offer. A component built by a customer years ago re-skins the instant the active design system changes, because it never captured a color in the first place — it captured a token name. A brand is applied by overriding a handful of tokens, not by editing components. And a design system is a portable file in an open, documented format, deployable and round-trippable through ordinary design tooling rather than a proprietary blob.

The token-indirection contract

The mechanism underneath all of this is one deliberate layer of indirection between a component and the value it paints. This contract is the heart of the page; everything else is consequence.

Token names are a fixed platform standard. The --caos-* custom-property vocabulary — --caos-color-surface, --caos-color-border, --caos-color-accent, --caos-space-4, --caos-font, --caos-radius, and the rest — is a closed, versioned set defined by the platform. Every component, whether platform-shipped or customer-built, binds to these names and never to a hard-coded value. A component says “paint my border with --caos-color-border”; it does not say “paint my border #E2E8E9”. The names are the one thing that does not vary between deployments.

A design system is a named set of values for those names (plus the mark and wordmark assets). The base generation supplies a complete set; a tenant’s brand is a thin override generation on top of it. The names are the stable contract; the values are the metadata that varies.

The engine applies the active design system once at the document root. When the interpreter renders an org, it resolves that org’s design system and sets the whole --caos-* set on the root element for the active theme and density (this is a fixed step in the boot order — the design system is applied before any surface below it paints). A theme change repaints the entire frame and every routed surface with no reload and no per-component work, because nothing downstream stored a value to go back and change.

Every shadow-DOM component inherits it. Base and custom components render inside their own shadow DOM for isolation (parent page CSS cannot leak in, a component’s styles cannot leak out). Inherited CSS custom properties are the one thing that deliberately pierces the shadow boundary: a component reads --caos-* from the inherited cascade even though it is sealed against everything else. That is what makes a single design system reach inside every encapsulated component at once.

The consequence is the whole point: switching the active design system re-skins everything simultaneously — including a component authored long before the new design system existed — because the binding is to names, and only the values behind the names changed. There is no migration, no re-deploy of the components, and no per-component override list to maintain.

Opting out is possible and is flagged as a defect. A custom component that hard-codes a color rather than reading a token opts that one thing out of theming: it will not re-skin, and it will clash on any org whose brand differs from the value that was frozen into it. This was the concrete anti-pattern the previous generation shipped — a screen that baked in its own colors, so that when the theme changed the screen did not, and it was invisibly wrong until the moment the token it should have read changed. The authoring model for building components correctly is covered in Pages and components; the authoring surface treats a hard-coded value as a smell — the color picker is token-first, offering the --caos-* palette by default and warning when a raw value is chosen that would be low-contrast against the active surface or would escape theming entirely. Binding to a value is always allowed and always the wrong default.

Delivery is not ownership

A package may bundle a design system — the standard platform packages ship with the base look so a freshly-installed org is coherent out of the box — but bundling is only delivery. Ownership is separate: a design system is independently deployable and overridable, exactly like any other metadata generation. You do not have to accept the design system a package happened to carry, and you never have to touch that package to change the look.

This is the practical payoff of the ownership flip:

• To rebrand, deploy a new design system. That single metadata generation overlays the base and repaints every surface. You do not reinstall the shell, you do not reinstall the setup app, and you do not redeploy a single component.
• The shell is unaffected by a rebrand, and a rebrand is unaffected by the shell. The shell reads brand tokens; it does not define them. Swapping the shell package changes the frame and leaves the design system in place; deploying a new design system changes the look and leaves the shell in place. The two axes are orthogonal because neither owns the other.
• The engine never enters into it. No look-related change is ever an engine change. The kernel distributes whatever token values the active design system carries; it holds no palette of its own past the one frozen exception below.

Which design system is active

An org can hold more than one design system at once: one a package delivered, a starter theme, and the org’s own branding. The org names the one that is active. The org root’s theme points at it, and the engine applies that design system.

• Provisioning points it at the starter theme.
• Setup’s Theme & Branding points it at the org’s own branding when it saves, and releases it on reset.
• A deploy points it anywhere by writing the org root.

A design system the org names cannot be deleted while it is named. When the org names nothing, or names a design system that is not installed, the engine takes the installed design system whose key sorts first, so every boot still resolves the same one. Installing another design system never changes the look of an org whose named design system is installed.

The kernel’s frozen default — two surfaces only

There is exactly one place the engine carries a designed look, and its scope is deliberately tiny. To paint the two surfaces that exist before any package is installed — the sign-in screen and the empty-workspace landing — the kernel bakes in a default design system: the platform’s own first-generation look, complete enough that a brand-new org is polished from its very first screen rather than blank-on-blank.

Two properties keep this consistent with the metadata-first rule:

• It is a fixed default, not a privileged one. Any installed design system — the base generation, the ACME stand-in, or a customer’s own — overrides the baked-in default on every surface past provisioning. The compiled-in default shows only on the two pre-install surfaces, and the moment a shell and apps install, deployed metadata takes over everywhere else.
• It is frozen against rebrands. If the platform’s own marketing look later changes, the baked-in default can stay exactly as it is — it is the engine’s provisioning-time signature, not a living brand. Decoupling the two means a rebrand never touches the kernel.

So the kernel’s design system and your design system are not the same object competing for the same surfaces. The kernel’s is a frozen floor for the pre-install moment; yours is deployed metadata that supersedes it the instant anything is installed. Nothing you deploy has to dislodge the baked-in default — it simply stops being reached.

The theme switch — a shell control over a design-system mechanism

The light/dark switch in the shell’s header is the cleanest illustration of the separation, and it is worth stating precisely: the shell provides the control; the design system provides the mechanism the control flips.

The theme switch is a control. When toggled, it flips a theme token that the active design system owns and distributes. The shell does not itself repaint anything — it holds no light and no dark palette. Every surface, the shell’s own chrome included, obtains its colors by reading the token, so flipping the token at the root causes every conforming surface to re-render in the new theme at once. A shell that stored its own light and dark colors instead of reading the token would be invisibly non-conforming: it would render correctly until the token it should have read changed, and then it would be wrong. The full contract for this seam is specified on the shell architecture page.

A canvas is the one surface this does not reach, and a component that paints onto one has to repaint itself. Everything drawn with a stylesheet re-skins when the token changes, because the browser re-resolves the value. A <canvas> does not: it keeps whatever pixels were last drawn on it, so a chart painted in the light palette stays light after the switch, and stays wrong until something redraws it. Nothing about that failure is visible to the component — it is not an error, it is old paint.

So a canvas-drawn component watches for the change and repaints. There are three signals and it needs all of them, because three independent things move the tokens it painted with:

• an explicit theme choice sets data-theme on the document element;
• the system default moves under prefers-color-scheme when the org never touched the switch;
• switching generation live stamps data-brand on the same root — see Switching a generation live.

The third is the one that gets missed, because it is not a theme change at all: light stays light, dark stays dark, and it is tempting to read “repaint on a theme change” as covering it. It does not. A generation swap moves the type scale and the neutral ramp, so a canvas that watched only the two theme signals keeps the previous generation’s typeface and label colour until something unrelated happens to redraw it — the same staleness, through a door the theme rule does not cover. A component that genuinely cannot watch the third signal must instead arrange to be fully re-rendered on a generation swap, and say so where it is written.

Every watcher is torn down when the element leaves the page — an observer on the document outlives the element that registered it, and a component that kept watching would repaint a canvas nobody is looking at, on every token change, for the life of the session. How it unsubscribes is the component’s own business; that it unsubscribes is not. caos-map’s <caos-map> is the worked example — it watches data-theme and data-brand with one observer on the root and prefers-color-scheme with a media query, and releases all three when it is removed — and today it is the only canvas on the platform; a chart is the obvious next one.

The brand seam works identically. The company-name slot and any brand-bearing region render from brand tokens — a mark and a wordmark supplied by the design system — never from a logo or product name baked into the shell package. That is what makes a white-labeled deployment a token swap rather than a shell rebuild.

The base design system

The base generation is the complete token set every deployment inherits when it does not white-label. It is the substrate a brand override lays over — and everything in it that a brand does not override is what keeps two differently-branded orgs recognizably the same platform.

Color. A single accent hue carries every accent, over a cool-graphite neutral ramp. Light surfaces run from a #F5F8F8 canvas up through white cards; dark surfaces run from a near-black canvas up through raised graphite panels. The accent is desaturated on purpose, and status color is treated as information rather than decoration — success, warning, danger, and info each carry a text color and a tinted background that read the same in both modes.

Typography is a three-family scale, self-hosted and CSP-safe (bundled woff2, never a CDN font URL):

Role	Family	Use
Display / headings	Space Grotesk	Page titles, section heads, metrics (tabular numerals)
Body	IBM Plex Sans	Prose, field values, dense table rows
Mono labels	IBM Plex Mono	Uppercase, letter-spaced field and tab labels

Space and form. A 4-point spacing base (--caos-space-1 = 4px through --caos-space-7 = 48px for section rhythm), a small radius scale, and flat elevation: structure comes from 1px borders, not shadow. Surfaces carry no shadow at all — a single float shadow is reserved for things that genuinely float (menus, popovers, modals, toasts). The focus ring is the accent, drawn as a 2px ring plus a 1px border shift on the focused control.

These invariants — the layout, the spacing, the type scale, the neutral ramp, the semantic status colors, and every component’s behavior — are not part of the brand seam. They are what makes a base-derived deployment recognizably the same platform regardless of whose logo is in the corner.

The v1 base look — art direction

The token contract above says how appearance is delivered; this says what the base generation actually looks like in v1, anchored to two canonical reference surfaces. The kernel’s two default screens — the sign-in and the empty-workspace landing — are rendered in this look and are kept as image references at assets/kernel-default-surfaces/login-mockup.png and empty-workspace-mockup.png. Where this prose and those images disagree, the images win — they are the v1 look of record.

• Accent. A single teal carries every accent: #2BB3B3 on dark, #178A8A on light (ramp #0D3B3B → #9FE4E4), desaturated on purpose.
• The signature ground. Hero, marketing, and the two pre-install surfaces sit on a diagonal gradient from near-black graphite to a teal-tinted edge — dark at the top-left, a brighter teal wash toward the bottom-right. Working data surfaces stay flat: white cards (light) or raised graphite panels (dark), never the gradient.
• The hero motif. The platform’s own illustration language is a thin teal line-art schematic — an isometric stack of metadata layers with radiating, labeled nodes (COMPONENTS · SHELL PACKAGE · APPLICATIONS · METADATA · EVENTS · APIS), dotted connectors, and small square node markers. It reads as “one intelligent core, many systems.”
• Iconography. Single-stroke line icons, teal or ink, each paired with an IBM Plex Mono uppercase micro-label.
• Composition. Brand lockup (mark + CAOS wordmark + CLOUD ATLANTIS OS) top-left; a white display headline (Space Grotesk) with a teal accent period; a floating white card for the data/form region; a mono status line at the foot (CAOS KERNEL ONLINE · VERSION 1.0.0 · WHITE-LABEL READY).
• Logo note. The triangle mark in the two reference images is an AI placeholder; the authentic mark is assets/kernel-default-surfaces/caos-logo*.png. Built surfaces and regenerated hero art use the real mark, never the placeholder.

The white-label brand seam

A deployment brands itself by overriding a small, fixed set of tokens and nothing else:

Token	Role
--brand-accent	The one accent hue that carries every accent across the UI.
--brand-accent-strong	The pressed / emphasis accent.
--brand-accent-soft	The tinted accent background — soft buttons, selected rows, accent-tinted pills.
--brand-mark	The deployment’s logo mark.
--brand-wordmark	The wordmark shown in the shell chrome.

The two brand assets — mark and wordmark — are the brand’s identity; the accent family is its color. Every accent in the --caos-* set derives from these: --caos-color-accent resolves to var(--brand-accent), and so on down. Brand-bearing text resolves the same way — the wordmark line and the assistant’s name read from brand tokens rather than string constants, so a rebrand changes labels, not only colors. Two design decisions keep the seam small:

• The on-dark accent is derived, not another token. On dark surfaces the accent is brightened with color-mix(in oklab, var(--brand-accent), white 14%), so any brand’s accent brightens correctly on dark without the deployment having to supply a second accent value. Correctness of the white-label across light and dark beats hard-coding a single theme’s on-dark hue.
• Everything else stays the base. The neutrals, the type scale, spacing, semantics, elevation, and all component behavior are outside the seam. A brand cannot restyle a button’s height, a table’s row rhythm, or the focus-ring treatment through this contract — only the accent family and the two brand assets. What is adjustable beyond the seam is only what the override model deliberately exposes; the invariant substrate is not themeable. Setup’s Theme & Branding exposes two such tokens: the body and heading typefaces, --caos-font and --caos-font-display.

Resolution at the root is a single overlay: base design system ⊕ tenant brand override → the published --caos-* variables.

Styling granularity

Global tokens re-skin uniformly: change --brand-accent and every accent in the org moves together. That covers the large majority of styling, but it is not the whole model. Some designs need to style a named part inside one component — a region that should look one way in one org and another way (or not at all) in the next, without touching any other component. “A design system is a token set, not a per-component override” stays true of the global re-skin; it is simply the broadest of four rungs, not the whole story.

A design system’s expressiveness is a four-rung ladder, from broadest to narrowest:

1. Global tokens — the --caos-* vocabulary plus the brand tokens. Org-wide values every component reads; the uniform re-skin described above. This is the floor, and it covers most styling.
2. Component variants — the closed set of per-component options a component declares and a design system is allowed to pick from: a button’s variant, a table’s density. The design system chooses among the options the component publishes; it cannot invent new ones.
3. Component styling seams — component-scoped tokens, CSS Shadow Parts, and named slots, described below. This is the rung that styles one named part of a single component per org, and it is native to the shadow-DOM substrate.
4. Per-instance authoring — a genuine one-off, such as rich-text formatting applied to a single instance. This is authoring, not theming, and is not a design-system concern.

Component styling seams

A worked example makes the rung concrete. Say a home greeting were to render “Good afternoon, Alex”, and one org wants the name after the comma accented while another wants it plain. Whether that part is accented would be an optional design characteristic the design system decides per org, not a value baked into the component. Three seams could express it, and a component author decides deliberately, at authoring time, which to expose — a region with no exposed seam cannot be styled from outside, and exposing one is a design-review decision rather than an accident.

• Component-scoped tokens — the component reads a named token for a sub-region and defaults it to inherit. A greeting could read a token named for its own subject span; a design system would set it to var(--brand-accent) to accent the name, or leave it unset for no accent. This is the preferred seam because it stays inside the token-name-stability contract: it is one more name the component binds to, and the design system still supplies only the value, so the whole re-skin story holds. <caos-overlay>’s --caos-overlay-width is the pattern shipped for real: a component-private custom property with a sensible inline fallback (var(--caos-overlay-width, 760px)), read only inside that one component. Concretely — the caution the next section exists to state — this only stays sound while the token stays private to the component that reads it, never entered into the platform’s shared --caos-* catalogue on the strength of a plan to use it. --caos-greeting-subject-color was authored into tokens.css for a greeting that was never built, and sat there with zero consumers until CAOS-586 deleted it; see Token governance below.
• CSS Shadow Parts (::part()) — the component marks a sub-region part="subject", and a design system targets caos-greeting::part(subject) { … } for richer per-part CSS than a single token value. ::part() is the W3C-standard, encapsulation-safe way to style shadow-DOM internals from outside — available precisely because components are custom elements with shadow DOM.
• Named slots — <slot name="…"> regions let a consumer project content or structure into named places inside the component.

One limit worth stating, because it is not obvious. A component that lifts a floating panel out to the top of the document — so that no surrounding box can clip it — puts that panel in a separate shadow tree. ::part() reaches into a component’s own shadow tree and no further, so the parts of a portaled panel are not addressable from outside, and the component can only expose seams on what stays behind. The four components that open a floating panel are all in this position: <caos-app-launcher>, <caos-nav-gadget>, <caos-object-caret> and <caos-overflow-menu> expose seams on their trigger and nothing on the panel. Component-scoped tokens are unaffected — custom properties inherit into the portaled tree — so a component whose panel needs to be styled per org must expose that as a token, not as a part.

How an author opens each of these seams is covered in Pages and components. Classifying a styling decision onto the ladder is the skill: a semantic pattern — greetings always accent the name — is rung 3, expressed once in the design system and applied everywhere the component appears. A one-off — redden the text after the comma in this heading only — is rung 4, authored on the instance and never a design-system concern.

The design system supplies values; the component author supplies the seams. Rung 1’s “a design system is a token set, not a per-component override” remains true of the global re-skin, but rungs 2 and 3 add controlled per-component and per-part expressiveness on top of it without breaking that story — they are all still named bindings the design system fills in, never bespoke CSS forked into a component.

Token governance: a component may not name a token after itself

A survey ahead of a larger component catalogue (CAOS-586) measured the platform’s own token discipline: 95 tokens serving 47 components, and exactly two of them — --caos-greeting-subject-color and --caos-heading-emphasis-color, both set to inherit in caos-ui/src/tokens.css — had zero consumers anywhere in the codebase. Neither was a rung-3 component-scoped token shipped alongside the component that reads it (the sound pattern --caos-overlay-width shows above); each was added to the platform’s shared catalogue in advance of a component that was never built, under a name that referred to that one component rather than a role every component could share. CAOS-586 deleted both.

The rule that fixes it, stated once so the count of violations never quietly climbs back up as the catalogue grows:

A component may not introduce a token — into the platform’s shared --caos-* catalogue — that names the component itself rather than a role or axis every component could read. If a piece needs something the system cannot express, that is a missing axis, and the axis is added once, for everyone, in tokens.css — never a one-off token added for that one piece.

Two clarifications keep this from contradicting the sanctioned patterns above:

• A component’s own private custom property is a different, allowed thing. --caos-overlay-width and --caos-overlay-scrim bear <caos-overlay>’s name too, but they are never entered into the shared catalogue (they do not appear in tokens.css, and are therefore not part of the declared vocabulary a theme can override — see the next section) — they are internal implementation detail with an inline fallback, exactly like a private instance field. The rule is about the shared, declared catalogue, not about every custom property a component happens to use internally.
• A genuine rung-3 component-scoped token stays sound only while it has a real consumer the moment it is added. --caos-greeting-subject-color failed on this, not merely on bearing a component’s name: it was authored ahead of any component reading it, which is indistinguishable in practice from a token nobody will ever read.

CAOS-586 also adopted three axes the same survey found missing outright — layering (a named z-index scale, replacing 13 raw literals with no coordination), size/density (one scale of five steps, xs to xl, used for exactly three things: the box an icon draws in, the diameter of an avatar, and the height of a control. The middle three are the steps <caos-button> had already invented informally through its size attribute, and <caos-icon> and <caos-avatar> read the scale rather than carrying sizes of their own), and interaction state (hover/disabled/selected) — and changed the design system’s tokens map from a free-form Record<string, string> to a declared, enumerable vocabulary: every valid --caos-*/--brand-* name lives in one exported list (DESIGN_SYSTEM_TOKEN_NAMES, kernel/src/meta/design-tokens.ts), and an org’s theme is validated against it — an unknown key is a rejection, not a silently-ignored typo. Full detail, the concrete token names for each axis, and the measured baseline are in docs/architecture/CAOS-586-design-token-axes.md.

Portable, open format

A design system is authored and exported in the W3C Design Tokens format — the open community-group standard for describing design tokens as data ($value / $type token nodes). It is compatible with the tooling built around that standard, including Style Dictionary and the common Figma token plugins, so a design system is a documented, portable file that round-trips through ordinary design tooling and deploys like any other metadata generation. It is not a proprietary export.

The distinction to hold onto is which layer is which standard:

• Token names are the platform standard. The --caos-* vocabulary is fixed and owned by the platform, so that a component built anywhere binds to the same names.
• The file format is an open standard. The design system file is W3C Design Tokens, so the values behind those names travel through the broader design-tooling ecosystem rather than living in a closed format.

The Branding editor

The screen where an org edits and switches its look — commonly surfaced as Setup → Branding — is itself a surface delivered by the platform-administration package over the design-system metadata, not a page compiled into the engine. theme is a type the kernel defines, so under the page-ownership rule the editor over it ships with the package that surfaces the kernel rather than with the one that masters the setup capability — Setup is where it is shown, not where it lives. That is the same discipline as everything else here: the editor is installed metadata that reads and writes design-system generations; the token mechanism it drives lives in the engine, and the enforcement underneath stays in the kernel. Remove that package and the tokens still resolve — you have simply removed the editing UI, not the design system.

It exposes two kinds of edit, and it draws a hard line between them:

• Brand tokens — the white-label seam above, plus whatever additional tokens the override model chooses to expose — edited as values, with a token-first color picker. The body and heading typefaces are a closed list, not typed names: the families the base self-hosts, plus the system sans-serif stack. The workspace loads fonts only from its own origin, so a family it does not host draws only on a machine that happens to have it installed, and falls back everywhere else. A typeface a deploy or a package’s theme set is shown as it is and kept when the org saves.
• Component variants — rung 2 of the styling-granularity ladder: the per-component options a design system is allowed to set, within the closed set each component declares.

Everything the editor does not expose is the invariant substrate — the layout system, spacing scale, type scale, neutral ramp, elevation model, and component behavior. An author can restyle the brand and the exposed variants, and cannot reach the invariants that keep every deployment coherent. The editor’s output is a design-system generation, and the org’s live look is always base design system ⊕ the org’s override, resolved at the root.

Switching a generation live

The Branding surface presents the available generations as cards — one per design system available to the org (for example, the teal base generation and a violet ACME generation) — each showing an accent swatch, a wordmark preview as it renders in the header, the name and a one-line description, and either an Apply button or a ✓ Current marker on the active generation.

Behavior	Detail
Live switch	Applying a generation stamps the active-brand marker on the root; the token rules repaint the whole frame — chrome, wordmark, accent, the assistant orb, and the assistant’s name — with no reload.
Persistence	The choice is saved and applied before first paint on the next load, so a reload comes up already branded with no flash of the default. (Saved per-browser today; setting it once for a whole org is a near-term step.)
Re-read on swap	Chrome web components (the wordmark, the assistant tab) re-resolve their token-driven labels via a brand-marker observer; the React surfaces (the orb, the assistant app) re-render through a shared brand store — so text labels, not just colors, update live.

The rule the editor enforces on authors is the same one the whole page enforces on components: define a new look as a token generation; never fork a component, and never hard-code a brand color, wordmark, or assistant name outside the seam.

Worked example — a small override re-skins everything

The reference white-label ships alongside the base: the same framework with the seam tokens overridden for ACME, a stand-in brand — a violet accent, the ACME wordmark and the ACME assistant name. The entire override is one small block published at the root, keyed to the active brand:

:root[data-brand="acme"] {
  --brand-accent:        #6B4FBB;   /* ACME violet */
  --brand-accent-strong: #543E96;
  --brand-accent-soft:   #ECE7F8;
  --brand-wordmark:      "ACME OS";
  --brand-ai-app-name:   "ACME AI";
}

Nothing else changes. Every button fill, selected row, active-tab underline, focus ring, and accent-tinted pill across every surface — including the accent’s brightened on-dark variant — repaints violet, because each of those reads --caos-color-accent, which derives from --brand-accent. The neutrals, type, spacing, semantics, and every component’s behavior stay the base. That is the whole contract: a deployment is one small override away from its own identity, and the components it inherited never had to know.

Rules

• A design system is its own metadata, not code and not part of any surface it paints. A component ships behavior, never a look.
• Components bind to token names (--caos-*), never to values. Hard-coding a value opts that one thing out of theming and is flagged.
• The engine applies the active design system once at the root; changing it re-skins every shadow-DOM component at once, including customer-authored ones. The shell’s theme switch is a control that flips a token the design system owns — the shell repaints nothing itself.
• Rebranding deploys a new design system. It never reinstalls the shell and never touches the engine. Delivery (a package may bundle a design system) is separate from ownership (a design system is independently deployable and overridable).
• The kernel’s baked-in default design system paints only the two pre-install surfaces (sign-in, empty-workspace) and is frozen against rebrands; every installed design system overrides it everywhere past provisioning.
• The white-label seam is the accent family plus two brand assets (mark, wordmark); the on-dark accent is derived, not another token. Everything outside the seam and the exposed override model is the invariant substrate.
• A component that paints onto a canvas repaints when the tokens move, and stops watching when it leaves the page. A canvas keeps the last pixels drawn on it, so it is the one thing a token flip does not re-skin. Three signals move them and it needs all three — data-theme on the document element, prefers-color-scheme, and data-brand for a live generation swap — and every one of them is released on removal.
• A design system is authored in the open W3C Design Tokens format — portable file, platform-standard names.
• The org’s live look is always the base design system overlaid with the org’s override, resolved at the root.

For where the design system sits among everything you author, see the developer surface; for how it travels between orgs as installed metadata, see packaging.