PixelPilot component-storybook.instructions.md

Component Storybook 2026

Component file → prop extraction → story generation → interaction tests → a11y checks. Produces stories that document every design system variant and all 9 component states.

---

PREREQUISITES

# Install Storybook (if not present)
npx storybook@latest init

# Required addons
npm install -D \
  @storybook/addon-a11y \
  @storybook/addon-interactions \
  @storybook/test \
  @storybook/addon-docs \
  chromatic  # optional — visual regression

---

STEP 1 — ANALYSE THE COMPONENT

Read the component file and extract:

## Component Analysis: {ComponentName}

### Props interface
{extracted TypeScript interface or prop-types}

### Variants (from union types / enums)
{e.g., variant: 'primary' | 'secondary' | 'ghost' | 'danger'}

### States (from the 9-state law)
{which of default/hover/focus/active/loading/disabled/error/success/empty apply}

### Design tokens used
{list of CSS custom property references found in the component}

### Sub-components / composition
{e.g., Button is used inside Form, Card, etc.}

---

STEP 2 — STORYBOOK CONFIG

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

const config: StorybookConfig = {
  stories: ['../src/**/*.stories.@(ts|tsx)'],
  addons: [
    '@storybook/addon-essentials',
    '@storybook/addon-interactions',
    '@storybook/addon-a11y',
    '@storybook/addon-docs',
  ],
  framework: {
    name: '@storybook/nextjs',
    options: {},
  },
};
export default config;

// .storybook/preview.ts
import type { Preview } from '@storybook/react';
import '../src/tokens.css';   // design tokens — must be first
import '../src/globals.css';

const preview: Preview = {
  parameters: {
    controls: { matchers: { color: /(background|color)$/i, date: /Date$/i } },
    a11y: { config: { rules: [{ id: 'color-contrast', enabled: true }] } },
    backgrounds: {
      default: 'light',
      values: [
        { name: 'light', value: 'var(--bg)' },
        { name: 'dark',  value: '#0A0B0E' },
      ],
    },
  },
  globalTypes: {
    theme: {
      name: 'Theme',
      description: 'Global theme for components',
      defaultValue: 'light',
      toolbar: {
        icon: 'circlehollow',
        items: ['light', 'dark'],
        showName: true,
      },
    },
  },
  decorators: [
    (Story, context) => {
      const theme = context.globals.theme;
      document.documentElement.setAttribute('data-theme', theme);
      return <Story />;
    },
  ],
};
export default preview;