Building a Theme

Theme package layout

my-theme/
  manifest.json
  theme.json              # tokens (colors, fonts, spacing)
  components/             # optional slot overrides
    Header.tsx
    Footer.tsx
    ProductCard.tsx
  styles/
    theme.css             # CSS custom properties
  preview.png

theme.json tokens

{
  "name": "Aurora Light",
  "colors": {
    "primary": "#7c3aed",
    "primary_hover": "#6d28d9",
    "background": "#ffffff",
    "surface": "#f8fafc",
    "text": "#0f172a",
    "text_muted": "#64748b",
    "border": "#e2e8f0",
    "accent": "#f43f5e"
  },
  "fonts": {
    "heading": "Manrope, system-ui, sans-serif",
    "body": "Inter, system-ui, sans-serif"
  },
  "border_radius": "12px",
  "spacing_unit": "4px"
}

These tokens are emitted as CSS custom properties at build time:

:root {
  --color-primary: #7c3aed;
  --color-primary-hover: #6d28d9;
  --font-heading: Manrope, system-ui, sans-serif;
  --radius: 12px;
  --space-1: 4px;
  --space-2: 8px;
  /* ... */
}

The base storefront uses these tokens everywhere, so a theme can rebrand the entire experience without touching component code.

Override a slot component

Drop a component file into components/ with the same name as a base slot:

// components/Header.tsx
import { useCart, useNav } from "@carphacom/storefront"

export default function Header() {
  const cart = useCart()
  const nav = useNav()
  return (
    <header className="my-theme-header">
      {/* your custom header */}
    </header>
  )
}

The platform automatically uses your component when the theme is active. Available slots: Header, Footer, Nav, ProductCard, ProductGallery, ProductDetails, CartDrawer, CartItem, CheckoutSteps, AddressForm, PaymentForm.

Per-page overrides

For deeper customization, override an entire page route:

components/pages/
  product.tsx       # replaces /[locale]/products/[handle]
  collection.tsx    # replaces /[locale]/collections/[slug]

Page overrides receive the same data props as the base page.

Test locally

git clone https://github.com/carphacom/storefront-base
cd storefront-base
npm install
npm link ../my-theme
npm run dev

The base storefront's dev mode picks up your theme via the symlink and hot-reloads on file changes.

Publish

zip -r my-theme-1.0.0.zip .
npx carphacom-cli sign my-theme-1.0.0.zip

Submit through carphacom.com → Developer Portal → Submit Item. After review, your theme appears in the marketplace under Themes.