Theme model

What it is

A theme is a template’s colour, type, and spacing system, declared once as a named set of tokens rather than scattered as literal values across a section’s markup. A section spends those tokens — bg-surface, text-ink — and never states a value directly. The tokens compile ahead of time to the stylesheet a published page loads; nothing about a theme is computed while a visitor is looking at the page.

Why it works this way

Two separate pressures shape this, and both are worth taking seriously on their own.

The first is that a template is not written once and rendered once. The same section renders inside every deliverable that composes it, and those deliverables belong to different properties and different agents, under different brands. A colour baked into a section’s markup is not a stylistic choice that happens to be wrong for one of those deliverables — it is a value the section commits to permanently, in code that is asked to vary by design. That is the same class of mistake as copying a fact into a slot instead of binding to it (see facts and provenance): both replace something that has to resolve per-case with something fixed at authoring time, when the author is in no position to know every case it will have to be right for. The fix is the same shape in both places, too — name the thing instead of stating it, and let something else resolve the name later, once, per deliverable or per template. A theme token is that name for colour, type, and spacing; no-hex is the rule that flags a literal in your editor, right where it appears.

The second pressure has nothing to do with any one section and everything to do with what a template does with several of them. A template composes sections that were authored independently — different files, often different points in time — onto one page. Nothing about that arrangement guarantees their stylesheets stay out of each other’s way; two sections could easily target the same element, or collide on specificity, if which one’s styles won were left for the sections themselves to work out. It isn’t left for them to work out. The platform fixes a single cascade order that every section’s CSS lands in, the same way, regardless of which section it is or where it happens to sit in the composition. A section’s author never has to know what else is on the page, or in what order, to know their own styles will hold — the order is fixed by the platform once, rather than negotiated between sections every time a template’s composition changes. See the CSS pipeline for what that order actually is.

How it works

A template’s design system lives in one declaration, written once: named colours, fonts, type sizes, radii, shadows, and layout values. A build step compiles that declaration into the stylesheet the page actually imports — see theme.ts for the token records and how a name becomes a utility. A section never writes a stylesheet that competes for the same ground; its own CSS is collected automatically and placed inside a layer the platform reserves for section styles, not one it chooses or negotiates itself — see the CSS pipeline for how a section’s CSS reaches the page and the full order the page loads in. Responsive behaviour follows the same logic as colour, and lands in the same place: the platform names no breakpoints, so a template declares the widths its own design swaps at — see breakpoints are yours.

What it is not

Not a global stylesheet you own. There is no shared file you edit to make a token of yours usable — declaring the token in your template’s own theme.ts is what makes it exist. The CSS a page actually loads is compiled from that declaration, and regenerated every time it changes; editing the generated output directly is undone the next time it compiles.

Not per-section theming. A section carries no theme of its own to configure. It spends whichever template’s tokens it is composed into, and looks right under any of them precisely because it never names a colour, font, or spacing value itself — only the token.

Not a per-slot content value. A theme token is authored once, by whoever designs the template, and never comes from a property’s facts — it dresses the page the same way for every deliverable that template renders. Content that varies per property is a slot’s job, sourced the way facts and provenance describes; a theme token is not a second, quieter route for that content to arrive by.

Not runtime style computation. A theme compiles once, ahead of time, from a fixed declaration — nothing about it is computed per visitor or per request. That is the same runtime story as everything else a template renders; see the pipeline for what does and doesn’t run per visitor, and server and client for why no CSS-in-JS runs at all.

Where next

• theme.ts — the token records, the document block, and how to declare a theme.
• The CSS pipeline — the two CSS entries, how a section’s CSS reaches the page, and the cascade order.
• no-hex — the rule that flags a literal colour in your editor.