storybook

storybook/
├── stories/                          # Component stories
│   ├── Button.stories.tsx            # Button component stories
│   ├── Input.stories.tsx             # Input component stories
│   ├── Select.stories.tsx            # Select component stories
│   ├── Dialog.stories.tsx            # Dialog component stories
│   ├── Table.stories.tsx             # Table component stories
│   └── ...                           # 50+ component stories
├── .storybook/                       # Storybook configuration
│   ├── main.ts                       # Core Storybook config
│   ├── manager.ts                    # UI/Manager customization
│   ├── preview.tsx                   # Global decorators & parameters
│   ├── test-runner.ts                # Test runner configuration
│   ├── vitest.setup.ts               # Vitest setup
│   └── utils/                        # Helper utilities
│       ├── themes.ts                 # Theme configuration
│       └── decorators.ts             # Custom decorators
├── styles/                           # Global styles
│   └── storybook.css                 # Storybook-specific styles
├── public/                           # Static assets
│   ├── images/                       # Image assets
│   └── fonts/                        # Custom fonts
├── tailwind.config.ts                # Tailwind configuration
├── vitest.config.ts                  # Vitest configuration
├── chromatic.config.json             # Chromatic configuration
└── package.json                      # Dependencies and scripts

// .storybook/utils/themes.ts
export const themes = {
  light: {
    className: "theme-light",
    name: "Light",
    colors: {
      primary: "hsl(221 83% 53%)", // Blue
      background: "hsl(0 0% 100%)",
      foreground: "hsl(222 47% 11%)"
    }
  },
  dark: {
    className: "theme-dark",
    name: "Dark",
    colors: {
      primary: "hsl(221 83% 53%)",
      background: "hsl(222 47% 11%)",
      foreground: "hsl(210 40% 98%)"
    }
  },
  corporate: {
    className: "theme-corporate",
    name: "Corporate",
    colors: {
      primary: "hsl(214 100% 25%)", // Deep Blue
      background: "hsl(0 0% 100%)",
      foreground: "hsl(222 47% 11%)"
    }
  },
  marketing: {
    className: "theme-marketing",
    name: "Marketing",
    colors: {
      primary: "hsl(336 84% 50%)", // Pink/Magenta
      background: "hsl(0 0% 100%)",
      foreground: "hsl(222 47% 11%)"
    }
  },
  admin: {
    className: "theme-admin",
    name: "Admin",
    colors: {
      primary: "hsl(0 84% 60%)", // Red
      background: "hsl(0 0% 100%)",
      foreground: "hsl(222 47% 11%)"
    }
  }
};

// .storybook/preview.tsx
import { withThemeByClassName } from "@storybook/addon-themes";
import { themes } from "./utils/themes";

export const decorators = [
  withThemeByClassName({
    themes: {
      light: themes.light.className,
      dark: themes.dark.className,
      corporate: themes.corporate.className,
      marketing: themes.marketing.className,
      admin: themes.admin.className
    },
    defaultTheme: "light"
  })
];

// stories/Button.stories.tsx
export const AllThemes: Story = {
  parameters: {
    // Test across all themes
    chromatic: {
      modes: {
        light: { theme: "light" },
        dark: { theme: "dark" },
        corporate: { theme: "corporate" },
        marketing: { theme: "marketing" },
        admin: { theme: "admin" }
      }
    }
  }
};

// .storybook/preview.tsx
export const globalTypes = {
  density: {
    description: "Spacing density",
    defaultValue: "comfortable",
    toolbar: {
      title: "Density",
      icon: "component",
      items: [
        { value: "comfortable", title: "Comfortable" },
        { value: "compact", title: "Compact" },
      ],
      dynamicTitle: true,
    },
  },
};

// Decorator to apply density class
export const decorators = [
  (Story, context) => {
    const density = context.globals.density || "comfortable";
    return (
      <div className={`density-${density}`}>
        <Story />

    );
  },
];

/* styles/storybook.css */
:root {
  /* Comfortable density (default) */
  --spacing-xs: 0.25rem;
  --spacing-sm: 0.5rem;
  --spacing-md: 1rem;
  --spacing-lg: 1.5rem;
  --spacing-xl: 2rem;
}

.density-compact {
  /* Compact density (reduced spacing) */
  --spacing-xs: 0.125rem;
  --spacing-sm: 0.25rem;
  --spacing-md: 0.5rem;
  --spacing-lg: 0.75rem;
  --spacing-xl: 1rem;
}

// stories/Button.stories.tsx
import type { Meta, StoryObj } from "@storybook/react";
import { Button } from "@repo/uni-ui";

// Meta defines component metadata
const meta: Meta<typeof Button> = {
  title: "Components/Button", // Sidebar location
  component: Button,
  tags: ["autodocs"], // Enable auto-generated docs
  parameters: {
    layout: "centered", // Story layout
  },
  argTypes: {
    variant: {
      control: "select",
      options: ["primary", "secondary", "outline", "ghost", "destructive"],
      description: "Visual style variant",
    },
    size: {
      control: "select",
      options: ["sm", "md", "lg"],
      description: "Button size",
    },
    disabled: {
      control: "boolean",
      description: "Disabled state",
    },
  },
};

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

// Each export = one story
export const Primary: Story = {
  args: {
    variant: "primary",
    children: "Primary Button",
  },
};

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

export const AllVariants: Story = {
  render: () => (
    <div className="flex gap-4">
      <Button variant="primary">Primary</Button>
      <Button variant="secondary">Secondary</Button>
      <Button variant="outline">Outline</Button>
      <Button variant="ghost">Ghost</Button>
      <Button variant="destructive">Delete</Button>

  ),
};

import { within, userEvent, expect } from "@storybook/test";

export const WithInteraction: Story = {
  args: {
    children: "Click me",
    onClick: fn() // Mock function from @storybook/test
  },
  play: async ({ args, canvasElement }) => {
    const canvas = within(canvasElement);

    // Find the button
    const button = canvas.getByRole("button");

    // Test interaction
    await userEvent.click(button);

    // Assertions
    await expect(args.onClick).toHaveBeenCalled();
    await expect(button).toHaveFocus();
  }
};

export const WithBackground: Story = {
  args: { children: "Button on background" },
  decorators: [
    (Story) => (
      <div className="p-8 bg-gray-100 rounded">
        <Story />

    ),
  ],
};

export const Documented: Story = {
  args: {
    variant: "primary",
    children: "Documented Button"
  },
  parameters: {
    docs: {
      description: {
        story: "This button demonstrates primary variant usage."
      }
    },
    a11y: {
      config: {
        rules: [
          { id: "color-contrast", enabled: true },
          { id: "button-name", enabled: true }
        ]
      }
    },
    chromatic: {
      delay: 300, // Wait 300ms before screenshot
      diffThreshold: 0.2 // 20% difference threshold
    }
  }
};

// .storybook/main.ts
import type { StorybookConfig } from "@storybook/react-vite";
import { join, dirname } from "node:path";

function getAbsolutePath(value: string): string {
  return dirname(require.resolve(join(value, "package.json")));
}

const config: StorybookConfig = {
  // Story locations
  stories: ["../stories/**/*.stories.@(ts|tsx)"],

  // Addons
  addons: [
    getAbsolutePath("@storybook/addon-essentials"),
    getAbsolutePath("@storybook/addon-a11y"),
    getAbsolutePath("@storybook/addon-themes"),
    getAbsolutePath("@storybook/addon-vitest"),
    getAbsolutePath("@chromatic-com/storybook"),
    getAbsolutePath("@storybook/addon-interactions")
  ],

  // Framework
  framework: {
    name: getAbsolutePath("@storybook/react-vite"),
    options: {}
  },

  // TypeScript
  typescript: {
    check: true,
    reactDocgen: "react-docgen-typescript",
    reactDocgenTypescriptOptions: {
      shouldExtractLiteralValuesFromEnum: true,
      propFilter: (prop) => (prop.parent ? !/node_modules/.test(prop.parent.fileName) : true)
    }
  },

  // Vite configuration
  viteFinal: async (config) => {
    return {
      ...config,
      resolve: {
        ...config.resolve,
        alias: {
          ...config.resolve?.alias,
          "@": join(__dirname, "../")
        }
      }
    };
  },

  // Static directories
  staticDirs: ["../public"],

  // Documentation
  docs: {
    autodocs: "tag" // Auto-generate docs for stories with 'autodocs' tag
  }
};

export default config;

// .storybook/preview.tsx
import type { Preview } from "@storybook/react";
import { withThemeByClassName } from "@storybook/addon-themes";
import "@repo/uni-ui/theme.css"; // Tailwind CSS 4 theme

const preview: Preview = {
  // Global parameters
  parameters: {
    // Controls
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/i,
      },
      expanded: true, // Expand controls panel by default
    },

    // Actions
    actions: {
      argTypesRegex: "^on[A-Z].*", // Auto-detect event handlers
    },

    // Backgrounds
    backgrounds: {
      default: "light",
      values: [
        { name: "light", value: "#ffffff" },
        { name: "dark", value: "#1a1a1a" },
        { name: "gray", value: "#f5f5f5" },
      ],
    },

    // Layout
    layout: "centered", // Default layout

    // Documentation
    docs: {
      toc: true, // Show table of contents
      source: {
        type: "dynamic", // Show source code
      },
    },

    // Viewport
    viewport: {
      viewports: {
        mobile: {
          name: "Mobile",
          styles: { width: "375px", height: "667px" },
        },
        tablet: {
          name: "Tablet",
          styles: { width: "768px", height: "1024px" },
        },
        desktop: {
          name: "Desktop",
          styles: { width: "1920px", height: "1080px" },
        },
      },
    },
  },

  // Global types (toolbar items)
  globalTypes: {
    theme: {
      description: "Global theme for components",
      defaultValue: "light",
      toolbar: {
        title: "Theme",
        icon: "paintbrush",
        items: [
          { value: "light", title: "Light", icon: "circlehollow" },
          { value: "dark", title: "Dark", icon: "circle" },
          { value: "corporate", title: "Corporate", icon: "diamond" },
          { value: "marketing", title: "Marketing", icon: "heart" },
          { value: "admin", title: "Admin", icon: "admin" },
        ],
        dynamicTitle: true,
      },
    },
    density: {
      description: "Spacing density",
      defaultValue: "comfortable",
      toolbar: {
        title: "Density",
        icon: "component",
        items: [
          { value: "comfortable", title: "Comfortable" },
          { value: "compact", title: "Compact" },
        ],
        dynamicTitle: true,
      },
    },
  },

  // Global decorators
  decorators: [
    // Theme decorator
    withThemeByClassName({
      themes: {
        light: "theme-light",
        dark: "theme-dark",
        corporate: "theme-corporate",
        marketing: "theme-marketing",
        admin: "theme-admin",
      },
      defaultTheme: "light",
    }),

    // Density decorator
    (Story, context) => {
      const density = context.globals.density || "comfortable";
      return (
        <div className={`density-${density}`}>
          <Story />

      );
    },
  ],
};

export default preview;

// .storybook/manager.ts
import { addons } from "@storybook/manager-api";
import { themes } from "@storybook/theming";

addons.setConfig({
  theme: themes.light,
  sidebar: {
    showRoots: true,
    collapsedRoots: ["other"]
  },
  toolbar: {
    title: { hidden: false },
    zoom: { hidden: false },
    eject: { hidden: false },
    copy: { hidden: false },
    fullscreen: { hidden: false }
  }
});

// .storybook/preview.tsx
parameters: {
  a11y: {
    // Default a11y configuration
    element: "#storybook-root",
    config: {
      rules: [
        {
          id: "color-contrast",
          enabled: true,
          reviewOnFail: true,
        },
        {
          id: "button-name",
          enabled: true,
        },
        {
          id: "label",
          enabled: true,
        },
        {
          id: "link-name",
          enabled: true,
        },
      ],
    },
    options: {
      runOnly: {
        type: "tag",
        values: ["wcag2a", "wcag2aa", "wcag21aa"],
      },
    },
  },
}

export const AccessibleButton: Story = {
  args: {
    children: "Accessible Button",
    "aria-label": "Submit form"
  },
  parameters: {
    a11y: {
      config: {
        rules: [
          // Highlight specific rules
          { id: "color-contrast", enabled: true }
        ]
      }
    }
  }
};

import { expect } from "@storybook/test";
import { axe, toHaveNoViolations } from "jest-axe";

expect.extend(toHaveNoViolations);

export const ManualA11yTest: Story = {
  play: async ({ canvasElement }) => {
    const results = await axe(canvasElement);
    expect(results).toHaveNoViolations();
  }
};

// chromatic.config.json
{
  "projectId": "your-project-id",
  "buildScriptName": "build-storybook",
  "exitZeroOnChanges": true,
  "exitOnceUploaded": true,
  "onlyChanged": true,
  "externals": ["public/**"],
  "debug": false
}

# Run Chromatic visual tests
pnpm --filter storybook chromatic

# With specific options
npx chromatic \
  --project-token=$CHROMATIC_PROJECT_TOKEN \
  --only-changed \
  --auto-accept-changes main

export const ChromaticTest: Story = {
  parameters: {
    chromatic: {
      delay: 500, // Wait 500ms before screenshot
      diffThreshold: 0.3, // 30% difference threshold
      pauseAnimationAtEnd: true, // Pause animations
      viewports: [375, 768, 1920], // Test multiple viewports
      modes: {
        light: { theme: "light" },
        dark: { theme: "dark" }
      }
    }
  }
};

export const SkipChromatic: Story = {
  parameters: {
    chromatic: { disableSnapshot: true }
  }
};

// vitest.config.ts
import { defineConfig } from "vitest/config";
import react from "@vitejs/plugin-react";

export default defineConfig({
  plugins: [react()],
  test: {
    environment: "jsdom",
    setupFiles: [".storybook/vitest.setup.ts"],
    browser: {
      enabled: true,
      name: "playwright",
      provider: "playwright",
      headless: true
    },
    coverage: {
      provider: "v8",
      reporter: ["text", "json", "html"],
      exclude: ["**/*.stories.tsx", "**/node_modules/**"]
    }
  }
});

// .storybook/test-runner.ts
import type { TestRunnerConfig } from "@storybook/test-runner";

const config: TestRunnerConfig = {
  async postVisit(page, context) {
    // Run accessibility tests
    const elementHandler = await page.$("#storybook-root");
    const innerHTML = await elementHandler?.innerHTML();
    expect(innerHTML).toBeTruthy();
  }
};

export default config;

# Run interaction tests
pnpm --filter storybook test-storybook

# Run with coverage
pnpm --filter storybook coverage:collect

# Run specific story
pnpm --filter storybook test-storybook --stories-filter="Button/*"

# Storybook Server
STORYBOOK_PORT=3700

# Chromatic
CHROMATIC_PROJECT_TOKEN="chpt_..."
CHROMATIC_APP_CODE="..."

# Feature Flags
NEXT_PUBLIC_ENABLE_STORYBOOK_PREVIEW="true"

{
  "scripts": {
    "dev": "storybook dev -p 3700",
    "build": "storybook build",
    "build-storybook": "storybook build",
    "preview": "http-server storybook-static -p 3700",
    "test-storybook": "test-storybook",
    "coverage:collect": "test-storybook --coverage",
    "chromatic": "chromatic --exit-zero-on-changes",
    "lint": "eslint stories/**/*.tsx",
    "typecheck": "tsc --noEmit"
  }
}

# Build Storybook for deployment
pnpm --filter storybook build

# Output directory: storybook-static/
# Can be deployed to any static hosting

# Deploy to Chromatic
npx chromatic --project-token=$CHROMATIC_PROJECT_TOKEN

# Output:
# ✔ Storybook published to https://your-project.chromatic.com
# ✔ Visual tests passed: 0 changes detected

# Deploy to Cloudflare Pages
pnpm --filter storybook build
wrangler pages deploy storybook-static --project-name=storybook

# Deploy to Vercel
pnpm --filter storybook build
vercel --prod storybook-static

stories/
├── Components/           # UI components
│   ├── Button.stories.tsx
│   ├── Input.stories.tsx
│   └── ...
├── Forms/                # Form components
│   ├── FormField.stories.tsx
│   ├── FormLabel.stories.tsx
│   └── ...
├── Layout/               # Layout components
│   ├── Container.stories.tsx
│   ├── Grid.stories.tsx
│   └── ...
└── Examples/             # Full page examples
    ├── LoginPage.stories.tsx
    └── DashboardPage.stories.tsx

// Add JSDoc comments for auto-generated docs
export interface ButtonProps {
  /** Visual style variant */
  variant?: "primary" | "secondary" | "outline";

  /** Button size */
  size?: "sm" | "md" | "lg";

  /** Disabled state */
  disabled?: boolean;

  /** Click handler */
  onClick?: () => void;
}

// Test user interactions comprehensively
export const CompleteInteraction: Story = {
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);

    // 1. Find elements
    const input = canvas.getByRole("textbox");
    const button = canvas.getByRole("button");

    // 2. Perform actions
    await userEvent.type(input, "test@example.com");
    await userEvent.click(button);

    // 3. Assert results
    await expect(input).toHaveValue("test@example.com");
    await expect(button).toBeDisabled();
  }
};

pnpm --filter storybook clean
rm -rf node_modules/.cache
pnpm --filter storybook dev

// .storybook/preview.tsx
import { withThemeByClassName } from "@storybook/addon-themes";

export const decorators = [
  withThemeByClassName({
    themes: {
      light: "theme-light",
      dark: "theme-dark"
    },
    defaultTheme: "light"
  })
];

export const Story: Story = {
  parameters: {
    chromatic: {
      delay: 1000, // Wait 1s for animations
      diffThreshold: 0.5 // Increase threshold to 50%
    }
  }
};

<Button
  aria-label="Submit form" // Add ARIA label
  className="bg-blue-600 text-white" // Ensure sufficient contrast
>
  Submit
</Button>