@salesmind-ai/design-system

A production-grade React component library built with Base UI, Storybook, and TypeScript.

Features

• Base UI — Built on headless primitives for maximum accessibility and customization
• CSS Variables — Theming via native CSS custom properties
• Tree Shakeable — ESM and CJS builds with side-effect marking
• TypeScript — First-class type support with full declarations
• Storybook — Every component documented with interactive stories

Installation

pnpm add @salesmind-ai/design-system

Usage

Import styles once in your app root:

import '@salesmind-ai/design-system/styles.css';

Import and use components:

import { Button } from '@salesmind-ai/design-system';

function App() {
  return <Button>Click me</Button>;
}

Entry points

| Import path | Description | |---|---| | @salesmind-ai/design-system | Main components | | @salesmind-ai/design-system/core | Core primitives | | @salesmind-ai/design-system/sections | Section shell and section primitives | | @salesmind-ai/design-system/nav | Navigation components | | @salesmind-ai/design-system/motion | Motion-enabled components | | @salesmind-ai/design-system/social-proof | Social proof components | | @salesmind-ai/design-system/marketing | Marketing/conversion components | | @salesmind-ai/design-system/blog | Blog and long-form content components | | @salesmind-ai/design-system/charts | Chart components | | @salesmind-ai/design-system/report | Report engine components | | @salesmind-ai/design-system/web | Backward-compatible mixed web entry | | @salesmind-ai/design-system/web/server | Server-safe SEO + JSON-LD utilities | | @salesmind-ai/design-system/web/client | Client-only consent + analytics utilities | | @salesmind-ai/design-system/theme | Theme system | | @salesmind-ai/design-system/i18n | Internationalization helpers | | @salesmind-ai/design-system/styles.css | Compiled CSS |

Web boundary rule

• Use @salesmind-ai/design-system/web/server for JSON-LD and schema generators in server components.
• Use @salesmind-ai/design-system/web/client for cookie consent hooks/components and analytics loaders.
• Treat @salesmind-ai/design-system/web as backward compatibility only, not the preferred import for new code.

CSS contract

Public CSS entrypoints are part of the package contract:

• @salesmind-ai/design-system/styles.css
• @salesmind-ai/design-system/index.css
• @salesmind-ai/design-system/core.css
• @salesmind-ai/design-system/web.css

Consumers should rely on these public CSS exports instead of private dist/ paths.

Development

This project uses pnpm. Make sure you have it installed:

corepack enable

The correct pnpm version is pinned in package.json via the packageManager field — corepack handles the rest.

Setup

pnpm install

Commands

| Command | Description | |---|---| | pnpm dev | Watch mode — rebuilds dist/ on every change | | pnpm build | Build the library (ESM + CJS via tsup) | | pnpm test | Run unit tests (vitest) | | pnpm test:watch | Run tests in watch mode | | pnpm lint | Lint with ESLint (zero warnings allowed) | | pnpm lint:css | Lint CSS with Stylelint | | pnpm typecheck | Type-check with TypeScript (tsc --noEmit) | | pnpm storybook | Start Storybook dev server on port 6006 | | pnpm build-storybook | Build static Storybook | | pnpm tokens:build | Build design tokens | | pnpm tokens:check | Verify tokens are in sync | | pnpm size | Check bundle size (size-limit) | | pnpm compliance:check | Run compliance checks |

Working in the monorepo

When developing inside the salesmind-ecosystem workspace, use the workspace commands instead:

# Design system + frontend (hot-reload)
pnpm dev:ds+frontend

# Design system + docs site
pnpm dev:ds+docs

# Design system + website
pnpm dev:ds+website

# Storybook standalone
pnpm storybook

Changes in src/ are rebuilt by tsup and hot-reloaded in consuming apps automatically.

Note: Consuming apps import from dist/, not src/. Make sure the dev watcher is running.

Project structure

src/
├── components/      # React components
├── core/            # Core/primitive exports
├── web/             # Mixed legacy web boundary (backward compat)
│   ├── server/      # Server-safe SEO/JSON-LD exports
│   └── client/      # Client-only consent/analytics exports
├── report-engine/   # Report generation logic
├── report-export/   # Report export utilities
├── i18n/            # Internationalization (react-intl)
├── stories/         # Storybook stories
├── styles/          # CSS + generated design tokens
├── theme/           # Theme configuration
├── tokens/          # Design token definitions
├── mocks/           # MSW mocks for Storybook
└── index.ts         # Main barrel export

Releasing

Releases are automated via GitHub Actions. Every push to main triggers a publish to npm using OIDC trusted publishing (no token required).

To bump the version:

pnpm changeset        # create a changeset describing the change
pnpm changeset version # apply the version bump
git add . && git commit -m "chore: version bump"
git push

Onboarding

New to the design system? Start with ONBOARDING.md — a structured 1-hour guide that covers setup, architecture, making changes, and understanding the rules.

For contribution details, see CONTRIBUTING.md.

Governance

This design system is the sole owner of all UI primitives, design tokens, component APIs, variant systems, accessibility standards, and motion standards.

If a component is missing, it must be created here first — with stories, tests, accessibility, and documentation — before any consuming application may use it.

To request a new component, use the Component Request issue template.

License

MIT