Theming: the Brand area, design tokens, import and export

Every public page carries the site's theme as CSS custom properties on :root. Blocks, modules and custom markup read them, so a brand change reaches every page at once. The admin edits the theme in Brand (Sidebar → Structure → Brand): logos, colors, type, space, block styles and the brand voice, saved as a draft you can preview before you publish. This page covers the Brand area, the tokens and what the stylesheet makes of them, block styles, how to import a brand from design tokens, a website, a PDF guide or another Spillway site, how to export it as a brand kit, how sites on one instance share a brand, and how the header and footer menus fit in.

The Brand area

Brand is for managers and admins (site.settings) and has six tabs:

• Identity: four media pickers for the Logo (shown in the header in place of the site name, which becomes its alt text), the Logo mark (the square symbol, stored for later use), the Logo on dark (used in the header when dark mode is on and the visitor's device is dark) and the Favicon (<link rel="icon">). The social image stays under Site settings → SEO defaults.
• Color: every color token with a color picker and a text field (hex, rgb(), hsl() or a color name), the ten generated shades of primary, secondary, accent and neutral, Dark mode (on or off, plus the colors that replace the light ones), High contrast colors, and the contrast grid.
• Type: the heading and body font stacks, the base size and the scale ratio (1.125, 1.2, 1.25, 1.333 or 1.5), with a live sample of the six sizes the stylesheet writes.
• Space and shape: corner radius, space unit, content max width and shadow, a sample card, and the custom tokens (Add token, Remove).
• Styles: the named block styles of each styled block, each shown as the real block in that style: New style, Edit, Duplicate, Make default, Reset (a built-in style you changed) and Delete (a style you added).
• Voice: the brand profile every AI task reads (who we are, how we sound, words to use and avoid), per site and part of the draft like the rest: the AI tasks and the pre-publish banned-word check use it once you publish. See Site settings and AI in getting-started.

Drafts, preview and publishing

Every edit on Identity, Color, Type, Space and shape, Styles and Voice is saved to the site's brand draft a moment after you stop typing; the live theme and the published voice do not change. The header shows the state (Draft or Published, and when the draft was last saved) and the actions:

• Preview opens the home page in a new tab with ?__brand=draft, rendered with the draft. Any public page, search page or /_preview/... URL takes the same parameter. Only a signed-in user with site.settings sees the draft; everyone else gets the published brand. Preview responses carry Cache-Control: no-store and never enter the page cache.
• Publish copies the draft to the site's theme, identity, block styles and brand profile, records the version in History, deletes the draft and purges the cache (the brand-guide tag too when the voice changed): the theme tag always, site:<id> when the theme or the identity changed, and style:<block>:<key> for each block style whose look changed. The tags reach the CDN through the purge hook when one is connected (caching.md).
• Discard draft throws the draft away; the published brand stays.
• History lists the last 20 published versions with who published them; Restore as draft makes one the draft, ready to preview and publish.
• Import brand reads a brand you already have (design tokens, a website, a PDF brand guide or a brand kit) into rows you review and apply to the draft (below).
• Export downloads the published brand as a brand kit for another Spillway site (Export the brand as a kit).

A value the server would refuse (a color that is not a CSS color, a base size outside 10 to 32 px, a ratio outside 1 to 2) is marked on its field and the draft is not saved until it is fixed. Existing sites need no migration for the theme: their seven tokens already are the published brand. The brand profile was one per instance before; migration 0041 copied it to every existing site, so no site's voice changed. A site created later starts with an empty profile (or its parent's, when it inherits a brand).

The contrast grid

The Color tab checks the pairs that matter for reading against WCAG 2.2: text on background, primary on background (links), and white and text on primary, secondary and accent (the last two when set), then the same pairs with the dark mode colors when dark mode is on. Each row shows a sample, the contrast ratio and a pass or fail badge for AA (4.5:1, body text), AA large (3:1, large text and controls) and AAA (7:1). The admin and the server share one implementation (contrastRatio and contrastGrid in @spillway-cms/shared), so #000 on #fff is 21:1 and #777 on #fff is 4.48:1, which fails AA. A pair with a color the checker cannot read (oklch(), var()) shows n/a.

The tokens

The seven core tokens are always written, with these defaults:

The extended tokens are optional. An unset color or shadow writes nothing, so blocks fall back as before; the type scale and the space unit always have a value:

The block stylesheet derives --sw-color-muted, --sw-color-border and --sw-color-surface from the core colors with color-mix, so the whole palette follows them. See blocks.md for the derived tokens.

Generated tokens

The server also writes, from the values above:

• Shades of primary, secondary, accent and neutral: --sw-color-primary-50, -100, -200 and so on to -900. Step 500 is the color itself; lower steps mix it toward white (50 is 90% white), higher steps toward black (900 is 60% black). Shades are computed from hex, rgb(), hsl() and named colors; a value in another notation gets no shades.
• The type scale: --sw-text-sm, --sw-text-base, --sw-text-lg, --sw-text-xl, --sw-text-2xl and --sw-text-3xl, the base size times the ratio to the power -1, 0, 1, 2, 3 and 4, in the base size's unit (16px at 1.25 gives 12.8px, 16px, 20px, 25px, 31.25px and 39.06px).

Dark mode and high contrast

modes.dark holds enabled (off or auto) and the colors that replace the light ones; with auto the stylesheet adds @media (prefers-color-scheme: dark){:root{...}} with those colors (and the shades of the shaded ones). modes.highContrast.colors becomes @media (prefers-contrast: more){:root{...}}. A color a mode leaves out keeps its light value.

Custom tokens

Custom tokens are extra name/value pairs saved with the theme (theme.custom). Each becomes --sw-<name> on :root: a token named brand-gradient is var(--sw-brand-gradient) in block CSS, in a module's stylesheet or in custom head markup. Names are kebab-case (^[a-z][a-z0-9-]{0,62}$), values are any CSS value; up to 200 per site. A named token wins over a custom token of the same variable, and a custom token wins over a generated shade, so an imported primary-500 palette is kept as it is.

Every value is sanitized before it reaches the page (<, >, {, } and ; are stripped), so a token can never close the style block; the brand draft also refuses such values outright.

Block styles

The component library is the block library plus named styles. Each styled block declares what can vary (its style slots: a Hero's background, text and layout, a card's border, fill and image position, a button's emphasis), and each slot offers a short list of values that map to tokens, never a raw color. The brand defines a few named styles per block from those values. An editor picks a style by name in the page builder's Style field and never sees a color field, so every page stays on brand without review.

Every site starts with the built-in styles below. They are built only from tokens, so the starter themes share one set that each theme's colors recolor:

The values of each slot are listed in blocks.md. A built-in style can be edited and reset, never deleted; a style you add can be edited, duplicated and deleted.

• Stored as a name. A block keeps style: "dark-band" in its props. Changing a style's definition restyles every page that uses it once the brand is published, and those pages are purged by their style:<block>:<key> tag.
• Defaults per block. Each block has one default style (Make default moves it). A block with no style, or with a style the site no longer has, renders the default, so a dropped block already looks finished. The built-in defaults reproduce the blocks' look from before styles, so existing pages are unchanged; a Button saved with the old variant: "secondary" keeps the Secondary style, and a Call to action keeps the band or card it stored.
• Per role. Who may pick it limits a style to roles (Authors, Editors, Managers, Admins); with none checked, everyone may use it. People who can edit the brand (site.settings) may use every style. The page builder offers a person only the styles their role allows; a block that already carries another style shows it read only with a note, and the server refuses a save that gives a block a style the person may not use (403).
• Modules too. A module block reuses a core block's styles ("styles": "Cards") or declares its own slots (styleSlots) in its manifest, and gets the same Style field. See modules.md.
• AI uses them. Page from brief lists, per block, the styles the person may use, and drops any other style the model returns.

Shared blocks stay what they are: reusable content, rendered in whatever style they were given.

How a style reaches the page

Before rendering, the server resolves every styled block's style (the stored key when the site has it, else the default), adds the class sw-style-<block>-<key> (sw-style-hero-dark-band) and inlines the rules of the styles the page uses after the block stylesheet. Each rule set is generated from the style's slot values and reads only tokens, with fallbacks for tokens a site never set (the accent falls back to the primary color, the neutral shades to grays), so nothing a site types reaches the CSS except a kebab-case key. GET /api/theme/tokens.css carries the rules of every published style for front ends that render the public JSON themselves. Preview shows the draft's styles too.

Style guide

Brand → Style guide renders the brand as a page: each logo on a light and on a dark background (with the favicon), every color with its CSS variable, value and ten shades, the contrast grid with each pair's ratio and its AA, AA large and AAA result, the type scale with sample text in the heading and the body font, the spacing scale, the corner radius and the shadow, the voice rules from Voice (voice, tone, audience, terminology, the words you do not use, the boilerplate and the examples), and every block that has styles, drawn in each of its styles with sample content.

The server builds it from the tokens on every request, so it is never out of date, and it draws each block through the same path as a page: the real markup, the block stylesheet and the rules of each style. The block samples are illustrations: they cannot be clicked or focused and screen readers skip them in favor of each style's name and description.

• Published and draft side by side. The tab shows the published brand. When a draft exists, Side by side puts the draft's guide next to it and Draft only shows the draft alone, so you can check a change before you publish it.
• Duplicate style. Every style in the guide has Duplicate style. It opens the style dialog with a copy (<key>-copy, "<name> copy"); adjust its slots, then Add style saves it to the brand draft. Nothing is added if you cancel.
• Print or save as PDF. Opens the guide on its own, without the admin around it, and opens the browser's print dialog: choose Save as PDF for the brand book. Each section starts a new page and colors print as they are (print-color-adjust: exact). The tab prints the published guide, or the draft's in Draft only.
• The public page at /brand. Publish the style guide at /brand (off by default) is part of the brand draft: once the brand is published, /brand shows the published guide on the public site in the site's header and footer, with a download link to the original file of each logo, for agencies, vendors and departments. It never shows the draft, not even with ?__brand=draft. It carries noindex (a meta tag and X-Robots-Tag): it is a reference for people who work with the brand, its sample content would read as thin pages to a search engine, and it is not in the sitemap. The page is cached like any other and tagged theme, brand-guide, site:<id>, style:<block>:<key> for every style it shows and media:<id> for every logo, so publishing the brand and saving the voice refresh it. While the setting is off, /brand is an ordinary path: a page at /brand if there is one, otherwise 404.

GET /api/brand/guide answers the guide as a standalone HTML document for any signed-in user (?draft=1 for the draft, with site.settings); see api.md, Style guide.

Import brand

Most organizations already have a brand somewhere: a design system, a website, a PDF guide. Import brand in the Brand header reads it so nobody retypes it. Every import ends on the same review screen, and nothing changes until you apply it; even then only the brand draft changes, and visitors see it when you Publish.

1. Pick a Source: Design tokens, Website, PDF brand guide or Brand kit, fill in the file or the address, and choose Read the source.
2. Review the import lists every value found, grouped as in the Brand area (Color, Type, Space and shape, Dark mode, High contrast, Custom tokens, Identity, Block styles, Voice, Style guide; the last three groups and high contrast come from brand kits). Each row shows the brand setting, the Imported value, the Current value of the draft (or of the published brand when there is no draft) and where the value came From, with a checkbox. Every row starts checked; Select all and Select none help. Notes lists warnings (what needs AI, fonts the source loads from elsewhere, logo rules); Left out lists what the source carried that maps to nothing, with the reason.
3. Apply to draft writes only the checked rows into the brand draft. Logos are added to the media library at this point and set on the draft's identity; voice rows go to the draft's Voice. On a site that inherits a brand, the rows of a part its parent locks are shown unchecked and cannot be applied (the server refuses them with 403 brand_locked).

An import waits for review for 24 hours, then it is deleted. Applying deletes it too. Every import is audited (brand.import_read when read, brand.import when applied), and an AI call is metered like any other (task import, within the monthly cap).

What each source maps

The Website source fetches the page the way the importer does: through the SSRF guard (public addresses only, every redirect checked again), with the importer's user agent and size limits, and with the same theme extractor. It reads one page, not the whole site. The logo and favicon are fetched again, through the same guard, only when their rows are applied. Without AI (off, not configured, or a user without ai.use) the voice is skipped and a note says so; colors, fonts and the logo never need AI. The theme sets font stacks only: when the site loads its fonts from Google Fonts or its own files, a note names them so you can make sure visitors get the font files too.

The PDF brand guide source reads the text inside the PDF without sending the file anywhere. A guide that is only scanned pictures has no text to read, and an encrypted PDF cannot be read: export it again without a password. With AI on, one call reads the text as a first pass and answers in a fixed shape that is checked field by field (a value that does not fit, such as a color that is not hex, is dropped with a note). The PDF's text goes to the model as data between markers, and the model is told never to follow instructions inside it. Logo rules (clear space, minimum size, do and don't) have no place in the brand, so they are listed in Notes for you to keep with the guide. The names of the fonts the PDF itself is set in are listed under Left out: they are often the brand's typefaces. Logo files go to identity slots by name: a name with white, dark, reverse or knockout fills Logo on dark, mark, icon or symbol the Logo mark, favicon the Favicon, anything else the Logo.

A design system made in Claude or Figma

A design system exported as W3C design tokens (DTCG JSON) or as CSS custom properties imports through the Design tokens source, whatever tool made it: its colors, fonts, sizes, spacing, shadow and dark mode map like any token file. A Figma file imports through its variables (the Design tokens source with the Figma format), modes included. Component styles in such an export are not read; build them as block styles. A dedicated format for design systems made in Claude is an open question.

Design token formats

• W3C design tokens (DTCG JSON): nested groups, $type inherited from the group, {group.token} aliases, fontFamily arrays, dimension objects ({ "value": 6, "unit": "px" }), color objects with hex or sRGB components, and shadow composites (one or several layers), which become a CSS box-shadow. Tokens Studio files (value/type without the $) are read the same way. Dark mode: a top-level dark group (or modes.dark, themes.dark) holds the dark values under the same paths, and a token's $extensions.mode.dark holds its own dark value; aliases inside the dark group resolve to the dark value of their target when there is one. Other composites are skipped with a warning.
• Figma variables: the REST API response of GET /v1/files/:key/variables/local (meta.variableCollections and variables with valuesByMode) and the common plugin exports (collections → modes → variables, or an array of collections). The default mode of each collection (or the one named Light, or the first) gives the values; a mode named Dark gives the dark mode colors; other modes are left out with a warning. VARIABLE_ALIAS references are followed in the same mode, colors are converted from { r, g, b, a }, and floats become px.
• CSS custom properties: the --name: value declarations of every :root block (or of the whole text when there is none). var(--x) references are resolved against the pasted file, var(--x, fallback) falls back, !important is dropped.
• Tailwind theme JSON: { "theme": { ... } } or the theme object itself, with extend merged in. colors (nested keys become primary-500; DEFAULT is the parent), fontFamily (arrays joined), borderRadius and maxWidth are read; spacing, fontSize, screens, lineHeight and boxShadow are skipped as utility scales. Tailwind config files are JavaScript: export the resolved theme as JSON first (for example node -e 'console.log(JSON.stringify(require("./tailwind.config.js").theme))').

How tokens are mapped

The importer flattens every file into a list of name → value pairs and matches names against the theme tokens, the specific colors first so that accent or color.text.secondary never reaches the primary color:

When several names match, the plain one wins: color.primary or primary.500 over primary.100, primary.hover or on-primary; a default/base segment is preferred. The six extended colors take a numbered shade only from 400 to 600, and never a name that is about another role (color.text.success, color.warning.border). Everything that does not match, and every value outside a token's range (a 48 px "font size base"), becomes a custom token named after its path (color.neutral.900 → color-neutral-900, --brand-500 → brand-500); a token under a top-level custom group (as the export writes them) always stays a custom token. Dark values that match no color are left out: dark mode carries colors only. Rename tokens in the source file if the heuristics pick the wrong one, or uncheck the row in the review.

The same mapping runs through the API without saving: POST /api/theme/import { "format": "auto", "content": "..." } (site.settings) returns { tokens, mapped, unmapped, warnings }. POST /api/brand/imports reads any source into a stored import and POST /api/brand/imports/:id/apply { "rows": [...] } writes the chosen rows to the draft (api.md, Brand import); POST /api/brand/draft/publish publishes it. PUT /api/site { "theme": { ... } } still writes the live theme directly, for scripts that do not want a draft.

Exporting

Export the brand as a kit

Export in the Brand header downloads the published brand (on a site that inherits a brand, the brand it shows) as a brand kit: an ordinary kit kit.json with "kind": "brand", holding the theme tokens with dark mode and high contrast, the custom tokens, the logos and favicon (inline, at most 2 MB each; a larger logo is left out and named in the kit's description), the site's own block styles, the style guide setting and the voice. The dialog names the kit: Label, Key (brand_<site key> by default) and Version (1.0.0). Nothing is written by an export.

Install it on another Spillway site from Import brand (the Brand kit source), from Settings → Kits when it is in the kits directory, or from a package registry. However it arrives, it never touches the live brand: it is read into the Import brand review, and the rows you apply go to that site's brand draft for someone to preview and publish. From the terminal: spillway brand export <file> [--site KEY] writes the kit, spillway brand import <file> [--site KEY] applies every row to the draft (the terminal has no review step) and prints them. GET /api/brand/export answers the kit (api.md, Brand kits).

Tokens and the stylesheet

• Export published tokens on the Space and shape tab downloads tokens.json, a DTCG document of the published theme (color.primary, color.text, color.background, font.body, font.heading, radius, max-width, and custom.*). Importing that file again maps one to one, so it is a safe way to copy a theme between sites or keep it in git. GET /api/theme/export returns the same for any signed-in user.
• GET /api/theme/tokens.css is public and returns the published :root block (and the mode media blocks) as text/css, cached under the theme tag until the next publish. Link it from a microsite, a documentation theme or a design-system playground: <link rel="stylesheet" href="https://example.org/api/theme/tokens.css">.

Shared brands

On a multisite instance one site's brand can be shared: departments inherit the institution's brand and change only what it leaves open, so a university changes its primary color once and every department site follows.

• Inherit. An instance admin (sites.manage) sets Brand to Inherit the brand of <site> on a site under Site settings → Sites. Every part of the child's brand starts inherited: it shows the parent's published brand (a parent's draft never reaches it). Setting it discards the child's brand draft. One level only: a site others inherit from cannot inherit a brand itself, and a child cannot be a parent.
• Parts. A brand has six parts, the Brand tabs: Identity (logos and favicon), Color (the nine colors, dark mode and high contrast), Type (fonts, base size, scale ratio), Space and shape (radius, max width, space unit, shadow, custom tokens), Styles (block styles) and Voice. The style guide setting is every site's own.
• Lock. The parent's Brand area shows Shared with N sites and a Locked for sites that inherit this brand checkbox per part. Locks are part of the parent's draft and apply when it publishes; a public university locks Color and Type, and its departments may still change spacing. Locking a part resets it to inherited on every child that had changed it.
• Override. On the child, each tab says whether its part is Inherited (follows the parent), Overridden (this site changed it; Reset to inherited puts the parent's values back in the draft) or Locked (read-only, with a note naming the parent: the tab title says "(locked)"). Changing anything on an unlocked part overrides that part when the child publishes. The server refuses a change to a locked part from every write path (the brand draft, Import brand, PUT /api/brand, PUT /api/site { theme }) with 403 brand_locked, naming the parts.
• Follow. When the parent publishes (or a script writes its live theme or voice), every child is recomputed: the parent's values for each inherited or locked part, its own for the rest. The page cache of each child that changed is purged (site:<child>, theme, brand-guide, and the CDN through the purge hook) and the change is audited as brand.inherit.
• Stop. Setting Brand back to Its own brand, or deleting the parent site, ends the inheritance: the child keeps the brand it shows as its own (the parent's logos are copied into its media library first), so nothing visually changes. A parent's deletion is audited on each child as brand.inheritance_clear.

A child's style guide says which parts it inherits and which are locked, on the cover and under each section's heading. AI tasks and the pre-publish checks on a child read its effective voice: the parent's when Voice is inherited.

Using tokens in your own CSS

.sw-callout {
  border: 1px solid var(--sw-color-border);
  border-radius: var(--sw-radius);
  background: var(--sw-color-accent-50, var(--sw-color-surface));
  padding: calc(var(--sw-space-unit) * 2);
  box-shadow: var(--sw-shadow, none);
  font-family: var(--sw-font-heading);
  font-size: var(--sw-text-lg);
}

Always give an optional or custom token a fallback: a site that has not set it renders the fallback instead of nothing.

Navigation menus

The header renders the main menu and the footer the footer menu (both created on install and kept by the system; see Menus in getting-started). The markup needs no JavaScript: top-level items are links, items with children are <details> disclosures, and on narrow screens the whole menu sits behind a Menu toggle (a <details> as well). Styles live in the shell under .sw-nav*, .sw-nav-toggle and .sw-footer-nav and use the theme tokens, so they follow the colors and radius above; override them from block CSS or a module stylesheet if the design calls for it. The current page's link carries aria-current="page". With a logo set under Brand → Identity, the header's home link shows the logo (.sw-site-logo, at most 2.5rem high) instead of the site name.

Spillway 0.1.0 · Edit this page on GitHub