How an Upstorr theme builds a page

An Upstorr page is assembled in layers. Each layer has one job.

layout
└── template
    ├── section
    │   └── block
    └── section
        └── block

Layout

The layout is the outside frame. It owns document-level markup and the places where the header, page content and footer appear. Use theme/layout/shared/theme.liquid for normal storefront pages and bare.liquid for pages that intentionally need a smaller frame.

Template

A JSON template chooses the starting section tree for one retail route. For example, templates/retail/product.json chooses the sections used by a product page. A template stores structure and starting values; it contains no design HTML.

Section group

Header and footer are ordered groups because they repeat around several templates. Their JSON files choose the starting sections and values in those shared areas.

Section

A section is a large merchant-customizable page piece. Its Liquid file owns its HTML, section-specific CSS, Liquid decisions, right-panel settings and local block definitions. Agency Mode opens this one file rather than the entire theme.

Block

A block is a smaller piece placed inside a section. A reusable block has its own Liquid file under blocks/. A section-local block is declared by its parent section and remains editable only through that main section's code editor.

Snippet and fragment

A snippet is a small Liquid helper with no merchant identity or controls. A fragment is a separately requested piece such as predictive search or a cart drawer.

The ownership rule

Put a decision at the smallest level that completely owns it. A section's unique appearance stays in that section. A button genuinely shared by many sections belongs in a reusable block. Store data, GST, inventory, authentication and checkout truth never belong in any theme layer.