Best practices

Habits that keep a theme fast, accessible, and update-proof.

A short checklist distilled from the architecture. Follow it and your theme survives platform updates, passes the gate on the first try, and feels fast.

Keep behavior on the platform

Never fetch. Call a cartisto.* method. If you find yourself wanting an endpoint the SDK doesn’t expose, that’s platform feedback — not a reason to reach around the SDK.
Enhance your own markup with controllers (data-cartisto) before reaching for a custom element. You keep the look; the platform keeps the logic.
Read shared state from cartisto.state; don’t invent window.__* globals.

Version deliberately

Patch for anything backward-compatible (copy, CSS, small fixes) — it reaches every store instantly.
Minor/major for structural change — cut a release first so customized stores opt in on their schedule.

Performance

Serve responsive images through image_url with an explicit width.
Keep your main.js for presentation only; the SDK already handles commerce.
Stay under the bundle budget — the gate enforces it, but design for it.

Accessibility & RTL

Label every control; keep one <main> landmark; give nav landmarks distinct aria-labels. The a11y gate audits home/listing/PDP/cart.
Use logical CSS properties and test under dir=rtl. See Localization & RTL.

Safe output

Trust the escape-by-default. Only | raw the platform tags, json_script output, and sanitized CMS HTML — never merchant free-text.

Work in drafts

Edit → draft → preview → publish. Use cartisto theme dev for a tight loop and cartisto theme validate before every publish.

Tip

Let the gate teach you If validate flags something, the message names the file, line, matched pattern, and the rule’s rationale. Read the why — it’s the architecture explaining which side of the line the code belongs on.