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.