storefront-react-ai-template

Boilerplate for a Swell storefront generated by the swell-ai-api codegen pipeline. Empty by design — pages, sections, blocks, and color schemes are filled in by the design + code agents before anything is shipped.

Dev

bun install
bun dev          # vite on PORT (default 3000)
bun build        # vite build
bun preview      # build + vite preview
bun deploy       # build + wrangler deploy

vite dev runs the template standalone, but with empty theme/settings/settings.json no color scheme is applied — expected. Run the codegen pipeline against this template to get a populated storefront.

Files the codegen pipeline overwrites

These are regenerated after the design agent finishes. Hand-edits are lost.

File	Stamper
tailwind.config.js	stampTailwindConfig — emits Tailwind colors from scheme roles + shadcn aliases
src/settings/schema.ts	stampSettingsSchema — emits the editor schema (color_scheme_group + cart_color_scheme) from declared scheme roles
src/sections/index.ts	stampRegistry — wires generated sections into the SDK's SectionRegistry
theme/settings/settings.json	populated by addColorScheme etc. — agent decides hex values per scheme
theme/templates/pages/*.json, theme/templates/layout/*.json	populated by template/section composition tools
src/sections/<section-type>/index.tsx	componentGenerate — section LLM phase
src/blocks/<Block>.tsx	componentGenerate — global block LLM phase (one file per unique block type, shared across sections)

Files that are boilerplate (don't get regenerated)

• src/App.tsx, src/main.tsx — app entry + routing wiring: reads the page registry from swell.json (storefront.theme.pages: id/url/collection), globs the per-page template JSONs, and hands URL-routed PageDeclarations to SwellStorefrontApp. Routing is URL-based — there are no page archetypes.
• src/components/ui/* — shadcn primitives the codegen LLM imports from @/components/ui/<name>. The validator only allow-lists imports for primitives that exist here, so the full set must stay even when no section imports a particular one yet.
• src/components/ErrorBoundary.tsx, src/lib/utils.ts — shared utilities.
• worker/* — Cloudflare Worker entrypoint that injects window.__SWELL__ from request headers. Marked "STRICTLY forbidden" to edit; codegen must not touch.
• src/index.css, vite.config.ts, tsconfig*.json, wrangler.jsonc, eslint.config.js, postcss.config.js, components.json — build/lint/runtime config.

Color scheme contract

Every scheme in theme/settings/settings.json must declare these 10 canonical roles (plan-time Zod enforces it). The design agent picks hex values per scheme and may add brand-specific extra roles on top.

background, text, surface, muted, border,
button, button_label, secondary_button, secondary_button_label, accent

Tailwind aliases derived in stampTailwindConfig (shadcn-compatible):

foreground             ← text
primary, primary-fg    ← button, button_label
secondary, secondary-fg← secondary_button, secondary_button_label
card, popover          ← surface
card-fg, popover-fg    ← text
accent, accent-fg      ← accent, button_label
muted, muted-fg        ← muted
input                  ← border
ring                   ← button
destructive            ← oklch (intentionally not brand-coupled)

Plan-time validators also reject schemes whose role pairs fall below WCAG AA contrast (4.5:1 for text pairs, 3:1 for UI/label-on-color pairs).