> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shoppex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Visual themes

> Edit ThemeDocument settings, pages, and blocks in the Theme Builder, then preview and publish.

An Easy theme is a ThemeDocument: a set of pages built from ordered blocks, each with typed settings. Edit it in the Theme Builder, or automate it with the CLI and API.

## What settings cover

ThemeDocument settings are structured data, validated against the theme's schema. They cover:

* Colors, typography, spacing, and shape tokens
* Page and block content
* Block visibility and variants
* Approved custom CSS

Fetch the current settings before you update them. An update sends the complete validated settings object, so an omitted key removes that value.

<Warning>
  Settings hold presentation data only. Do not store secrets in them. Do not reproduce pricing, stock, payment, or checkout rules there. Those stay server-side.
</Warning>

## Blocks and stable IDs

Each block on a page has a stable ID, a registered type, a visibility flag, and typed settings. The ID stays the same when you reorder or edit the block. A later automated update or an AI edit targets that ID, so a changed ID looks like a deleted block plus a new one.

An unknown block type or an invalid setting fails validation. Shoppex does not select a fallback block or guess a value in its place.

## The editing loop

The Theme Builder holds the source of truth for a draft.

<Steps>
  <Step title="Inspect">
    Open the page in the Builder, or fetch the current document and settings, before you change anything.
  </Step>

  <Step title="Edit">
    Change only the page, block, or setting you intend to update.
  </Step>

  <Step title="Preview">
    Check every page type that uses the changed block: product, collection, content, and system pages.
  </Step>

  <Step title="Save">
    Saving stores your draft. It does not change the live storefront.
  </Step>

  <Step title="Publish">
    Publishing validates the document and creates a new revision. Visitors see the new revision only after it completes.
  </Step>
</Steps>

## Revisions and conflicts

Every publish creates a new revision. A published revision never changes afterwards, so a visitor never receives a half-written document.

Another editor, an AI edit, or a CLI push can save a newer draft while you work. If that happens, your save or publish is rejected with a revision conflict instead of silently overwriting that work. If you get a revision conflict, reload the latest draft. Then reapply your change on top of it.

For a self-hosted headless application, use `@shoppexio/storefront` instead of the Theme Builder. See [Themes](/storefront/themes) for how the two compare.