Authoring

Theme Tokens

Define shared design tokens with @theme for colors, spacing, typography, radius, breakpoints, containers, shadows, and motion.

Theme tokens are the shared design values a Master CSS project reaches for every day: colors, spacing, typography, radius, shadows, motion, breakpoints, and container sizes.

Define tokens in the project CSS entry with @theme, then use short contextual classes in markup. Keep the page focused on values. Use Global Styles for reusable components and utilities, Conditional Queries for variants, and Variables and Modes for the underlying resolution model.

@import '@master/css';@theme {  --color-brand: #4f46e5;  --color-text-action: var(--color-brand);  --spacing-lg: 1.5rem;  --radius-lg: 1rem;  --breakpoint-md: 48rem;  --container-md: 28rem;}@theme light {  --color-surface-card: #ffffff;}@theme dark {  --color-surface-card: #111827;}

<section class="p:lg r:lg grid-cols:2@md bg:surface-card">  <button class="px:md py:xs r:md fg:white bg:brand">Save</button>  <a class="text:action" href="/settings">Settings</a></section>

Master CSS resolves theme tokens before generating class rules. The generated CSS still uses normal CSS custom properties unless you intentionally define inline tokens.

Project CSS entry

A project needs a CSS entry that marks the Master CSS graph. Put shared tokens in the stylesheet that imports @master/css, or in CSS already imported by that entry.

@import '@master/css';@theme {  --color-brand: #4f46e5;}

The important part is the graph, not a special file name. Theme tokens can live wherever the project CSS entry already reaches them.

Define tokens

Theme tokens are CSS custom property declarations inside @theme blocks. Write the full token name with the leading --. The prefix places the value in a namespace that Master CSS utilities already understand.

@theme {  --content-hash: " #";  --color-brand: #4f46e5;  --color-text-action: var(--color-brand);  --spacing-lg: 1.5rem;  --font-family-sans: Geist, ui-sans-serif, system-ui, sans-serif;  --radius-lg: 1rem;  --breakpoint-md: 48rem;  --container-md: 28rem;}@theme light {  --color-surface-card: #ffffff;  --shadow-card: 0 0 0 1px rgb(15 23 42 / .06), 0 16px 40px rgb(15 23 42 / .12);}@theme dark {  --color-surface-card: #111827;  --shadow-card: 0 0 0 1px rgb(255 255 255 / .06), 0 16px 40px rgb(0 0 0 / .36);}

Use token names that describe the shared decision, not the first component that needed the value. A brand color, lg spacing step, or card shadow can be reused. A token named after one button or one modal usually belongs closer to that component.

Use tokens

Utilities resolve token values from the namespace they use. The same short key can mean spacing in p:lg, radius in r:lg, a container width in max-w:md, or a breakpoint in @md.

<article class="p:lg r:lg font:sans bg:surface-card shadow:card">  <h2>Dashboard</h2>  <a class="text:blue" href="/settings">Settings</a></article>

For a deeper explanation of namespace resolution and contextual lookup, see Variables and Modes.

Alias and override tokens

Use native CSS var() when a token should reference another token. This keeps semantic roles tied to a smaller set of foundation values.

@theme {  --color-brand: #4f46e5;  --color-text-action: var(--color-brand);}

Define the same token key as a preset token when you want to override it. Later definitions in the project CSS graph win.

@theme {  --color-blue: #4589ff;  --spacing-lg: 1.625rem;}

Use overrides intentionally. If the whole product should use a different blue or lg, override the preset token. If only one product role changes, create a semantic token such as color-text-action or shadow-card.

Add mode-aware values

Use mode-specific @theme blocks when the same token should resolve differently in light, dark, or custom modes.

@theme light {  --color-surface-card: #ffffff;  --color-text-card: #111827;  --shadow-card: 0 0 0 1px rgb(15 23 42 / .06), 0 16px 40px rgb(15 23 42 / .12);}@theme dark {  --color-surface-card: #111827;  --color-text-card: #f9fafb;  --shadow-card: 0 0 0 1px rgb(255 255 255 / .06), 0 16px 40px rgb(0 0 0 / .36);}

<article class="bg:surface-card shadow:card text:card">...</article>

Keep the token name mode-neutral. Markup should say surface-card or text-card, not dark-card.

For mode-trigger, default-mode, manual switches, and local mode islands, see Variables and Modes.

Use inline and static tokens

Use @theme inline when a token is only a utility shorthand and should not emit a CSS custom property. Master CSS still matches the token, but generated utilities write the resolved value directly.

@theme inline {  --color-brand: #4f46e5;  --spacing-feature: 1.5rem;}

<article class="bg:brand p:feature">...</article>

.bg\:brand { background-color: #4f46e5; }.p\:feature { padding: 1.5rem; }

Inline tokens can reference other inline tokens. If an inline token references a regular theme token, Master CSS keeps the regular var(--*) reference and emits that regular token when needed. Inline tokens cannot be mode-specific; use normal @theme light and @theme dark blocks when a value must change by mode.

Use @theme static when a token or managed keyframes definition should be emitted as an initial CSS resource instead of waiting for a matching class.

@theme static {  --color-brand: #4f46e5;}

Define responsive tokens

Responsive thresholds are theme tokens too. Define breakpoint variables for viewport condition suffixes, and define container variables for container query thresholds and width caps.

@theme {  --breakpoint-sm: 40rem;  --breakpoint-md: 48rem;  --breakpoint-lg: 64rem;  --container-sm: 24rem;  --container-md: 28rem;  --container-lg: 32rem;}

<div class="grid-cols:1 gap:md grid-cols:2@md grid-cols:3@lg">  ...</div><aside class="container max-w:lg">  <article class="grid-cols:1 grid-cols:2@container(md)">    ...  </article></aside>

Keep breakpoint tokens broad and product-wide. Use container tokens when a reusable component should respond to the space it receives. See Breakpoints and Containers for the responsive scales.

Define motion tokens

Motion values can be tokens too. Put reusable animation recipes, durations, easing curves, and managed keyframes in @theme.

@theme {  --duration-enter: 180ms;  --easing-standard: cubic-bezier(.4, 0, .2, 1);  --animate-dialog-in: dialog-in var(--duration-enter) var(--easing-standard) both;  @keyframes dialog-in {    from { translate: 0 0.5rem; opacity: 0; }    to { translate: 0; opacity: 1; }  }}

<dialog class="animate:dialog-in"></dialog>

Keyframes are emitted outside cascade layers, while animation utilities still generate in the utilities layer. For motion naming and usage, see Motion and Animation.