How themes work
The theme folder, the kit underneath it, and templates, designs and variants.
The folder
A theme is the theme/ folder: React components and CSS. It holds your layout, header and footer, the page-builder blocks, the store pages, optional shells around the flows Queek owns, plus three files that describe it:
manifest.ts— the theme's metadata and the variants each block, header and footer comes in.theme.config.ts— author, tags, categories, and the templates and designs it ships.demo.json— the main demo store: the products, photos and copy the preview renders.
Theme vs kit
The theme renders. The kit (@usequeek/theme-kit) does everything else: data, cart, auth and checkout. Your components read the store through hooks like useProducts, useShop, useCart and useStorefront. You never fetch, never call an API, never write to the kit's stores.
Theme → templates → designs
A theme is the look. A template is one business the theme is dressed as — food, hair, clothes — with that business's own sections. A design is one concrete demo store of a template. A merchant picks one design, and Queek builds their store from its layouts, then fills it with the merchant's own products and photos.
Variants
Each block, header and footer comes in variants: small named designs declared in manifest.ts, each with an id, a label and a one-line purpose. A variant needs a renderer and exactly the fields its component reads. Merchants switch variants in their editor.
Design tokens
Style from design tokens, never fixed sizes: var(--fs-*) for type, var(--space-*) for spacing, var(--radius-*) for corners, var(--image-*) for image sizes. A hard-coded size is a setting that does nothing in the merchant's editor.
The full contract is THEME.md — start with its Templates section for what each design must carry.