Conventions
Rules the theme holds itself to. Read these before writing anything; most exist because breaking them causes a subtle failure rather than an obvious one.
| Page | Covers |
|---|---|
| Colours | Brand palette, why arbitrary hex is banned, gradients, dark context |
| Spacing & Layout | The px-to-rem scale, the .container utility, custom property syntax |
| Liquid & Schema | Liquid gotchas, schema patterns, translation placement |
| Metafields | The migrelief namespace, legacy custom, full store inventory |
The short version
Section titled “The short version”Colours come from the palette. Never bg-[#013d32] — use bg-deep-green.
If Figma specs a colour with no matching token, ask before adding one.
Convert px to the spacing scale. w-[138px] is w-34.5. Divide by 4.
Arbitrary values are for genuinely off-scale things like hairlines.
Use .container, don’t compose one. container px-4 overrides the
responsive gutter and quietly breaks wide layouts.
Liquid has no ternary. And filters are silently dropped on render
arguments — a real bug source.
Every schema label needs a translation. Blocks translate under blocks,
sections under sections. Mixing them up throws confusing errors.
Theme check must pass with zero errors before committing.
New metafields go in the migrelief namespace. Never custom or
custom_fields — those are the previous agency’s and are being retired.
Still to write
Section titled “Still to write”Accessibility, performance, image handling, Alpine patterns, and metaobjects — see the Docs Backlog.