A token-driven section library, on one runtime

There's a quiet fork every Shopify brand hits eventually. A native theme is editable in the theme editor and never leaves Shopify, but the front-end is capped by the template engine. A headless storefront, a React front-end talking to Shopify over the Storefront API, loads sub-second and gives you total design control, but it's usually a separate codebase built by developers you have to hire.

For a while we tried to have it both ways: one section definition, two renderers. It worked, and we shipped it. But every section then had to be authored, reviewed, and kept in pixel agreement twice, and the option was worth less than the tax. Almost no one wanted the theme output once they'd seen the headless one load. So we resolved the fork by picking a side. GemBoss now renders one way: headless. What survived the collapse is the part that was doing the real work: the section itself carries almost no styling of its own. The look lives in tokens.

Tokens are the contract

Every section in the gem library reads from a shared set of design tokens rather than hard-coded values: the brand and accent colors, the surface and line colors, a governed type ramp (a heading scale from --gem-h1 down through --gem-h6), spacing rhythm, radii. A hero doesn't decide it's 44px bold; it asks the type ramp what a headline is. A card doesn't paint itself grey; it reads the surface token.

That indirection is what makes the library restyleable. Change a brand from editorial-serif to clean-sans, or swap the accent from iris to coral, and you're changing tokens, not hunting through fifty sections for the old value. The section is a shape; the tokens are the skin.

A section is a shape. The tokens are the skin. Restyling a store is a token change, not a section rewrite.

Dawn became a standard, not a second output

Dropping the Liquid renderer didn't mean throwing Dawn away. Dawn is Shopify's reference theme, and a decade of merchant expectation is encoded in it: what a product card does on tap, how a cart drawer behaves, where the variant picker sits. Sections like gem-hero or gem-featured-collection are React ports that inherit that vocabulary deliberately.

So Dawn moved from being one of two build targets to being the benchmark the single runtime is measured against. Merchants get a storefront that behaves the way Shopify taught them to expect, without paying the template engine's ceiling for it.

Parity is a gate, not a promise

A claim like "it behaves like Dawn" is worthless without something that stops it from quietly becoming false. So it's checked, not asserted. After every production deploy, sections are rendered and compared against real Dawn, structurally and visually, and a section that has drifted fails the gate instead of being noticed by eye weeks later.

There's a second gate that matters more than it sounds. One headless deploy renders every store, so new code runs against every already-published store the moment it ships. A committed set of render fingerprints (tag order, gem-* classes, attribute names, with content stripped out) means any change to how a live store renders has to be seen and deliberately blessed in the pull request that causes it. An upgrade cannot silently restyle a store that was signed off months ago.

This is the same philosophy as the fidelity scoring on capture. A claim about the output only means something when there's a gate that stops it from being false.

What collapsing to one runtime bought

The honest accounting: we gave up the ability to hand you an editable Liquid theme. In exchange, a section is authored once and reviewed once. A brand change is a token change, not a hunt through two implementations. And every engineering hour that used to go into keeping two renderers in agreement now goes into the sections themselves.

It also keeps the whole thing yours. The storefront runs on the open gem framework, on your domain, against your own Shopify store: catalog, cart, and checkout stay exactly where they were. No proprietary section format, and nothing you can't take with you.

Back to all writing