Getting started

Use this page as a compact adoption funnel: dependencies first, theming fundamentals, Experience System Registry setup, how resources relate, then migration when replacing legacy stacks.

Companion docs

• Installation — pnpm / npm / yarn, @source, styles, ThemeProvider
• Theming — tokens, data-ds-*, density, Tailwind variants
• Registry — components.json, REGISTRY_TOKEN, npx shadcn@latest add @by-es/...
• Skills — workflow skills + LLM reference Markdown from the registry
• Model Context Protocol (MCP) — @by/experience-system-mcp in tooling
• Migration — replacing MUI, CCL, legacy icons; by-es migrate scan

1. Installation

Add @by/experience-system and @by/icons together: icons are designed as companions to the primitives—you generally want both.

React: @by/experience-system and @by/icons support React 18 and React 19. Keep one compatible react + react-dom minor across the app so tooling and runtime stay aligned.

Detailed install commands, @source, optional style.css, and ThemeProvider placement are documented in Installation.

Dependencies & peer dependency expectations

2. Theme setup

The Experience System is Tailwind-native: typography, layout, semantic colors, and density are expressed with utilities that plug into @by/experience-system/theme.css. That stylesheet defines how raw tokens compose into palettes and scales your components already expect.

Instead of juggling large JS theme blobs everywhere, ThemeProvider applies a small set of runtime choices (color mode, spacing density, dir) as DOM attributes on a wrapper rooted in theme. Those attributes drive dark:, compact:, and related variants so visuals stay coherent while product teams tune standard / compact / ultra-compact, RTL, and Portal-driven theme payloads.

Semantic surfaces (neutral, info, success, …) attach to palette variables that activate under data-ds-color. Practical consequence: primitives look right when ThemeProvider is wired as documented—don't treat theme as “optional décor”.

2.1 Tailwind

Your app needs a stylesheet path that pulls in Tailwind @tailwind/@layer, imports theme.css in the prescribed order alongside tw-animate-css, and tells Tailwind to scan Experience System packages so class usage produces CSS (@source over node_modules/@by/experience-system and @by/icons).

Treat Installation as canonical for bundler notes. For coexistence beside legacy Material UI, use the setup-tailwind-theme-provider-skill workflow listed in the alert above.

2.2 ThemeProvider

ThemeProvider is the bridge between design tokens on the stylesheet and product-level UI state:

• color toggles light / dark and unlocks data-ds-color semantics for palettes.
• spacing (standard, compact, ultra-compact) scales density-aware spacing and typography.
• direction (ltr, rtl) flows through layout that respects horizontal reading direction.

Wrap your application (or shell root) once you are ready for Experience System primitives to own that surface so every descendent reads coherent context rather than patching attributes per subtree.

Minimal pattern:

import { ThemeProvider } from '@by/experience-system';

export default function App() {
  return (
    <ThemeProvider color="light" spacing="standard" direction="ltr">
      {/* Routed application */}
    </ThemeProvider>
  );
}

Full API philosophy and data-ds-* contract: Theming.

2.3 Portal theme consumption

Blue Yonder product UIs integrate with Portal Shell, which emits theme payloads your feature code must hydrate into ThemeProvider. ThemeProvider never reads Portal on its own—listen for ThemeResponseMessage (MessageActions.ThemeResponse), marshal themeMessage.themeObject (theme, color, spacing, direction) onto ThemeProvider, and omit legacy theme blobs shaped for abandoned stacks.

Operational guide plus skill reference: Portal theme consumption.

3. Experience System Registry setup

A design-system registry, in this stack, is a hosted catalog + metadata paired with the shadcn-style CLI. You declare the registry endpoint in components.json, then npx shadcn@latest add fetches definitions (components, docs assets, Markdown skills, references) from that endpoint and writes generated files under paths you choose in your repo. The registry does not replace npm for @by/experience-system—it is how curated BY items arrive when you want scaffolds, registry-only composites, and agent assets next to application code.

Configure the @by-es endpoint in components.json, authenticate with REGISTRY_TOKEN, then add items through npx shadcn@latest add @by-es/<item> using the upstream shadcn CLI flow. Anything you scaffold is checked into git as your source—you review it exactly like handwritten application code.

What you pull from the registry

• Components — composites and scaffolding you iterate on locally.
• Skills — task-specific Markdown workflows for agents and tooling.
• Reference items — installable Markdown references (tokens, namespaces, migrations) complementary to MCP.

Operational setup: Registry.

4. Familiarize yourself with resources

Skills vs MCP

Skills ship as narrow, task-specific instruction packs tuned for LLMs: “run Tailwind beside MUI”, “listen for themeMessage.themeObject”, “interpret migrate scan output”. They excel when you already know which job requires a scripted sequence and want repeatable Markdown an agent reads end-to-end.

MCP (@by/experience-system-mcp) behaves more like persistent Experience System intelligence plugged into Cursor, Claude Code, VS Code MCP, etc.—semantic search across component inventories, validators, governance rules, snippets. MCP keeps where primitives live, how APIs compose, how registry molecules align readily available rather than rewriting that context manually.

Neither replaces docs on this site. Use Skills for regimented narratives, MCP for exploratory building, Skills for registry listings plus copy helpers, MCP for install + tooling surface.

Components vs Registry

Primitives from @by/experience-system are atomic building blocks—you import them wholesale from npm and iterate through package releases.

Registry components are molecules: opinionated composites that assemble those atoms for you inside your repo after scaffolding. Owning generated files unlocks customizing wiring, renaming slots, layering business logic, without forking upstream packages blindly.

Introduction depth (foundations, ownership model): Introduction.

5. Migration

Leaving Material UI, CCL, or @jda/lui-common-icon-library-mui5 is a deliberate shift—not just import swaps—from runtime theme factories (sx, styled, LuiThemeProvider) toward semantic Tailwind utilities, theme.css, ThemeProvider, and bridging Portal themeMessage.themeObject payloads.

Plan vertical slices (router/MFE bundles) rather than heroic long-lived forks. Expect dual stacks briefly: legacy providers on untouched routes while new screens mount ThemeProvider with BY primitives.

What's available

• Skills covering scans, structured reports, triage workflows, Portal bridges, incremental component migrations—instantiate them from Skills after @by-es is wired.
• CLI tooling bundled with @by/experience-system: migrate scan inventories legacy imports plus findings, migrate report rolls up aggregates for planning, and migrate codemod is still iterative / experimental.
• More automation continues to evolve—checkpoint Migration for changelog-style coverage of new tooling.

Canonical guidance, churn tables, and CLI usage: Migration.

Related

• Installation
• Theming
• Portal theme consumption
• Registry
• Skills
• Model Context Protocol (MCP)
• Introduction
• Migration