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 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 or NVM for version management)

Install and run

From the monorepo root:

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

Or from this package directory:

yarn dev

Storybook runs at 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 build:storybook-tokens | Re-process design-tokens CSS for Storybook | | 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

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.

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 in this package.