Installation

The design system is not published to a package manager. You install it by placing the design-system/ folder in your project, then building your own stylesheet that imports it. There is no pre-compiled CSS to link — you own the build.

Tip

This is deliberate: it lets your project’s styles and the design system share one Tailwind build, so you can add your own utilities and overrides. See the stylesheet model in the overview.

1. Add the folder

1. Copy the design-system/ folder into the directory your server exposes as static files:

   Vanilla / static
   • Directorymy-site/

     • index.html
     • Directorydesign-system/ (place it here)

       • …
   JSP / webapp
   • Directorysrc/main/webapp/

     • Directorypages/

       • …
     • Directorydesign-system/ (place it here)

       • …

2. Everywhere the docs write /design-system/..., use the path where you put the folder.

2. Install the build dependencies

These are needed only to compile the design system (Tailwind + Sass) and to copy the preline runtime.

pnpm

pnpm add -D @tailwindcss/cli @tailwindcss/forms @tailwindcss/typography \
  preline sass tailwindcss tailwindcss-animate ncp

npm

npm i -D @tailwindcss/cli @tailwindcss/forms @tailwindcss/typography \
  preline sass tailwindcss tailwindcss-animate ncp

Package	Why
tailwindcss, @tailwindcss/cli	Compiles the utility + token stylesheet (v4).
@tailwindcss/forms	Normalises native form controls.
@tailwindcss/typography	Prose styles for rich text / WYSIWYG.
tailwindcss-animate	Animation utilities used by components.
sass	Compiles the SCSS component layer to components.min.css.
preline	Bundled by the design system. You install it only so its imports resolve at build time and to copy its runtime — you never wire it into your own config.
ncp	Tiny cross-platform copy — used by the preline step below.

Pin Preline to 4.1.x

The design system’s main.css imports preline/variants.css, which 4.2.0 removed. Install [email protected] until the styles are migrated.

3. Create your stylesheet

Make one stylesheet your project owns. Import the design system’s main.css and add a @source for your markup so Tailwind scans it:

src/app.css

/* your own project styles go here… */

/* …then bring in the design system: */
@import '../design-system/style/base/main.css';

/* scan your templates/pages for classes (adjust to your layout): */
@source '../pages';

Tip

main.css already pulls in Tailwind, the plugins, the tokens, the component layer and Preline — so this one import is the whole design system. Everything above/below it in this file is yours.

4. Wire up package.json

Here is a complete package.json. The scripts are named with ui (not ds) because in a real project they build your whole UI — your styles and the design system — not just the design system. Adjust the design-system, src/app.css and public/app.css paths to your layout.

package.json

{
  "name": "my-project",
  "packageManager": "[email protected]",
  "scripts": {
    "copy:preline": "ncp node_modules/preline/preline.js design-system/assets/preline/preline.js",
    "build:ui": "pnpm copy:preline && pnpm run \"/build:ui:.+/\"",
    "build:ui:components": "sass design-system/style/base/components/components.scss design-system/style/base/components/components.min.css --no-source-map --style compressed",
    "build:ui:style": "tailwindcss -i src/app.css -o public/app.css --minify",
    "watch:ui": "pnpm copy:preline && pnpm run --parallel \"/watch:ui:.+/\"",
    "watch:ui:components": "sass design-system/style/base/components/components.scss design-system/style/base/components/components.min.css --no-source-map --style compressed --watch",
    "watch:ui:style": "tailwindcss -i src/app.css -o public/app.css --minify --watch"
  },
  "devDependencies": {
    "@tailwindcss/cli": "^4.3.2",
    "@tailwindcss/forms": "^0.5.11",
    "@tailwindcss/typography": "^0.5.20",
    "ncp": "^2.0.0",
    "preline": "4.1.3",
    "sass": "^1.101.0",
    "tailwindcss": "^4.3.2",
    "tailwindcss-animate": "^1.0.7"
  }
}

• copy:preline — copies Preline’s runtime into design-system/assets/preline/. It’s the first thing build:ui and watch:ui do, so you never call it by hand.
• build:ui:components — Sass bundles the SCSS component layer into components.min.css (which main.css imports).
• build:ui:style — Tailwind compiles your stylesheet to the file you serve (public/app.css here). That’s the CSS your pages link.
• build:ui / watch:ui — run both :components and :style together (watch runs them in parallel).

Skip the typing — copy the starter

The design system ships a ready-made design-system/package.json and design-system/pnpm-lock.yaml with exactly these scripts and dependencies (with path/to/... placeholders). If your project has no package.json yet, move both to your project root and replace the placeholders. If you already have one, just merge the scripts and devDependencies into it.

5. Compile

pnpm build:ui

While editing your UI or the design system, watch instead:

pnpm watch:ui

Next

• Vanilla setup — the plain-HTML <head> to paste.
• JSP / Gradle setup — server-rendered, with the Gradle build task.
• How the JavaScript works — the data-* model and the _defaults.js dependency.