@futurecraft-group/design-system

The shared, multi-theme UI library that powers the Gyco e-commerce storefront — ~90 React + Tailwind components across four layers (primitives → composites → patterns → sections), plus design tokens and a Tailwind preset.

Browse it first. Every component has a live, interactive story in our Storybook explorer — see it rendered, tweak its props, read the prop table, copy a usage snippet, and flip light/dark. Run npm run storybook locally, or visit the published explorer:

https://future-craft-group.gitlab.io/gyco-re-ecommerce/web/ecommerce-design-system/

(Deployed by the pages CI job on main. If the URL 404s, confirm the exact address in GitLab → Deploy → Pages after the first pipeline runs.)

Install

Published to the FutureCraft private registry:

npm install @futurecraft-group/design-system

Peer dependencies

npm install react react-dom tailwindcss

• react / react-dom — >=18 (storefront runs React 19)
• tailwindcss — ^3

Setup — wire in the Tailwind preset (required)

Components are styled with semantic utility classes (bg-ui-button-inverted, rounded-rounded, txt-compact-medium, …) and the design-token CSS variables, all of which only exist when the preset is loaded. Without it, components render unstyled.

// tailwind.config.js
module.exports = {
  presets: [require("@futurecraft-group/design-system/preset")],
  content: [
    "./src/**/*.{ts,tsx}",
    // scan the library too so its classes aren't purged
    "./node_modules/@futurecraft-group/design-system/dist/**/*.{js,mjs}",
  ],
};

/* global stylesheet */
@tailwind base;
@tailwind components;
@tailwind utilities;

Use a component

import { Button } from "@futurecraft-group/design-system";

export function Example() {
  return (
    <Button variant="primary" size="md" onClick={() => alert("hi")}>
      Click me
    </Button>
  );
}

The package ships ESM + CJS and is marked "use client", so it works in the Next.js App Router (client components) and Pages Router.

Subpath exports

| Import | What you get | | --- | --- | | @futurecraft-group/design-system | all components + the cn() helper | | @futurecraft-group/design-system/preset | the Tailwind preset | | @futurecraft-group/design-system/tokens | raw token objects (JS) | | @futurecraft-group/design-system/utils | utilities (cn, …) |

Theming

Theming is CSS-variable based: the preset injects a light token set on :root and a dark set on .dark (darkMode: "class"). Toggle the dark class on a root element to re-theme the entire UI — components never hardcode colors:

document.documentElement.classList.toggle("dark", isDark);

See the Theming and Design Tokens pages in the explorer for the full token reference and how to add a new theme.

Local development

npm install
npm run storybook        # explorer at http://localhost:6006 (reads src directly)
npm run typecheck        # tsc --noEmit
npm run build            # tsup → dist/
npm run build-storybook  # static explorer → storybook-static/
npm run test-storybook   # interaction + smoke tests (needs `npm run storybook` running)

The explorer also includes an Accessibility panel (axe checks per story) and an Interactions panel — components like Button, Modal, and TabSwitcher ship play-function tests that double as CI checks.

The storefront consumes a built copy of this package, not its source. After editing the library:

npm run build                    # tsup
node scripts/sync-storefront.mjs # copy dist → storefront node_modules

then restart the storefront dev server (Next.js doesn't watch node_modules). During an editing session, npm run dev:link rebuilds + syncs on every save. (Storybook reads source directly, so it needs no build/sync step.)

Adding a component to the explorer

Stories are colocated with each component as Component.stories.tsx, using the Storybook CSF3 format. The contract that keeps prop tables and controls working:

1. JSDoc the props in Component.types.ts (or the inline interface) — one line per prop, with @default where the component sets one. This populates the prop-table descriptions.
2. Write Component.stories.tsx following the reference, src/primitives/button/Button.stories.tsx:
   • const meta = { title: "<Layer>/<Name>", component, tags: ["autodocs"], … } satisfies Meta<typeof X>
   • Title prefix by layer: Primitives/, Composites/, Patterns/, Sections/.
   • Curate argTypes (selects for unions, booleans, text) and give each a description.
   • A Default story plus a few showcase stories (variants / sizes / states).
   • Required props with no default (callbacks, required data) MUST be set in the meta-level args — otherwise satisfies Meta forces args onto every story and the build fails.
   • Controlled/overlay components: drive state with useState inside a render function so the canvas is interactive.
3. Reuse shared mock data from src/docs/_fixtures.ts (PRODUCT, PRODUCTS, CATEGORIES, img()) where the prop shapes match.
4. Verify: npm run typecheck && npm run build-storybook.

Cross-cutting docs pages live in src/docs/ as .mdx.

CI

.gitlab-ci.yml runs on main and MRs:

• verify — typecheck + library build (the gate)
• test-storybook — smoke-mounts every story and runs the play-function interaction tests (Playwright image)
• pages — builds the Storybook explorer and publishes it to GitLab Pages (main only)

License

UNLICENSED — © Gyco / FutureCraft.