Add Storybook for component documentation

[jeromehardaway]

Description

Set up Storybook to document and develop UI components in isolation.

Benefits

• Visual component documentation
• Develop components in isolation
• Interactive component playground
• Test different component states
• Share components with designers
• Catch UI bugs early

Installation

Step 1: Install Storybook

npx storybook@latest init

This will:

• Install dependencies
• Add npm scripts
• Create .storybook configuration
• Add example stories

Step 2: Configure for Next.js

Update .storybook/main.ts:

import type { StorybookConfig } from '@storybook/nextjs';

const config: StorybookConfig = {
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx)'],
  addons: [
    '@storybook/addon-links',
    '@storybook/addon-essentials',
    '@storybook/addon-interactions',
    '@storybook/addon-a11y', // Accessibility testing
  ],
  framework: {
    name: '@storybook/nextjs',
    options: {},
  },
  docs: {
    autodocs: 'tag',
  },
  staticDirs: ['../public'],
};

export default config;

Step 3: Configure Preview

Update .storybook/preview.ts:

import type { Preview } from '@storybook/react';
import '../src/styles/globals.css'; // Import your global styles

const preview: Preview = {
  parameters: {
    actions: { argTypesRegex: '^on[A-Z].*' },
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/,
      },
    },
  },
};

export default preview;

Creating Stories

Button Component Story

Create src/components/ui/button/button.stories.tsx:

import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './button';

const meta: Meta<typeof Button> = {
  title: 'UI/Button',
  component: Button,
  tags: ['autodocs'],
  argTypes: {
    variant: {
      control: 'select',
      options: ['primary', 'secondary', 'outline', 'ghost', 'danger'],
    },
    size: {
      control: 'select',
      options: ['sm', 'md', 'lg'],
    },
    isLoading: {
      control: 'boolean',
    },
  },
};

export default meta;
type Story = StoryObj<typeof Button>;

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

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

export const Loading: Story = {
  args: {
    children: 'Button',
    variant: 'primary',
    isLoading: true,
  },
};

export const FullWidth: Story = {
  args: {
    children: 'Button',
    variant: 'primary',
    fullWidth: true,
  },
};

Card Component Story

import type { Meta, StoryObj } from '@storybook/react';
import { Card } from './card';

const meta: Meta<typeof Card> = {
  title: 'UI/Card',
  component: Card,
  tags: ['autodocs'],
};

export default meta;
type Story = StoryObj<typeof Card>;

export const Default: Story = {
  args: {
    title: 'Card Title',
    description: 'This is a card description',
    children: <p>Card content goes here</p>,
  },
};

export const WithImage: Story = {
  args: {
    title: 'Card with Image',
    image: '/images/example.jpg',
    description: 'Card with an image',
  },
};

Running Storybook

# Start Storybook
npm run storybook

# Build static Storybook
npm run build-storybook

Tasks

• Install Storybook with Next.js preset
• Configure Storybook for the project
• Import global styles
• Create stories for Button component
• Create stories for Card component
• Create stories for Form components
• Create stories for Modal component
• Add accessibility addon
• Add interaction testing
• Deploy Storybook (optional - Chromatic, etc.)

Components to Document (Priority Order)

1. Button
2. Input/Form fields
3. Card
4. Modal
5. Navigation
6. Loading states (Skeleton)
7. Error states
8. Empty states

Best Practices

Story Organization

src/
  components/
    ui/
      button/
        button.tsx
        button.stories.tsx  ← Story next to component
        button.test.tsx

Story Naming Convention

// Use descriptive names
export const Default: Story = {};
export const WithIcon: Story = {};
export const Loading: Story = {};
export const Disabled: Story = {};
export const FullWidth: Story = {};

Learning Outcomes

• Understanding component documentation
• Learning Storybook
• Practice with component-driven development
• Understanding design systems

Estimated Time

3-4 hours (setup + creating stories)

Additional Resources

• Storybook for Next.js
• Writing Stories
• Storybook Best Practices

Priority

Medium - Improves developer experience

Difficulty

Intermediate