# Code theme

A code theme draws your store's storefront from files you write: Liquid for
the pages, CSS for the look and JSON for settings and texts. It goes beyond the
drag-and-drop builder: any layout, your own sections and components, on every
page of the store, and even small JavaScript apps in an isolated space.

## Where to start

| You want to | Start with |
|---|---|
| Understand the whole path, from zero to the live store | [First steps](/en/code-theme/start/) |
| Ask Claude, Cursor or another AI to change the store | [Connect your AI (MCP)](/en/code-theme/mcp/) |
| Edit on your computer, with git and your AI | [hystore tool](/en/code-theme/cli/) |
| Edit without installing anything | [Dashboard editor](/en/code-theme/editor/) |
| Copy a banner, a product showcase, a countdown | [Ready examples](/en/code-theme/examples/) |
| Add a wheel, a calculator or a mini game | [Isolated apps](/en/code-theme/apps/) |
| Integrate with your system or CI | [Theme API](/en/code-theme/api/) |

## Four ways to edit

- **In the dashboard**: Customization > Code theme > *Open the editor*. Code
  with autocomplete and checks, preview on the side. [Dashboard editor](/en/code-theme/editor/)
- **On your computer, with your AI**: `npx @hystudios/hystore theme pull`
  downloads the theme and an `AGENTS.md` that teaches the format to Claude
  Code, Cursor, Codex and others. [hystore tool](/en/code-theme/cli/)
- **With the AI connected to the store**: Claude, Cursor and other MCP apps
  sign in through the dashboard and edit the draft without installing
  anything. [Connect your AI](/en/code-theme/mcp/)
- **Through the API**: theme keys for integrations and CI. [Theme API](/en/code-theme/api/)

People who do not write code can still change texts, colours and the order of
sections in **Customize theme**, with the fields the theme declares.

## From draft to live

1. **Draft**: every edit goes to the draft. The live store does not change.
2. **Check**: each file is checked when saved (forbidden HTML, Liquid syntax,
   CSS rules, JSON format). A file with an error is refused with the line and
   the reason.
3. **Preview**: a 24-hour link opens the draft on the store's real address.
4. **Publish**: in the dashboard, whoever has the *Publish the theme*
   permission publishes. From the tool, the AI or the API it is a **publish
   request** that this person approves, seeing what changed.
5. **Use in the store**: Code theme > In the store > *Use the theme in the
   store*. While the code theme is live, the builder is turned off. Picking a
   ready layout again takes the theme off the store without deleting it.

The last 30 published versions are kept; any of them can come back to the
draft.

> [!TIP]
> A store without a theme can start from a ready theme, with every page, light
> and dark, in the store's colours: **Base** (simple and complete), **Aurora**
> (gradient band, servers in a carousel), **Celeste** (a window over a sky
> with pixel clouds, side menu) or **Prisma** (digital store look, catalog
> with filters).

## What a theme cannot do

- Run JavaScript on the page. Interaction comes from `data-hystore-*`
  attributes and `<hystore-*>` elements the store handles. Real JavaScript
  only inside an [isolated app](/en/code-theme/apps/).
- Touch money or accounts. Cart, payment, profile, purchases, password and
  sign-in are the store's own pages and open without the theme.
- Read private data. The theme sees the store's public data and only the nick
  and skin of the visitor: never e-mail, balance or orders.
- Hide the required area of the free plans (ads, legal links).

The store checks the theme when it is saved, cleans the page again when it is
drawn, and the content security policy blocks scripts. If the theme fails to
draw, the page falls back to the store's default layout instead of going
blank.

## Plans

The code theme is a plan module: it shows in stores whose plan includes
**Code theme**, and the owner can turn it off in Settings > Modules. Connecting
an AI straight to the store is an option inside that module. Without the
module, the theme screens show the way to the plans, keys and tool sessions
stop working (disconnecting is still available) and a store that used the
theme goes back to the ready layout, without deleting anything.

## Permissions

Team > Access Roles, *Code theme* group:

| Permission | Allows |
|---|---|
| View the theme | see files, versions and requests; open the editor read-only |
| Edit the theme | change the draft, images and fonts; restore versions |
| Publish the theme | publish, approve or refuse requests |
| Theme credentials | create and revoke keys, see and disconnect tool sessions |

A key or tool session never does more than the role of the person who created
it allows, and it stops working if that person leaves the store or loses the
permission. For every new key, tool login or AI app connected, the store owner
(and the person who did it, if someone else) gets an e-mail with the link to
disconnect.