Theme folder architecture

Upstorr themes follow Upstorr Design Control—three modes for three different levels of design freedom:

  1. Founder Mode: merchants use sliders, choices and fields in the visual editor.
  2. Agency Mode: agencies edit one selected Liquid section at a time.
  3. Developer Mode: developers use this complete CLI checkout.

Read docs/upstorr-design-control.md to understand the boundary and purpose of each mode.

Only theme/ is storefront source. The other root folders help people build and test it.

my-theme/
├── README.md
├── package.json
├── tsconfig.json
├── docs/
├── tests/
├── .upstorr-theme/                 generated by the CLI
│   ├── lock.json
│   ├── sdk/                        generated SDK autocomplete
│   ├── state/
│   └── build/
└── theme/                          authored storefront source
    ├── storefront.json
    ├── config/
    │   └── settings.json
    ├── controls/
    │   ├── shared/
    │   └── retail/
    ├── layout/
    │   ├── shared/
    │   │   ├── theme.liquid
    │   │   └── bare.liquid
    │   └── retail/
    ├── templates/
    │   └── retail/
    ├── section-groups/
    │   └── retail/
    ├── sections/
    │   ├── shared/
    │   └── retail/
    ├── blocks/
    │   ├── shared/
    │   └── retail/
    ├── snippets/
    │   ├── shared/
    │   └── retail/
    ├── fragments/
    │   └── retail/
    ├── assets/
    │   ├── base.css
    │   ├── retail.css              optional shared retail CSS
    │   ├── theme.ts                optional browser JavaScript
    │   └── images/
    └── locales/
        └── en.default.json

What each place does

  • storefront.json is the theme identity card. It declares the theme key, channel and public contract versions.
  • config/settings.json declares theme-wide controls such as the logo, colours and page width.
  • controls/ stores repeated groups of right-panel controls. It renders nothing by itself.
  • layout/ contains the outside frame shared by pages.
  • templates/retail/ contains starting section trees for retail routes. JSON chooses pieces and starting values; it does not contain HTML.
  • section-groups/retail/ contains starting header and footer trees.
  • sections/ contains large page pieces. One Liquid file owns that section's HTML, CSS, Liquid rules, controls and section-local block definitions.
  • blocks/ contains reusable visible Liquid pieces such as Button, Text or Product card.
  • snippets/ contains small Liquid helpers with no merchant identity or controls.
  • fragments/ contains pieces requested separately, such as predictive search or a cart drawer.
  • assets/ contains shared CSS, images and optional Level 3 JavaScript.
  • locales/ contains shopper-facing translated words.

Retail templates supplied by the starter

The starter includes home, product, collection, collection list, cart, checkout, search, normal page, contact page, blog, article, sign-in, orders, wishlist, bookings, booking detail, digital delivery, gift card, password, maintenance and 404 templates.

Templates are a safe starting tree, not a promise that every brand wants the same screen. Product, cart and checkout demonstrate public commerce data and behaviour. The specialist account/order/wishlist/booking templates start as small presentation shells so developers can design them deliberately with the documented SDK instead of inheriting another brand's design.

The sharing rule

Share a whole understandable thing, such as a Button block or a Box control pack. Do not hide a section's unique appearance in a distant helper merely to save a few lines. An agency or AI should be able to open one section and understand its design.

What never belongs in theme/

Do not add src/, schema/, node_modules/, generated bundles, tests, API clients, authentication code, tax calculations or payment-provider code. The CLI generates runtime files under .upstorr-theme/; Upstorr owns commerce truth behind the public SDK.

Do not add empty wholesale folders. This starter is retail-only.