Theme contract specification

The single, authoritative statement of the theme contract. Everything here is mechanically enforced by the Quality Gate in the CLI, the tests, and the publish path — this page is the human-readable mirror of that one source of truth.

Required layout tags

views/pages/layout.liquid MUST output all three (a publish is rejected otherwise):

Tag	Provides
{{ platform_head | raw }}	SEO meta + JSON-LD, title, window.__* globals, i18n, fonts, design tokens + merchant CSS, pixels (head)
{{ content | raw }}	The current page
{{ platform_body | raw }}	Pixels + analytics, the SDK + commerce bundles, the page bundle, merchant JS

Banned patterns

A theme MUST NOT contain (matched against .liquid/.js):

Pattern	Why	Use instead
fetch(	Themes don’t call the API	a cartisto.* method
salla.	Pre-rebrand SDK global	window.cartisto.*
<script src=…/js/store-…>	Platform scripts are injected	let platform_body inject them
<add-to-cart-button>, <wishlist-button>, <store-auth-modal>	Pre-namespace element names	<cartisto-add-to-cart>, <cartisto-wishlist>, <cartisto-auth-modal>
addToWishlist, changeMainImage	Behavior owned by the platform	the wishlist component / PDP controller
"cartUpdated"	Renamed event	cartisto:cart:updated
bare window.productData / window.storeTheme	Seed-global naming	window.__PRODUCT__ / window.__STORE_THEME__

Manifest requirements

• theme.json MUST declare a known "sdk" contract version.
• theme.json MUST declare a semver "version" (the release version).
• Release snapshots (releases/<MAJOR.MINOR>/) MUST be well-formed, version- consistent, and archive a past minor line.

Locale parity

Every locale file in a theme MUST expose the same key set — a key one language has and another lacks is a failed publish.

Locked pages

views/pages/checkout.liquid and views/pages/order-confirmation.liquid MUST NOT exist in a theme. The payment surface is platform-owned and platform-rendered.

Bundle budget

Storefront JS MUST stay under the per-entry and per-page byte budgets. This keeps the shopper experience fast regardless of theme.

The event & data-attribute grammar

• Root marker: data-cartisto="<name>"; child ref: data-cartisto-ref="<part>"; platform-written stamp: data-cartisto-bound (never author it).
• Events are named cartisto:<domain>:<verb> — see the event catalog.
• Seed globals follow window.__NAME__.