Front-End CSS Tokens

render_header_scripts() loads a bundled system stylesheet (assets/css/synaptikCSS.php, combining the search overlay, shortcode, and gallery-layout CSS) on pages that need it. That stylesheet is intentionally theme-agnostic — it reads its colors, spacing, and typography from CSS custom properties, which your theme's style.css is expected to define.

Every token below now has a built-in fallback value. A theme defining none of them still renders a coherent, working dark-ish default — not an invisible or broken-color UI element. tests/Unit/CssFallbackTest.php parses all three stylesheets and fails the build if any var(--token) usage is missing a fallback (with two narrow, deliberate exceptions noted below), and tests/Unit/ThemeContractTokensTest.php locks in that theme/starter/css/style.css still declares the full reference set. Skipping the tokens below is never a hard error; it's purely a "does it match your brand" question.

gallery-layout.css's name is legacy and slightly misleading — the same stylesheet also styles collapsible/tabbed sections (.c-col, .tab-group), not only gallery grids.

Chained fallbacks — define a handful of general tokens, get everything

Most of the niche, component-specific tokens below fall back to a general-purpose token first, and only then to a hardcoded literal — the same way a CSS cascade already works, just one level deeper:

--search-accent: var(--color-primary, #2e7d46);
--search-accent-light: var(--color-primary-light, #4fa75c);
--search-radius: var(--border-radius-sm, 6px);
--color-background-secondary: var(--bg-accent, rgba(255,255,255,.05));
--color-text-primary: var(--text-main, #eee);
--color-text-secondary: var(--text-secondary, #9fb0a5);
--tab-color: var(--color-primary, #4fa75c);

In practice this means defining --color-primary, --color-primary-light, --border-radius-sm, --bg-accent, --text-main, and --text-secondary in your theme's :root already gets the search overlay and gallery/collapsible styling looking coherent with the rest of your design — without learning or setting a single search- or gallery-specific variable name. A theme that wants the search bar colored differently from its main accent still can, by defining the niche token directly: it wins over the chained fallback, exactly like any other CSS cascade.

Nothing was renamed and nothing was removed to make this work — every token that existed before still works exactly as before if you already defined it.

Core tokens (shortcodes, general admin-style borrowing)

Gallery grid tokens (gallery-layout.css — also styles collapsibles/tabs)

Naming here is inconsistent (four different prefixes for what is conceptually one set of tokens) — an existing inconsistency in core, not something your theme needs to fix. Just define the ones you want to customize; everything else falls back.

--c-bg/--c-color are deliberately exempt from the fallback rule: .c-col sets them on itself (an inline style="--c-color:…" from the editor's per-collapsible color picker), so they're never read from a theme's :root in the first place — a :root fallback for them would be dead code.

Search overlay tokens (search.css)

:root {
    /* Minimum you actually need to customize, thanks to chaining */
    --color-primary: #4fa75c;
    --color-primary-light: #61ce70;
    --border-radius-sm: 4px;
    --bg-accent: rgba(255,255,255,.08);
    --text-main: #eee;
    --text-secondary: #9fb0a5;

    /* Only if you want these to differ from the chained defaults above */
    --search-accent-dark: #235c35;
    --search-overlay-bg: rgba(10, 15, 12, .92);
    --search-card-bg: #1c261f;
    --search-card-bg-hover: #24312a;
    --search-checkbox-border: #4a5850;
    --search-section-heading: #9fb0a5;
}

Where to define them

Set these once, at :root level, in your theme's css/style.css — the same file you're already writing for everything else. There's no separate registration step; the system stylesheet simply reads whatever is in scope by the time it renders. theme/starter/css/style.css defines the full reference set and is the one tests/Unit/ThemeContractTokensTest.php checks against.