Storybook Development

Overview

The Openlane UI library uses Storybook for component development, testing, and documentation. Storybook provides an isolated environment to build and test components independently from your application.

Running Storybook

Storybook is set up in the apps/storybook directory of the monorepo.

Navigate to the monorepo root

cd /path/to/openlane-monorepo

Install dependencies

pnpm install

Start Storybook

cd apps/storybook
pnpm dev

Storybook will start on http://localhost:6006

Storybook Configuration

The Storybook setup uses Vite for fast builds and hot module replacement:

.storybook/main.ts

import type { StorybookConfig } from '@storybook/react-vite'

const config: StorybookConfig = {
  stories: [
    '../src/**/*.mdx',
    {
      directory: '../../../packages/ui/src',
      files: '**/*.stories.*',
    },
  ],
  addons: [
    '@storybook/addon-links',
    '@storybook/addon-a11y',
    '@storybook/addon-themes',
    '@storybook/addon-docs',
  ],
  framework: {
    name: '@storybook/react-vite',
    options: {
      builder: {
        viteConfigPath: 'vite.config.ts',
      },
    },
  },
  docs: {
    defaultName: 'Documentation',
  },
}

Installed Addons

Accessibility

@storybook/addon-a11y - Test components for accessibility issues

Theming

@storybook/addon-themes - Toggle between light and dark themes

Documentation

@storybook/addon-docs - Auto-generate component documentation

Links

@storybook/addon-links - Navigate between stories

Writing Stories

Stories are written using the Component Story Format (CSF) 3.0:

Basic Story Example

Here’s how the Button component stories are structured:

button.stories.tsx

import type { Meta, StoryObj } from '@storybook/react-vite'
import { ArrowRight, InfoIcon } from 'lucide-react'
import { Button, buttonStyles } from './button'

type ButtonVariants = keyof typeof buttonStyles.variants.variant
type ButtonSizes = keyof typeof buttonStyles.variants.size

const variants = Object.keys(buttonStyles.variants.variant) as ButtonVariants[]
const sizes = Object.keys(buttonStyles.variants.size) as ButtonSizes[]

const meta: Meta<typeof Button> = {
  title: 'Actions/Button',
  component: Button,
  parameters: {
    docs: {
      description: {
        component: 'Displays a button with multiple variants and sizes',
      },
    },
  },
  argTypes: {
    variant: {
      description: 'Defines the theme of the button',
      control: 'select',
      options: variants,
    },
    size: {
      description: 'Defines the size of the button',
      control: 'select',
      options: sizes,
    },
    loading: { control: 'boolean' },
    iconAnimated: { control: 'boolean' },
  },
} satisfies Meta<typeof Button>

export default meta
type Story = StoryObj<typeof meta>

export const Primary: Story = {
  args: {
    children: 'Primary Button',
    variant: 'primary',
  },
}

export const Secondary: Story = {
  args: {
    children: 'Secondary Button',
    variant: 'secondary',
  },
}

export const WithIcon: Story = {
  args: {
    children: 'Continue',
    variant: 'primary',
    icon: <ArrowRight />,
    iconAnimated: true,
  },
}

export const Loading: Story = {
  args: {
    children: 'Loading...',
    loading: true,
  },
}

Story Organization

Stories are organized by category:

Actions/
├── Button
├── AlertDialog
├── Dialog
└── ConfirmationDialog

Form/
├── Input
├── Textarea
├── Select
├── Checkbox
└── Switch

Data Display/
├── Table
├── DataTable
├── Badge
└── Tag

Feedback/
├── Alert
├── Toast
└── Tooltip

Interactive Controls

Storybook provides interactive controls for component props:

Text Controls
Select Controls
Boolean Controls

argTypes: {
  children: {
    control: 'text',
    description: 'Button content',
  },
  placeholder: {
    control: 'text',
  },
}

argTypes: {
  variant: {
    control: 'select',
    options: ['primary', 'secondary', 'destructive'],
  },
  size: {
    control: 'select',
    options: ['sm', 'md', 'lg'],
  },
}

argTypes: {
  loading: { control: 'boolean' },
  disabled: { control: 'boolean' },
  iconAnimated: { control: 'boolean' },
}

Testing Components

Visual Testing

Use Storybook to visually test components in isolation:

Test all variants: Create stories for each variant
Test states: Loading, disabled, error states
Test interactions: Click handlers, form submissions
Test responsive behavior: Resize viewport

Accessibility Testing

The @storybook/addon-a11y addon automatically checks for accessibility issues:

Open any story

Navigate to a component story in Storybook

Check the Accessibility tab

View accessibility violations and passes in the addon panel

Fix violations

Address any reported accessibility issues in your component

Dark Mode Testing

Test components in both light and dark modes:

Click the theme toggle in the Storybook toolbar
Switch between light, dark, and side-by-side views
Verify colors and contrast in both themes

.storybook/preview.tsx

import { withThemeByClassName } from '@storybook/addon-themes'

export const decorators = [
  withThemeByClassName({
    themes: {
      light: '',
      dark: 'dark',
    },
    defaultTheme: 'light',
  }),
]

Documentation

Storybook auto-generates documentation from your stories:

Component Description

const meta: Meta<typeof Button> = {
  title: 'Actions/Button',
  component: Button,
  parameters: {
    docs: {
      description: {
        component: 'A button component with multiple variants and states.',
      },
    },
  },
}

Prop Documentation

argTypes: {
  variant: {
    description: 'The visual style variant of the button',
    table: {
      type: { summary: 'primary | secondary | destructive' },
      defaultValue: { summary: 'primary' },
    },
  },
}

Creating New Stories

Follow these steps to create a new story:

Create the story file

Create a .stories.tsx file next to your component:

packages/ui/src/my-component/my-component.stories.tsx

Define the meta object

import type { Meta, StoryObj } from '@storybook/react-vite'
import { MyComponent } from './my-component'

const meta: Meta<typeof MyComponent> = {
  title: 'Category/MyComponent',
  component: MyComponent,
  argTypes: {
    // Define controls here
  },
} satisfies Meta<typeof MyComponent>

export default meta
type Story = StoryObj<typeof meta>

Create story variants

export const Default: Story = {
  args: {
    // Default props
  },
}

export const Variant1: Story = {
  args: {
    // Variant props
  },
}

Test in Storybook

Start Storybook and verify your new story appears:

pnpm dev

Best Practices

Create Comprehensive Stories

Cover all important variants and states:

export const Default: Story = { ... }
export const Primary: Story = { ... }
export const Secondary: Story = { ... }
export const Loading: Story = { ... }
export const Disabled: Story = { ... }
export const WithIcon: Story = { ... }
export const LongText: Story = { ... }

Use Meaningful Story Names

Story names should clearly describe what they demonstrate:

// Good
export const WithIconAndLoadingState: Story = { ... }

// Avoid
export const Story1: Story = { ... }

Document Component Behavior

Add descriptions to help users understand the component:

parameters: {
  docs: {
    description: {
      component: 'This component is used for...',
      story: 'This story demonstrates...',
    },
  },
}

Test Edge Cases

Create stories for edge cases:

export const VeryLongText: Story = {
  args: {
    children: 'Very long text that might overflow...',
  },
}

export const EmptyState: Story = {
  args: {
    data: [],
  },
}

Building Storybook

Build a static version of Storybook for deployment:

pnpm build-storybook

The static files will be generated in storybook-static/.

Available Scripts

pnpm dev
# Starts Storybook dev server on port 6006

Troubleshooting

Stories not appearing

Check that your story file matches the glob pattern in main.ts:

stories: [
  {
    directory: '../../../packages/ui/src',
    files: '**/*.stories.*',  // Must end in .stories.tsx
  },
]

Styles not loading

Ensure styles are imported in .storybook/preview.tsx:

import '@repo/ui/styles.css'

Dark mode not working

Verify the theme addon is configured:

import { withThemeByClassName } from '@storybook/addon-themes'

export const decorators = [
  withThemeByClassName({
    themes: { light: '', dark: 'dark' },
    defaultTheme: 'light',
  }),
]

Component Examples in Storybook

Here are some example components you can explore in Storybook:

Button

10+ variants including primary, secondary, loading states

Input

Variants with icons, prefixes, suffixes

Select

Form select with multiple styles

Dialog

Modal dialogs with different layouts

Table

Sortable data tables

Toast

Toast notifications with variants

Tabs

Tabbed navigation

Badge

Status badges and labels

Switch

Toggle switches

Next Steps

Component Overview

View all available components

Usage Guide

Learn how to use components

Theming

Customize component themes

Installation

Setup the component library

Getting Started

Console

Component Library

Architecture

Development

Documentation Index

​Overview

​Running Storybook

​Storybook Configuration

​Installed Addons

Accessibility

Theming

Documentation

Links

​Writing Stories

​Basic Story Example

​Story Organization

​Interactive Controls

​Testing Components

​Visual Testing

​Accessibility Testing

​Dark Mode Testing

​Documentation

​Component Description

​Prop Documentation

​Creating New Stories

​Best Practices

​Building Storybook

​Available Scripts

​Troubleshooting

​Component Examples in Storybook

Button

Input

Select

Dialog

Table

Toast

Tabs

Badge

Switch

​Next Steps

Component Overview

Usage Guide

Theming

Installation

Build docs developers (and LLMs) love

Overview

Running Storybook

Storybook Configuration

Installed Addons

Writing Stories

Basic Story Example

Story Organization

Interactive Controls

Testing Components

Visual Testing

Accessibility Testing

Dark Mode Testing

Documentation

Component Description

Prop Documentation

Creating New Stories

Best Practices

Building Storybook

Available Scripts

Troubleshooting

Component Examples in Storybook

Next Steps