Skip to main content

Storybook

Storybook is the primary development environment for the shared design system.

It is configured inside:

packages/ui/

Storybook is used to:

  • develop components in isolation
  • preview design foundations
  • document supported component variants
  • validate component behavior
  • run browser-based story tests
  • perform accessibility checks
  • review RTL and LTR behavior
  • review light and dark themes
  • produce a static design-system build

Story organization​

The current Storybook hierarchy includes:

Foundations
Primitives
Form Controls

General-purpose controls such as Button belong to Primitives.

Form-specific elements such as inputs, selection controls, labels, and field composition belong to Form Controls.

Additional categories should be introduced only when the component inventory justifies them.

Environment controls​

Storybook provides global environment controls for theme and direction.

Theme​

Supported theme modes are:

System
Light
Dark

The design-system DOM receives only the resolved theme:

data-theme="light"
data-theme="dark"

System preference resolution belongs to the environment layer rather than individual components.

Direction​

Stories can be previewed globally in:

LTR
RTL

Components inherit document direction by default.

Stories may also set an explicit local dir when validating nested or mixed direction scenarios.

These controls allow the same component story to be reviewed without creating duplicate theme- or direction-specific stories.

Development server​

The Storybook development server runs on:

http://localhost:6006

It is included in the repository-wide development workflow:

pnpm dev

This starts the web application, documentation application, and Storybook development environment together.

For targeted Storybook development:

pnpm --filter @repo/ui dev

Browser tests​

Storybook stories participate in Vitest browser testing through Chromium.

Interaction tests use Storybook's test utilities to validate public component behavior.

Accessibility checks are configured as test failures so violations are part of the quality gate.

Production build​

The repository-wide build contract is:

pnpm build

It includes the Storybook production build together with the Web and Docs production builds.

The internal UI task is:

pnpm --filter @repo/ui build-storybook

The specialized internal task name is intentional because Storybook is not the library build artifact consumed by downstream workspaces.

The generated static output is written to:

packages/ui/storybook-static/

Generated Storybook output is ignored by Git and repository formatting tools.