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.
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).
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.
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.
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.
6. Meet the accessibility floor
alton every image, taken from a title or a setting.aria-labelon icon-only links and dots.- A real heading order:
h2for the section,h3for items. loading="lazy"on images below the fold, and not on the first, largest one.aria-hiddenon 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?