A token-driven section library for Dawn & gem

There's a quiet fork every Shopify brand hits eventually. A native theme. Built on Liquid, on the open Dawn base. 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, and the section you built for the theme doesn't come with you.

GemBoss doesn't ask you to pick a lane and rebuild if you change your mind. A section is authored once, in one library, and rendered by either runtime. The trick is that the section itself carries almost no styling of its own. The look lives in tokens.

Tokens are the contract

Every section in the Dawn + 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.

The same section, two renderers

Here's where the "two runtimes" claim has to earn itself. A section like gem-hero or gem-featured-collection has two renderers behind one definition: a Liquid renderer that emits a real Dawn-compatible Shopify section, and a React renderer for the headless storefront. Both consume the same section schema and the same tokens.

Ship native and you get a clean, editable Liquid theme that installs into your store. Ship headless and you get the edge-fast React storefront. Switch later and the sections come with you. No rebuild, because they were never tied to one runtime in the first place.

Parity is a gate, not a promise

Two renderers is exactly the kind of design that drifts. It's easy for the Liquid header and the React header to fall a few pixels out of agreement. A margin here, a first-child rule there. Until "the same section" quietly isn't. So parity isn't left to good intentions; it's checked.

Sections are rendered in both runtimes and compared, structurally and visually, so a divergence between the Liquid output and the React output is caught as a regression rather than shipped to a customer. The rule is boring and strict: if the two renderers disagree, that's a bug, not a variant.

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. "Renders the same in both stacks" is worth putting in writing precisely because a parity check enforces it.

Why one library beats two codebases

Keeping a single token-driven library instead of a theme repo and a headless repo pays off three ways. Brand changes propagate everywhere at once, through tokens. New sections land in both runtimes the day they're authored. And you keep the option to move between native and headless as your needs change. Speed when you want it, theme-editor familiarity when you want that, without throwing away the store you built.

It also keeps the whole thing yours. The library is the open Dawn base plus the gem sections, on your domain, your data. No proprietary section format that only one runtime understands, and nothing you can't take with you.

Back to all writing