File structure

A theme is a tree of Liquid views, assets, locales, and one manifest.

my-theme/
├── theme.json                 # manifest: settings schema + section catalog + version
├── views/
│   ├── pages/
│   │   ├── layout.liquid       # the page shell (REQUIRED) — wraps every page
│   │   ├── home.liquid
│   │   ├── product/single.liquid
│   │   ├── product/index.liquid   # product listing / collection
│   │   ├── category.liquid
│   │   ├── cart.liquid
│   │   ├── customer/dashboard.liquid
│   │   ├── store-page.liquid       # CMS pages
│   │   ├── blog/index.liquid, blog/single.liquid
│   │   ├── track-order.liquid
│   │   └── error.liquid
│   ├── sections/                # composable content sections (one file per type)
│   │   ├── hero.liquid          # rendered via section.partial — never hardcode this path
│   │   └── …
│   ├── blocks/                  # block partials (one file per block type)
│   │   ├── title.liquid         # product-core + section blocks — rendered via block.partial
│   │   └── …
│   └── components/
│       ├── header/header.liquid
│       ├── footer/footer.liquid
│       └── …                    # your own partials, rendered with {% render %}
├── assets/
│   ├── css/theme.css            # the compiled stylesheet layout.liquid links
│   ├── css/style.src.css        # Tailwind source (platform-compiled; not served)
│   └── js/main.js               # your presentation JS (runs AFTER the SDK)
└── locales/
    ├── en.json                  # per-theme string overrides (optional)
    └── ar.json

The pages that matter

• layout.liquid is the shell every page renders inside. It must output three platform tags or the save is rejected:

  {{ platform_head | raw }}   {# SEO, globals, fonts, design tokens, your CSS #}
  {{ content | raw }}         {# the current page #}
  {{ platform_body | raw }}   {# the SDK + commerce scripts + your JS #}
  

  Keep {{ platform_body | raw }} before your own main.js — your scripts depend on window.cartisto, which platform_body loads.

• checkout and order-confirmation are locked. They render from platform-owned templates for every theme. Your theme can’t ship them, and the save API rejects views/pages/checkout.liquid. This is what keeps the payment surface safe. Cart stays fully themeable.

Assets

• assets/css/theme.css is what layout.liquid links and what the platform serves. If you use Tailwind, edit assets/css/style.src.css; the platform compiles it to theme.css.
• Images and fonts referenced from CSS are yours to include; product images come through the platform as absolute URLs.

Locales

Storefront strings layer: a shared platform base, then your theme’s locales/<lang>.json overrides on top (deep-merged). Override only the keys you want to change — see Localization.

The manifest

theme.json declares the settings a merchant can configure, the sections they can compose, the SDK contract version you target, and your release version. See theme.json reference.