Installation

Install @by/experience-system and @by/icons, add peer dependencies, wire styles and Tailwind, and wrap your app with ThemeProvider.

This article explains how to add @by/experience-system and @by/icons to an application: install both packages, satisfy peer dependencies, import styles (recommended Tailwind setup or optional precompiled CSS), and wrap the UI with ThemeProvider for theming. @by/icons is the supported BY icon set and replaces @jda/lui-common-icon-library-mui5 from the legacy CCL stack—treat it as a required companion to the experience system for new work, not an optional add-on.

Install the packages

@by/experience-system

pnpm add @by/experience-system

@by/icons

Install @by/icons alongside @by/experience-system using the same package manager. It ships namespaced SVG icon components; discovery and import paths are covered by by-icons-skill on Skills.

pnpm add @by/icons

Peer dependency: @by/icons expects react (same major as your app). You already install react for @by/experience-system—keep a single compatible version.

Available tags

@latest — Latest stable release of the library.
@next — Next pre-release of the library.

Peer dependencies

The library expects these peer dependencies in your project. Install versions compatible with your stack. The experience system supports React 18 and React 19, and requires Tailwind CSS v4 for the documented theme.css styling path documented under Tailwind Setup below:

pnpm add react react-dom tailwindcss tw-animate-css

Tailwind Setup

Production BY apps integrate Tailwind CSS v4 with theme.css: that is how tokens, dark: / compact: semantics, and component utilities resolve. Configure a single global stylesheet (see your bundler—for many apps this is index.css, globals.css, or app.css) and import layers in this order: web fonts (Calibre where used for marketing typography, Roboto Mono for font-mono), tailwindcss, @by/experience-system/theme.css, and tw-animate-css:

/* Global stylesheet (e.g. index.css, globals.css, or app.css) imported by HTML or bundler entry. */

@import url('https://fonts.googleapis.com/css2?family=Roboto+Mono:wght@300;400;500;600;700&display=swap');
@import url('https://jdaluistorybook-icons-dev.azureedge.net/fonts/calibre/fonts.css');
@import 'tailwindcss';
@import '@by/experience-system/theme.css';
@import 'tw-animate-css';

The experience system theme sets --font-mono so Tailwind’s font-mono utility resolves to Roboto Mono first (same stack as provider typography for code, kbd, and samp). If you skip the Google Fonts import, browsers fall back through the rest of the stack.

Reference that file from your HTML (for example in the <head>):

<link rel="stylesheet" href="index.css" />

Vite with the @tailwindcss/vite plugin is a common bundler setup, but other bundlers work. See the Tailwind CSS v4 installation guide for configuration details.

Watching Tailwind classes from the library

If Tailwind does not pick up classes from the package, register the package as a source in the same stylesheet (adjust the path to node_modules if your layout differs):

/* Same global stylesheet alongside the imports above */

@source "../node_modules/@by/experience-system";
@source "../node_modules/@by/icons";

Register @by/icons when you use Tailwind utilities in files that live next to generated icon output or when your build must see classes referenced from icon modules. For a full working example, see the Experience System sample MFE in this repository.

Application wrapping

ThemeProvider is required for @by/experience-system primitives to apply the correct runtime theme contract. Under the hood it renders an inner div with data-ds-theme, data-ds-color, data-ds-spacing, and dir, publishes React context (theme, color, spacing, direction, containerRef for overlays), and is what activates palette variables that depend on data-ds-color.

Wrap your application once at your shell/root (sometimes an MFE boundary) so every descendant shares one coherent density, mode, and dir model. Passing color="light" / "dark", spacing="standard" / "compact" / "ultra-compact", and direction="ltr" / "rtl" aligns Tailwind dark:, compact:, and typography with product settings. When you run inside the Portal Shell, you bridge ThemeResponseMessage (themeMessage.themeObject) into ThemeProvider—the provider does not read Portal on its own; see Portal theme consumption.

API surface, useThemeContext, token tables, and previews: Theming.

Optional: precompiled stylesheet (no Tailwind in the app)

For narrow integrations that intentionally omit Tailwind, the package also ships @by/experience-system/style.css, a precompiled stylesheet that bundles the Tailwind layers and tokens.

This can be appropriate when:

The app does not use Tailwind CSS.
You do not need to customize styling via Tailwind in the consumer.
You do not need to extend tokens or use Tailwind class names in your own code.

Replace the contents of your entry stylesheet with:

@import '@by/experience-system/style.css';

Note: Prefer Tailwind Setup above whenever you extend tokens, add utilities, tune density, or need full control. style.css is a concession for legacy or minimal hosts—not the default Experience System trajectory.

Getting started — Adoption checklist, packages, and tools
Migration — CCL/MUI → BY Experience System, preflight, and by-es migrate scan
Portal Theme Consumption — themeMessage.themeObject from the Portal Shell for ThemeProvider
Registry — Optional CLI workflow with npx / pnpx and components.json
Components — Usage and examples for UI components
Foundation — Tokens, typography, and visual foundations
Collaboration — Contributing and workflow

Installation

On this page