storefront-kit

v0.40.0

Published

3 days ago

A collection of modern, accessible commerce UI components

0High
0Medium
0Low

hunterbecton

react components ui commerce button tailwind

Storefront Kit

A collection of modern, accessible commerce UI components built with React, TypeScript, and Tailwind CSS.

Requirements

React 18+ or 19+
Tailwind CSS 3.x (Tailwind CSS 4 is not yet supported)
Node.js 18+

Installation

# Install storefront-kit
pnpm add storefront-kit

# Install required peer dependencies
pnpm add react react-dom

# Install Tailwind CSS and plugins as dev dependencies
pnpm add -D tailwindcss tailwindcss-animate @tailwindcss/container-queries @tailwindcss/typography

Setup

1. Configure Tailwind

Add the Storefront Kit preset and content path to your tailwind.config.js:

import storefrontKit from 'storefront-kit/tailwind';

export default {
  presets: [storefrontKit],
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    './node_modules/storefront-kit/dist/**/*.{js,mjs}', // required: scan component class names
  ],
};

2. Import Base Styles

The storefront-kit/styles stylesheet contains only plain CSS (the design system's CSS variables), so it can be imported from CSS or from a JavaScript entry point with any bundler — webpack, Turbopack, or Vite.

Add the Storefront Kit styles and Tailwind directives to your global CSS file:

/* globals.css */
@import 'storefront-kit/styles';

@tailwind base;
@tailwind components;
@tailwind utilities;

Or import the styles in your JavaScript/TypeScript entry point and keep the Tailwind directives in your CSS:

// app/layout.tsx (Next.js) or main.tsx (Vite/React)
import 'storefront-kit/styles';

/* globals.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

3. Install Fonts

Storefront Kit uses Plus Jakarta Sans for headings (font-heading) and Inter for body text (font-body). Both are available on Google Fonts.

Next.js (App Router):

// app/layout.tsx
import { Inter, Plus_Jakarta_Sans } from 'next/font/google';
import 'storefront-kit/styles';

const inter = Inter({ subsets: ['latin'], variable: '--sfk-font-body' });
const plusJakartaSans = Plus_Jakarta_Sans({ subsets: ['latin'], variable: '--sfk-font-heading' });

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" className={`${inter.variable} ${plusJakartaSans.variable}`}>
      <body>{children}</body>
    </html>
  );
}

4. Use Components

Monolith (single import, props-driven):

import { Button, Badge, Alert } from 'storefront-kit';

function App() {
  return (
    <div>
      <Button variant="primary">Add to Cart</Button>
      <Button variant="outline">View Details</Button>
      <Badge>New</Badge>
    </div>
  );
}

Composable (primitives for custom layouts):

import * as ProductCardPrimitive from 'storefront-kit/product-card';

function MyProductCard() {
  return (
    <ProductCardPrimitive.Root aspectRatio="5/6">
      <ProductCardPrimitive.Preview>
        <ProductCardPrimitive.Thumbnail>
          <ProductCardPrimitive.Image src="/product.jpg" alt="Product" />
        </ProductCardPrimitive.Thumbnail>
        <ProductCardPrimitive.Link href="/products/1" aria-label="View product" />
      </ProductCardPrimitive.Preview>
      <ProductCardPrimitive.Details>
        <ProductCardPrimitive.Header>
          <ProductCardPrimitive.Title>Product Name</ProductCardPrimitive.Title>
          <ProductCardPrimitive.Price price={{ type: 'default', value: '$19.99' }} />
        </ProductCardPrimitive.Header>
      </ProductCardPrimitive.Details>
    </ProductCardPrimitive.Root>
  );
}

Additional primitives are available for more advanced layouts: Subtitle, Rating, Badge, Skeleton, Actions, Form, Input, CartButton, CartLink, and Compare.

Web Components

Storefront Kit also ships framework-free web components. They need no React and no Tailwind — install the package and import the component's subpath:

pnpm add storefront-kit

import 'storefront-kit/web/carousel';

<sfk-carousel loop>
  <img src="/slide-1.jpg" alt="" />
  <img src="/slide-2.jpg" alt="" />
</sfk-carousel>

The import registers the sfk-carousel* custom elements. Components render with built-in defaults; to theme them, define --sfk-* custom properties on the page (custom properties inherit into shadow roots), or import storefront-kit/styles for the full token set — it's prebuilt CSS and needs no Tailwind.

React imports are also available as storefront-kit/react and storefront-kit/react/<component>; the bare storefront-kit spelling continues to work.

Tailwind Utilities

The preset adds design system utilities you can use throughout your app:

<div className="bg-brand text-background">
  <h1 className="font-heading text-foreground">Hello World</h1>
  <p className="font-body text-contrast-400">Body text</p>
</div>

Color utilities:

| Token | Tailwind classes | |---|---| | Brand | bg-brand, bg-brand-background, bg-brand-foreground | | Success | bg-success, bg-success-background, bg-success-foreground | | Error | bg-error, bg-error-background, bg-error-foreground | | Warning | bg-warning, bg-warning-background, bg-warning-foreground | | Neutral | bg-background, bg-foreground | | Contrast | bg-contrast-100 through bg-contrast-500 |

Typography utilities:

font-heading — Plus Jakarta Sans
font-body — Inter

Helper utilities:

scrollbar-none — hides scrollbars while keeping the element scrollable
focus-primary — keyboard-only focus outline using --sfk-border-focus-primary
focus-secondary — keyboard-only focus outline using --sfk-border-focus-secondary

Customization

Override CSS variables to customize the design system. All color variables use OKLCH format (lightness chroma hue):

/* globals.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

:root {
  --sfk-brand-lch: 0.6 0.2 250;        /* OKLCH: lightness chroma hue */
  --sfk-foreground-lch: 0.18 0 0;
  --sfk-background-lch: 1 0 0;
}

All available color variables:

| Variable | Default | |---|---| | --sfk-brand-lch | 0.57 0.24 277 | | --sfk-brand-background-lch | 0.95 0.05 277 | | --sfk-brand-foreground-lch | 0.3 0.03 277 | | --sfk-background-lch | 1 0 0 | | --sfk-foreground-lch | 0.18 0 0 | | --sfk-contrast-100-lch | 0.95 0 0 | | --sfk-contrast-200-lch | 0.86 0 0 | | --sfk-contrast-300-lch | 0.76 0 0 | | --sfk-contrast-400-lch | 0.63 0 0 | | --sfk-contrast-500-lch | 0.45 0 0 | | --sfk-success-lch | 0.85 0.2 142 | | --sfk-success-background-lch | 0.95 0.05 142 | | --sfk-success-foreground-lch | 0.3 0.1 142 | | --sfk-error-lch | 0.59 0.24 26 | | --sfk-error-background-lch | 0.95 0.05 26 | | --sfk-error-foreground-lch | 0.2 0.1 26 | | --sfk-warning-lch | 0.8 0.16 80 | | --sfk-warning-background-lch | 0.95 0.05 80 | | --sfk-warning-foreground-lch | 0.25 0.06 80 |

Font family variables:

| Variable | Default | |---|---| | --sfk-font-heading | 'Plus Jakarta Sans', sans-serif | | --sfk-font-body | 'Inter', sans-serif |

Documentation

For detailed component documentation, examples, and interactive demos, visit our Storybook.

License

MIT — see LICENSE.md for details.