Themes that are design tokens, not forked stylesheets

The usual life of an ecommerce theme is well documented. You buy or build one, you customise it, and each customisation makes the next platform update slightly more dangerous. Two years later the theme cannot be updated, security fixes are declined, and a redesign means starting again.

The cause is that customisation forks the code. Change one thing and you now own a copy of everything.

A theme is a set of values

Qwikr’s storefront themes are token presets rather than separate stylesheets. Colours, type, spacing, corner radius, shadow — a theme family is a set of values fed into one set of templates.

Two consequences that matter. Improvements to the templates reach every shop, because there is only one set. And a shop cannot end up permanently stranded on an old version, because it was never carrying its own copy in the first place.

What that costs you, honestly

You cannot restructure a page by editing a template file. If your design needs the product page laid out in a fundamentally different way, tokens will not get you there.

That is the trade, and it is the right one for most merchants and the wrong one for a few. If you genuinely need arbitrary layout, the answer is not to fight the theme — it is to build a bespoke front end on the API and let Qwikr be the commerce layer behind it. That is a supported path rather than a failure.

The trap in a token system

Worth stating because it has bitten this codebase. If a section is committed to one look — a deliberately dark call-to-action band, say — it must not be built on a token that changes with the theme.

Build that band on the general “ink” colour and it looks right until the theme inverts, at which point the background goes light while the hardcoded white text stays white, and the section becomes invisible. Committed sections take fixed values. It is the sort of bug that passes every review and is discovered by a customer.

Adding a family

A new theme family is a new preset, which means it must be registered as well as defined. A preset that is defined but not registered does not fail loudly — it silently falls back to the default, and the shop looks fine while being on entirely the wrong theme. If a new theme appears to do nothing, that is the first thing to check.

Preview before publish

Because the storefront is published as static files rather than rendered per visitor, a design change is a deliberate act rather than a side effect of saving. That makes preview more important than it is on a database-backed shop, and it means you can see exactly what will go out before it does.

It also means a bad change is not live the instant you make it, which on balance is worth more than instant updates.