Developers

For developers who change Poison's code or build on it: how the theme is put together, the events it sends, and how to add code that survives theme updates.

Before you change code

• Duplicate the theme first. In Online Store > Themes, open the theme's … menu and choose Duplicate, then work on the copy. A mistake in code can break a storefront for customers.
• Edited files are not updated automatically. A theme update carries settings and content over, not code edits. Keep your work in new files where you can, and keep a list of every theme file you changed.
• Support does not cover code changes. If you are not comfortable with Liquid, CSS and JavaScript, hire a Shopify Partner.

Many changes need no code at all: the Custom Liquid section and block, app blocks, and the theme's settings cover most requests. Try those first.

How the theme is built

Poison is an Online Store 2.0 theme: JSON templates made of sections, sections made of blocks.

templates/*.json    → sections → blocks → snippets
layout/theme.liquid → header group · main content · footer group · cart drawer or notification · overlay group

• Sections are in sections/. The header, the footer and the overlays are section groups (header-group.json, footer-group.json, overlay-group.json).
• Blocks are theme blocks in blocks/. Files that start with _ are private to one section (the product page's blocks, a slide, a testimonial). The others can be added to any section that accepts theme blocks.
• Snippets in snippets/ are partials, for example image.liquid, product-card.liquid and price.liquid. Each opens with a {% doc %} header that lists its parameters.
• Assets: every stylesheet and script is a file in assets/. Nothing is minified, so the code is readable; Shopify minifies it when it serves it.
• The theme also ships an AGENTS.md file at its root with the same conventions, written for coding agents.

CSS

Native CSS, in cascade layers in this order: reset, tokens, base, layout, components, sections, utilities. base.css loads on every page; each section links its own file (section-*.css, component-*.css).

• Classes start with po- and follow BEM (po-card__title, po-card--portrait).
• Colors, fonts, radii and spacing are custom properties written from the theme settings by snippets/css-variables.liquid. Use them (var(--po-fg) for text, var(--po-bg) for the background, var(--po-accent), var(--po-radius-md)) instead of fixed values, so that your additions follow the merchant's settings and the color scheme they sit in.
• Use logical properties (margin-inline-start, padding-block, inset-inline-end). The theme supports right-to-left languages, and physical properties (margin-left) break them.
• To override a theme rule, write your rule in a later layer or outside the layers; rules outside any layer win over layered rules.

JavaScript

Plain ES modules and custom elements, with no framework and no dependencies. Custom elements start with po-. Scripts find their elements through data-po-* attributes.

Shared modules are imported by name through an import map:

import { POISON_EVENTS, emit, on } from '@poison/events';
import { add, change, update, get } from '@poison/cart-api';
import { renderSection } from '@poison/section-renderer';

Text and routes for scripts come from a JSON object the theme renders into the page (po-config), so that scripts hold no text of their own and every string can be translated.

Text and translations

Every string a customer reads is a translation key: {{ 'products.product.add_to_cart' | t }}. The keys are in locales/, in 12 languages. Labels in the theme editor are keys too, in the *.schema.json files. When you add a string, add it to every language file, or it shows in English there.

Links, prices and images

• Build links from the routes object ({{ routes.cart_url }}), never from a fixed path. Stores that sell in several languages or markets have prefixed URLs.
• Show prices with the money filters, and dates with the date filter.
• Render images with the image snippet. It writes srcset, sizes, dimensions, lazy loading and the focal point.

Updating part of a page

Whatever changes without a page load (the cart, a variant change, filters, predictive search, quick add) is rendered by Shopify and swapped in, through the Section Rendering API. The theme does not build HTML from JSON in the browser, so every update shows the same markup, prices and translations as a full page load.

To change the cart from your own code, use the theme's cart functions. They update the cart, redraw every cart surface and send the events. After add, the theme opens the drawer or the notification, or goes to the cart page when the cart type is Page, as it does for its own buttons:

import { add } from '@poison/cart-api';

await add({ items: [{ id: 44011, quantity: 1 }] });

If your code changes the cart some other way, ask the theme to redraw it:

document.dispatchEvent(new CustomEvent('cart:refresh'));

Events

The theme sends events on document after the page has updated. Each carries its data in event.detail.

document.addEventListener('cart:updated', (event) => {
  const { cart, action } = event.detail;
  console.log(`Cart ${action}: ${cart.item_count} items`);
});

The complete catalog, with the data of each event and examples, is in the events reference. The theme also sends Shopify's standard events for apps and analytics.

Adding your own section or block

1. Create a file in sections/ or blocks/ with a {% schema %} at the end. Give a section a preset so that it appears in the editor's Add section list.
2. Reuse the theme's building blocks. Give the section a color_scheme setting with the ID color_scheme and render the section-attributes snippet on its root element (<section {% render 'section-attributes', section: section, class: 'my-section' %}>): it applies the color scheme, the page width and the section spacing the way every other section does. Render images with the image snippet.
3. Put its stylesheet in assets/ and link it from the section with stylesheet_tag.
4. Keep {{ block.shopify_attributes }} on the root element of a block, so that the editor can select it.

Check your work

• Run shopify theme check and fix what it reports.
• Test with the keyboard alone, at phone and desktop widths.
• If the store sells in a right-to-left language, test there too.
• In the theme editor, add, move and remove your section; scripts must start again when a section is re-rendered (listen for shopify:section:load, or use a custom element, which starts by itself).