The Theme contract

startupbuilder.dev defines the Theme: "A Theme is the design tokens of a Brand, its color, type, spacing, radius, and motion, that every Component reads when it renders." mdxui adds five policies and compiles the tokens to CSS custom properties.

Three kinds of roleCopy Anchor Link

A role names a use, not a look: ink-lede is the color a lede is set in, whatever that color is. Every Section type reads roles and never a literal color, typeface or size.

From @mdxui/themes@7.0.0-alpha.0: 21 core roles, which every Theme sets, and 325 derived roles, each with a default.

paper, panel, ink, ink-soft, rule, rule-soft, accent, accent-ink, pass, fail, warn, plate, plate-ink, plate-rule, sans, mono, text, lh, shell-max, shell-inset, shell-d-section

Core rolesCopy Anchor Link

Each square is one role under one Theme, as resolveTokens returns it. Hover for the value; click to copy the custom property. Dark shows the palette a Theme emits, so the three light-only Themes keep their light values.

Derived rolesCopy Anchor Link

A Theme that sets only the core roles renders: every derived role falls back through var() to a core role. A richer Theme overrides the families its design needs. The bars count how many roles of each family a Theme sets itself.

@mdxui/themes exports lists every derived role with its default.

Invariant rolesCopy Anchor Link

An invariant role is declared once and never redefined for dark. compileTheme refuses a Theme that names one in dark. certificate keeps its plate and its scrim invariant, so a code window is the same dark plate in both schemes.

On a plateCopy Anchor Link

A plate section re-tokens its subtree: a Section type on a plate reads --ink and gets the plate's ink. PLATE_REMAP names each pair, so one Section type renders on paper and on a plate with no second set of styles.

The Theme objectCopy Anchor Link

interface Theme {
  name: string;
  light: Record<string, string>; // the full light palette, every core role included
  dark?: Record<string, string>; // only what changes for dark
  invariant?: Record<string, string>; // declared once, never redefined for dark
  dividers: DividerPolicy;
  markers: boolean;
  featured: 'rule' | 'plate';
  icons: 'inline' | 'image';
  scheme?: 'auto' | 'light';
}

CompilingCopy Anchor Link

compileTheme(theme) checks a Theme against the contract and returns its custom properties for :root. It refuses a Theme missing a core role and names every missing one. For a Theme that sets only paper:

theme "harbor" is missing core roles: panel, ink, ink-soft, rule, rule-soft, accent, accent-ink, pass, fail, warn, plate, plate-ink, plate-rule, sans, mono, text, lh, shell-max, shell-inset, shell-d-section

resolveTokens(theme) returns the light palette with every var() chain followed to its value, for wherever a role is needed as a literal. The playground runs both on every edit.

Prior definitionsCopy Anchor Link