npm package: @salesmind-ai/design-system
Description: Salesmind AI Design System
Author: Salesmind AI
Latest version: 0.6.0

# @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

```bash
pnpm add @salesmind-ai/design-system
```

## Usage

Import styles once in your app root:

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

Import and use components:

```tsx
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:

```bash
corepack enable
```

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

### Setup

```bash
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](https://github.com/salesmind-ai/salesmind-ecosystem) workspace, use the workspace commands instead:

```bash
# 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:

```bash
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](./ONBOARDING.md) — a structured 1-hour guide that covers setup, architecture, making changes, and understanding the rules.

For contribution details, see [CONTRIBUTING.md](./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](.github/ISSUE_TEMPLATE/component_request.md).

## License

MIT