Frameworks

Installation

How to install WDS and add it to your app.

WDS is a set of Web Components built with Lit, so it works in any stack. Every app needs two packages: the design tokens (@wds/tokens, CSS variables --wds-*) and the components (@wds/core). Angular apps also get @wds/angular with typed wrappers, forms integration and services.

Choose your framework#

Start by picking your framework, then follow its guide to install and use WDS.

Packages#

Package	What it contains	When you need it
`@wds/tokens`	CSS variables `--wds-*`: colors, radius, shadows, spacing, light and dark theme. With Tailwind CSS, also `@wds/tokens/tailwind.css`.	Always.
`@wds/core`	The `wds-*` Web Components. Each component has its own entry point, such as `@wds/core/button`.	Always.
`lit`	The library the components are built with (a peer dependency of `@wds/core`).	With a package manager.
`@wds/angular`	Typed wrappers with inputs and outputs, Signal Forms and Reactive Forms integration, dialog, drawer and sheet services.	Angular apps.
`@wds/react`	Typed React components with props and event handlers, one for each element.	React and Next.js apps.
`wds.bundle.js`	Every component with Lit in one file, shipped in `@wds/core/dist`.	Pages without a bundler, such as Spring Boot.

Local installation#

Until the packages are in a registry, build them in the wds-ds repo and install them from files. Use the .tgz files, not a file: link to the packages folder: the link resolves @angular/core from the wds-ds repo, and two copies of Angular break dependency injection.

Build the packages#

In the wds-ds repo. The command replaces the previous files in libs.

bash

# in the wds-ds repo: builds and packs every package to ./libs
pnpm install
pnpm pack:libs

tree

libs/
├── wds-angular-0.1.0.tgz
├── wds-core-0.1.0.tgz
├── wds-react-0.1.0.tgz
└── wds-tokens-0.1.0.tgz

Copy them to your app#

Keep them in libs in your app and commit them, so the app installs without the wds-ds repo.

bash

# from the wds-ds repo to your app
mkdir -p ../my-app/libs
cp libs/*.tgz ../my-app/libs/

Install packages#

lit comes from the registry, like every other dependency. Leave out @wds/angular in apps without Angular. React and Next.js apps install wds-react-0.1.0.tgz instead.

bash

# in your app
npm install ./libs/wds-core-0.1.0.tgz ./libs/wds-tokens-0.1.0.tgz ./libs/wds-angular-0.1.0.tgz lit

# only if you use wds-chart
npm install echarts

The packages point at the files:

package.json

"dependencies": {
  "@wds/angular": "file:libs/wds-angular-0.1.0.tgz",
  "@wds/core": "file:libs/wds-core-0.1.0.tgz",
  "@wds/tokens": "file:libs/wds-tokens-0.1.0.tgz",
  "lit": "^3.2.0"
}

Continue the setup#

Follow the guide of your framework from the step after installing the packages: imports are the same as with the registry.

Update#

Raise the version for every build. With the same version, npm can keep the old files from its cache and lockfile.

bash

# 1. wds-ds: raise "version" in packages/core, packages/tokens and packages/angular (e.g. 0.1.1)
pnpm pack:libs
cp libs/*.tgz ../my-app/libs/

# 2. your app
npm install ./libs/wds-core-0.1.1.tgz ./libs/wds-tokens-0.1.1.tgz ./libs/wds-angular-0.1.1.tgz

Theming#

The tokens come with a default theme. To change colors, radius and fonts, build a theme in Create, copy its theme.css and import it after the tokens.

styles.css

/* after the tokens: overrides --wds-* for the light and dark theme */
@import '@wds/tokens/tokens.css';
@import './theme.css'; /* copied from Create */

The dark theme is on when the html element has the dark class.

index.html

<!-- the dark theme follows the .dark class on <html> -->
<html class="dark">

Tailwind CSS#

With Tailwind CSS v4, import @wds/tokens/tailwind.css after the tokens. It maps Tailwind colors, radius and shadows to the --wds-* variables, so classes such as bg-primary, text-muted-foreground, border-sidebar-border or rounded-lg follow the theme, the dark theme included.

styles.css

/* src/styles.css */
@import 'tailwindcss';
@import '@wds/tokens/tokens.css';
@import '@wds/tokens/tailwind.css'; /* bg-primary, border-sidebar-border, rounded-lg... */

/* the dark: variant follows the same .dark class as the WDS theme */
@custom-variant dark (&:where(.dark, .dark *));

Without this file Tailwind does not know the WDS colors: a class like border-sidebar-border is not generated, and border-b alone draws the border in the text color.