Built with Chinaski

Design Tokens

Design tokens are named CSS custom properties — color values, sizes, anything a stylesheet can consume — stored in the database and turned into :root declarations on every built page. Change the token’s value in the admin, rebuild, and every stylesheet rule that references that variable updates site-wide. No template edits, no code.

This page explains the Design Tokens screen, how tokens reach the built pages, and how to name things well.

The Design Tokens screen

Under Design Tokens in the sidebar (Administrators and users whose allowed content types include design tokens):

  • The list shows every token sorted by its optional Group and then by name, each row carrying the name, current value, group label, and last-updated time.
  • + New Token starts a fresh entry.

Creating or editing a token

Three fields:

  • Name — the CSS variable’s identifier without the leading dashes. It must start with a letter and contain only letters, digits, hyphens, and underscores (the CSS rules reject anything else, including a leading dash). Example: accent-color.
  • Value — exactly what the CSS variable should be: a color (#FAF7F2), a spacing (1.25rem), or even a reference to another variable.
  • Group — an optional organizational label (colors, shown as a placeholder); it sorts the list, but it’s purely organizational and has no effect on the built CSS.

Rules enforced by the form:

  • Names must start with a letter.
  • Names are unique site-wide — two tokens with the same identifier is an error; edit the existing one instead.
  • Existing values stay exactly as-is until you change them (the form pre-fills).

What a token becomes on the built site

At build time, every token is turn into a CSS custom property. A token named accent-color with the value #AA2266 becomes:

:root {
  --accent-color: #AA2266;
}

and appears in the <head> of every built page (a single style block is added only when at least one token exists). Your theme’s stylesheet — or the built-in theme’s stylesheet — references it as var(--accent-color) anywhere those values are used.

This means:

  • To recolor a theme without touching its templates: create tokens matching the variable names its stylesheet already uses — you’re changing the custom-property values underneath the design, not the design rules.
  • The output is fully qualified: values are complete CSS strings, no validation, no type coercion — a token used as a color only behaves as a color where the stylesheet expects a color.
  • Names and values are both HTML-escaped in the emitted stylesheet, so there’s no injection path.

Changing a token

Edit the token’s value and save — but the site doesn’t rebuild by itself: tokens aren’t tied to automatic rebuilds. Dispatch a build (dashboard or scheduled) and the next pass writes the new value into every page. Preview endpoints share the same token query — previews reflect updated values even while the live site hasn’t been rebuilt yet.

Deleting a token

Deletion is immediate — no trash phase, no restore. On the next build the custom property simply stops being emitted. Stylesheet rules that referenced it fall back to their own defaults, since the variable no longer exists at the places it was used. If the goal was a color change, it’s usually better to update the existing token’s value than to delete and recreate.

The distinction and what not to confuse

  • Token names → CSS variable names — without the leading dash at the point of definition; the builder adds the CSS -- prefix.
  • Group labels are for you, not the stylesheet — they help sort the list, and don’t change CSS.
  • Tokens can’t shadow site kinds. You can’t make a token that isn’t a color or length behave as one; tokens are name → value pairs, nothing more than CSS references.

The short version

Set a name (a CSS variable, without the dashes) and a value in the Design Tokens screen; the build writes a :root block with all tokens on every page — and theme stylesheets respond to the variable references as colors, spacing, or anything else without a template revision.