Storybook Integration

nib storybook init wires your brand tokens into Storybook — adding the design token panel, light/dark theme switching, and [data-theme] decorator — so every story renders in your exact brand colors out of the box.

---

Before and After

Before: Your Storybook and your design tokens are two separate worlds. You hardcode hex values in stories, manually theme controls don't match the tokens in your CSS, and every time the brand changes you update both places.

After: Run one command. nib patches your Storybook config to import variables.css, registers a [data-theme] decorator for light/dark switching, adds the design token panel, and writes a DesignTokens.mdx doc page — all idempotent, safe to re-run.

---

Quick Start

# Set up Storybook with nib brand tokens
nib storybook init

# Confirm brand tokens are annotated for the panel
# In .nib/brand.config.json, set:
# "storybook": { "annotations": true }

# Rebuild CSS with annotations
nib brand build

---

Prerequisites

Before running nib storybook init:

1. Brand tokens must exist — run nib brand init first if you haven't already
2. CSS must be built — docs/design/system/build/css/variables.css must exist (run nib brand build)
3. Storybook must be installed — nib detects and patches an existing Storybook config

No Storybook yet?

Install it first:

npx storybook@latest init

Then run nib storybook init to layer in brand tokens.

---

What Gets Created

nib creates or patches exactly four files:

File	Action	What it does
.storybook/main.ts	Create or patch	Adds @storybook/addon-themes, storybook-design-token, and staticDirs entry for variables.css
.storybook/preview.ts	Create or patch	Imports variables.css, registers the theme decorator
.storybook/nib-theme-decorator.ts	Always create	Sets [data-theme="light"/"dark"] on the story root — matches your CSS [data-theme] selector
src/stories/DesignTokens.mdx	Create if absent	Design token panel page with all brand token categories

All operations are idempotent. Running nib storybook init twice is safe.

---

Design Token Panel

The design token panel shows every CSS variable from variables.css grouped by category — color, typography, spacing, radius, elevation, and more.

To enable it, set "annotations": true in .nib/brand.config.json:

{
  "storybook": {
    "annotations": true
  }
}

Then rebuild:

nib brand build

nib injects @tokens and @presenter comments into variables.css that the storybook-design-token addon reads. The token panel will appear in the Storybook Addons panel.

---

Theme Switching

The nib theme decorator sets data-theme="light" or data-theme="dark" on the Storybook story root. Your CSS already uses [data-theme="dark"] selectors for dark mode overrides (generated by nib brand build), so switching themes in Storybook previews the real dark mode — no extra work needed.

The toolbar theme switcher appears automatically when @storybook/addon-themes is installed. nib recommends the correct version for your Storybook major version:

Storybook version	@storybook/addon-themes	storybook-design-token
10.x	latest	^5
9.x	latest	^4
8.x	latest	^2.9

nib prints the exact npm install / pnpm add / yarn add command to run after nib storybook init.

---

Framework Detection

nib reads package.json to detect your framework and generate matching story file imports:

Dependency	Detected as	Import source
react	react	@storybook/react-vite
vue	vue3	@storybook/vue3-vite
svelte	svelte	@storybook/svelte-vite
lit	web-components	@storybook/web-components-vite
none detected	unknown	PLACEHOLDER comment

Override detection with nib component story Button --framework vue3.

---

Full Workflow

The intended end-to-end path from brand tokens to documented components:

# 1. Generate brand tokens
nib brand init --from brand.md

# 2. Wire Storybook
nib storybook init

# 3. Install the addons nib recommends
npm install @storybook/addon-themes storybook-design-token

# 4. Enable the token panel and rebuild
#    Set "storybook": { "annotations": true } in .nib/brand.config.json
nib brand build

# 5. Define a component contract
nib component init Button

# 6. Generate a story scaffold
nib component story Button

# 7. Replace the PLACEHOLDER import in src/stories/Button.stories.ts
#    with your real component import

# 8. Start Storybook
npx storybook dev

---

Regenerating

nib patches are idempotent — re-running nib storybook init will not duplicate addons or imports. The nib-theme-decorator.ts file is always overwritten (it's generated, not user-editable).

When you update brand tokens, rebuild CSS to update the panel:

nib brand build   # re-annotates variables.css

No Storybook restart needed — Vite's hot-reload picks up the updated variables.css automatically.

---

Related Commands

• nib component init — Define a component contract with WAI-ARIA patterns
• nib component story — Generate a .stories.ts scaffold from a contract
• nib brand build — Regenerate CSS variables and token annotations
• nib brand validate — Validate token files and contract references before Storybook breaks