Theme customizer

Admin → Themes → Customize (/admin/themes/customize). Use Styles for identity, light and dark colour palettes, body typography, headings, spacing scale, corners, shadows, wide width, default navigation, and Additional CSS. Use Home, Blog, Header, and Footer to select or build the site's shared surfaces. Changes have draft and published states.

Effective CSS is served at `GET /theme.css` (preview-aware). Custom CSS is sanitized (lib/safe-css.ts) so a theme cannot inject arbitrary harmful rules. Theme mods are cached under theme:mods:.

Related APIs live under /api/themes customize GET/PATCH/DELETE. Roles that may customize are checked on the server (administrators and designated customize roles).

Design tokens and dark mode#

Customizer controls generate validated CSS variables. Heading font, weight, line height, letter spacing, and H1–H3 sizes become tokens; one spacing value drives the responsive rhythm used by every block. Corners, shadows, and wide width work the same way. Theme CSS loads first, generated site tokens next, and Additional CSS last so editor choices win predictably.

The dark palette applies when a visitor chooses dark and, with no stored choice, when the device requests dark. The Light / dark block can expose Auto, which clears the stored preference and follows device changes live.

Header builder#

Theme builder → Header keeps a library of named headers. One is marked the site default and renders on every page; each page then picks its header from a dropdown in the page builder — the site default, a named header, or *None* — instead of editing header chrome inline. Every header carries a base config plus sparse per-language overrides (the exact locale merged over the base) and has draft and published states like the footer. The per-page choice persists immediately via PUT /api/content/:id/header-ref, independent of the page's Save. Site-wide chrome documents live in the template_parts table. Plugins and themes can contribute headers through the header.templates, header.resolve, and header.config hooks.

Theme-contributed controls#

A theme adds its own controls with a customize block in justflows-theme.json. Each control is a color, range, select, or font, keyed by the CSS custom property it sets and grouped into named sections. schemaWithThemeControls merges them onto the built-in schema, so the values flow to :root and draft and publish exactly like the core tokens. A sibling blockControls map lists, per block type, the variables to surface as first-class inspector fields.

{
  "customize": {
    "brand": {
      "label": "Brand",
      "controls": {
        "--brand-accent": {
          "label": "Accent",
          "type": "color",
          "default": "#3b82f6"
        },
        "--brand-tilt": {
          "label": "Card tilt",
          "type": "range",
          "default": 0,
          "min": 0,
          "max": 5,
          "step": 0.5,
          "unit": "deg"
        }
      }
    }
  },
  "blockControls": {
    "core.hero": [
      "--brand-accent",
      "--brand-tilt"
    ]
  }
}