Skip to main content
The theme is a workspace-scoped document of design tokens — brand color, font scale, border radius, motion timing — that every block reads at render time. There is one theme per workspace. By the end of this page you will understand the token categories, how blocks resolve them, and how to patch and publish a theme without touching individual pages.

​
Why one theme per workspace

Every visual property a block exposes — its background color, its corner radius, its title font size — resolves through theme tokens rather than hard-coded values. Change a token and every page in the workspace picks up the new value on the next render. You never edit individual page documents to rebrand the site. When colors.primary changes, the Hero on the landing page, the Cta on the pricing page, and the NavShell accent on the dashboard all update — no page edits required.

​
Token categories

A theme document organizes tokens into broad categories. To see the live token set for your workspace, fetch the theme document — it contains every token name and current value.

​
Reading the theme

get-theme.sh
curl https://api.gavai.app/v1/workspaces/acme/theme \
  -H "Authorization: Bearer gak_test_..."
The response is the full theme object. Full endpoint details: API reference → Theme.

​
Editing the theme

Apply changes with the same RFC 6902 JSON Patch model used for pages. Patch one token or many in a single call.
patch-theme.sh
curl -X PATCH https://api.gavai.app/v1/workspaces/acme/theme \
  -H "Authorization: Bearer gak_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      { "op": "replace", "path": "/colors/primary", "value": "#6d4aff" }
    ]
  }'
The patch writes to a theme draft — live pages keep rendering the previously published values until you publish the draft. See Editing pages with JSON Patch for operation types, path syntax, and test guards. The semantics are identical.

​
Publishing the theme

publish-theme.sh
curl -X POST https://api.gavai.app/v1/workspaces/acme/theme \
  -H "Authorization: Bearer gak_test_..."
After publish, every page in the workspace resolves the updated values on the next render.
Publishing the theme re-skins every page in the workspace immediately. Preview your changes in the Builder before publishing to a live workspace.

​
How blocks consume tokens

A block declares which token each of its visual properties should resolve to, and the runtime substitutes the current value at render time. A Hero’s background pulls from a surface color token. A Cta button’s color pulls from colors.primary. A FeaturesGrid card’s corner radius pulls from a radius token. The block document does not name a hex code or a pixel value — only the token. The benefit shows up at rebrand time. Switching a workspace from violet to teal is a single replace on /colors/primary. The eight presentational blocks and the four data-bound blocks all pick it up — no page patches, no migrations.

​
Per-instance overrides

For one-off adjustments on a single block instance, every block accepts the class_overrides common prop. Overrides layer on top of the resolved theme values and affect only the instance they’re set on. See common props on the PageBlocks overview.

​
Where to go next