Assets and custom JavaScript

The theme/assets/ directory contains shared CSS, theme-owned images and optional browser JavaScript.

theme/assets/
├── base.css
├── retail.css
├── theme.ts
└── images/

Keep most unique section CSS inside its section Liquid file so Agency Mode remains understandable. Put true global foundations—reset rules, typography variables and layout primitives—in base.css. Use retail.css only for styles shared across several retail routes.

Use theme.ts for interactions that Liquid and CSS cannot express, such as advanced animation, 3D rendering or a theme-wide enhancement. It must contain presentation behavior, not commerce truth.

Upstorr navigation can replace page content without a browser refresh. Re-run page enhancements after the documented upstorr:storefront-navigation event and ensure repeated initialization does not attach duplicate listeners.

Third-party browser packages must be declared in the theme checkout's package.json. Node modules, server libraries, private @upstorr/* packages, direct platform requests, cookies, auth headers and payment scripts are forbidden.