# Design System 2

A library of low-level components to build design systems at Salesforce. This package contains **Design System 2 (SLDS 2)**, the next-generation design system for Salesforce products.

> **Consumer documentation**: See [README.consumer.md](README.consumer.md) for the published package guide (dist structure, CSS/UIF consumption patterns, and usage examples). That file is swapped in as the package README during `npm publish`.

## Getting Started

### Prerequisites

- **Node.js** >= 20 (see [Volta](https://volta.sh/) or [NVM](https://github.com/nvm-sh/nvm) for version management)

### Install and run

From the **monorepo root**:

```bash
yarn install
yarn workspace @salesforce-ux/design-system-2 dev
```

Or from this package directory:

```bash
yarn dev
```

Storybook runs at [http://localhost:6006](http://localhost:6006).

## Scripts

| Command                       | Description                                         |
| ----------------------------- | --------------------------------------------------- |
| `yarn dev`                    | Build once, then watch JS/CSS/UIF and run Storybook |
| `yarn storybook`              | Start Storybook only (run `yarn build` first)       |
| `yarn build`                  | Full build: dev + production outputs                |
| `yarn build:production`       | Production dist outputs only                        |
| `yarn build:css:dev`          | Build dev CSS (standard + theme-layer)              |
| `yarn build:css:production`   | Build all dist/css/ outputs                         |
| `yarn build:uif`              | Build UIF artifacts                                 |
| `yarn test`                   | Run Vitest unit tests with coverage                 |
| `yarn test:scripts`           | Run build script tests only                         |

## Build Outputs

| Directory | Purpose                              | Published to npm |
| --------- | ------------------------------------ | ---------------- |
| `build/`  | Internal dev artifacts for Storybook | No               |
| `dist/`   | Consumer-facing package output       | Yes              |

Both directories are produced from the same source files and share the same PostCSS plugin infrastructure. Storybook needs composable building blocks for runtime theme switching. Consumers need final assembled outputs ready for direct use.

### Dist structure

```text
dist/
  css/
    bundled/            Structure + theme tokens baked together (one file per theme)
    modular/            Separate base + theme files (for runtime theme-swapping)
  uif/
    foundation/         Abstract component definitions
    slds/               SLDS system component definitions
```

For full details on dist contents and consumption patterns, see [README.consumer.md](README.consumer.md).

### Publishing

The `prepack` hook swaps `README.consumer.md` into `README.md` so that the published tarball and npmjs.com show consumer-focused documentation. The `postpack` hook restores the dev README automatically.

## License

See [LICENSE.txt](LICENSE.txt) in this package.