Theming

Principle

A theme has one token source. Components use role names from that source. The editor and the front end resolve the same names to the same values.

Why

Note

Colours, type, and spacing drift when they live in more than one file. The editor sidebar offers whatever theme.json lists. A palette left over from a starter theme is what an editor applies, even when the templates use a different set of colours.

How

The palette, font families, font sizes, and spacing scale live in theme.json. CSS refers to those presets:

theme.css

color: var(--wp--preset--color--ink);
background: var(--wp--preset--color--canvas);
font-family: var(--wp--preset--font-family--body);

theme.json

{
  "settings": {
    "color": {
      "palette": [
        { "name": "Ink", "slug": "ink", "color": "#1e1e1e" },
        { "name": "Canvas", "slug": "canvas", "color": "#fafafa" }
      ]
    }
  }
}

A token name is a role (ink, canvas, brand, accent), not the raw value. A scale step such as green-500 stays inside the token file. Components use the role.

Background, text, border, and focus ring are separate roles when the values differ. A green that works as a large fill often fails as 16px text on white. Those are two tokens.

A utility framework, when one is in use, maps these same values and does not invent a second palette. The framework’s default colours, fonts, and sizes are cleared so only the theme’s tokens exist.

A classic theme that is mostly utility classes in PHP may keep the raw values in CSS. theme.json still lists that same palette. Layout widths (contentSize, wideSize) sit in theme.json with the type scale.

How to check

Tip

Hex and rgb() outside the token file. A specimen that prints a hex next to its preset is the exception.

grep -R -n -E '#[0-9A-Fa-f]{3,8}|rgba?\(' \
  --exclude=theme.json --exclude-dir=patterns .

Every preset a stylesheet uses is declared. The two sorted lists match. A slug in CSS that is missing from theme.json is a second source.

grep -R -h -o -E 'var\(--wp--preset--color--[a-z0-9-]+\)' . \
  | sed 's/.*color--//;s/)//' | sort -u
jq -r '.settings.color.palette[].slug' theme.json | sort -u

Avoid

Caution

A starter palette left in theme.json after the real colours moved into CSS. The editor offers the starter.

The same custom property assigned twice. The later assignment wins, and the earlier one is a trap.

A hover colour, a shadow, or a focus white hard-coded in a component. That value does not follow a palette change.