W4DEV

Global styles

By the end of this page you know how an agent reads and changes the site’s global styles, the colours, typography and spacing you would otherwise set in the Site Editor’s Styles panel, and how to take a change back.

These tools are in the Global styles group. It starts off, and it needs the edit_theme_options capability and an active block theme.

Which styles the tools change

A block theme’s look comes from three layers. WordPress has defaults. The theme’s theme.json sits on top of them. Your own changes, made under Styles in the Site Editor, sit on top of both and are stored in the database.

The tools in this group work on the third layer only: your own customisations. They do not write theme.json. To change the theme’s own defaults, edit theme.json with the Theme files tools instead.

Because these changes live in the database, a theme update does not remove them.

Read

btm.styles-read returns your current styles and settings, and a hash. With merged: true it also returns the merged result of the theme and your customisations, which is what the site uses. The merged result is for reference: it tells the agent which values come from the theme, so it changes only what it has to.

Change

btm.styles-update replaces styles, settings or both. Each one it sends replaces the saved one as a whole, so the agent reads first and sends the complete object with its change in it. The agent sends the hash it read as expectedHash. If the styles changed in between, for example because you saved in the Site Editor, the call is refused and the agent has to read again.

The save goes through WordPress’s own global styles code. WordPress checks and cleans the values, exactly as it does for a save in the Site Editor, and keeps a revision.

An example of what an agent sends to set the body text colour and a heading size, on a site with no other customisations yet:

{
  "styles": {
    "color": { "text": "#1a1a1a" },
    "elements": {
      "h2": { "typography": { "fontSize": "2rem" } }
    }
  },
  "expectedHash": "<hash from btm.styles-read>"
}

Go back

  • btm.styles-revisions lists the saved revisions of your global styles. They are the same revisions the Site Editor keeps for Styles.
  • btm.styles-restore-revision puts one back. It needs expectedHash, like an update.
  • btm.styles-reset clears all your customisations, so the site uses the theme’s own styles again. It needs expectedHash too. The revision history stays, so a reset can be undone by restoring a revision.

Confirmation

btm.styles-update, btm.styles-restore-revision and btm.styles-reset are marked destructive. A browser agent asks you before running them while Confirm destructive tools is on. A remote client asks in the client. btm.styles-read and btm.styles-revisions are read-only.

If something goes wrong

  • The group’s checkbox is disabled. The active theme is a classic theme, or your account lacks edit_theme_options. The Theme row of the Status card says which kind of theme is active.
  • A change does not show on the site. Check for a page cache first. Then ask the agent to call btm.styles-read with merged: true and compare the value with what you expect.