LiquidAuthoring Standards

Authoring Standards

These are not style preferences. Each one has already caused a real bug in a real section, and theme review checks them. A section that follows them works on every store, next to every other section, for every shopper.

1. Scope your CSS to the section

CSS in a section applies to the whole page. Two copies of your section on one page must not fight over class names, so put the section id in them.

liquid
{%- assign uid = section.id -%}
<style>
.sl-{{ uid }}-track { display: flex; }
</style>
<div class="sl-{{ uid }}-track">…</div>

2. Build lookup keys before using them in brackets

The most likely mistake in any section with a numbered list of settings. Filters do not run inside brackets, and the wrong form fails silently: no error, no output, just a section that renders nothing. Run this and compare the two lines (the example declares two settings, so the right form prints them).

Composed keys
Playground
Loading editor…

Runs in your browser on sample data: the same engine and filters as the storefront. Widgets such as add to cart are simulated: clicking one shows what would happen on a store.

Better still, use a list setting instead of numbered settings, and loop over it.

3. Guard every object

A section placed on a page without its data must render nothing, or a graceful empty state. Never a broken layout.

liquid
{%- if collection.products.size > 0 -%}
…
{%- else -%}
<p>No products to show here yet.</p>
{%- endif -%}

4. Escape what goes into attributes

Product titles contain quotes. Anything inside an attribute (alt, aria-label, data-joomni-title) goes through | escape. Body text and rich_text settings are output as they are.

liquid
<img alt="{{ product.title | escape }}" src="{{ product.featured_image | image_url: 800 }}">
<a data-joomni-title="{{ product.title | escape }} — {{ v.title | escape }}">…</a>

5. Respect reduced motion

If motion is the whole point of a section, do not merely shorten it for visitors who ask for less: stop it, and leave the content reachable another way.

liquid
@media (prefers-reduced-motion: reduce) {
.mq-{{ uid }}-track { animation: none; }
.mq-{{ uid }}-view { overflow-x: auto; }
}

6. Meet the accessibility floor

  • alt on every image, taken from a title or a setting.
  • aria-label on icon-only links and dots.
  • A real heading order: h2 for the section, h3 for items.
  • loading="lazy" on images below the fold, and not on the first, largest one.
  • aria-hidden on duplicated content, so a screen reader does not read a marquee twice.
  • Radio pickers get role="radiogroup" and visible labels. Never show the chosen state with colour alone.
  • Text has enough contrast with its background. Pair every background token with its on- colour.

7. Defaults must be publishable

Every default value has to pass review unchanged. Images must come from the Joomni media library or images.unsplash.com: a default pointing anywhere else fails the moment someone adds your section and submits without editing it.

8. Read the merchant's theme

Colours, fonts, radius and spacing come from theme tokens, so the section matches whichever store installs it. Hardcode only what is a deliberate design choice.

9. Keep scripts small and local

If a section has a script, it finds its own root by an id built from section.id, binds once, and does nothing outside the section. See Tags & snippets.

Building with AI?

Assistants connected to a Studio sandbox are given these same rules, and run the same theme review you do. See Building with AI.

Still stuck? Our team reads every message.

Need help?