# 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](https://w4dev.com/docs/block-theme-mcp/theme-files-change-sets-backups-undo/) 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.

Source: https://w4dev.com/docs/block-theme-mcp/global-styles/