스토리북 디자인 시스템: 컴포넌트 카탈로그

pnpm dlx storybook@latest init
pnpm add -D @storybook/addon-a11y @chromatic-com/storybook

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

const config: StorybookConfig = {
  stories: ['../{components,app}/**/*.stories.@(ts|tsx|mdx)'],
  addons: [
    '@storybook/addon-essentials',
    '@storybook/addon-a11y',
    '@chromatic-com/storybook',
  ],
  framework: '@storybook/nextjs',
  docs: { autodocs: 'tag' },
};

export default config;

// stories/Tokens/Colors.mdx
import { Meta, ColorPalette, ColorItem } from '@storybook/blocks';

<Meta title="Design Tokens / Colors" />

# 색상 토큰

<ColorPalette>
  <ColorItem
    title="Brand"
    subtitle="브랜드 색상"
    colors={{
      'brand-50':  '#eef2ff',
      'brand-500': '#6366f1',
      'brand-900': '#312e81',
    }}
  />
  <ColorItem
    title="Semantic"
    subtitle="의미 색상"
    colors={{
      success: '#10b981',
      warning: '#f59e0b',
      danger:  '#ef4444',
    }}
  />
</ColorPalette>

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

const meta = {
  title: 'Components/Button',
  component: Button,
  parameters: {
    layout: 'centered',
    docs: {
      description: {
        component: '주요 액션 버튼. 4가지 variant + 3가지 size.',
      },
    },
  },
  tags: ['autodocs'],
  argTypes: {
    variant: {
      control: 'select',
      options: ['primary', 'secondary', 'danger', 'ghost'],
      description: '시각적 강도',
    },
    size: {
      control: 'radio',
      options: ['sm', 'md', 'lg'],
    },
  },
} satisfies Meta<typeof Button>;

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

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

export const AllVariants: Story = {
  render: (args) => (
    <div className="flex gap-2">
      <Button variant="primary">Primary</Button>
      <Button variant="secondary">Secondary</Button>
      <Button variant="danger">Danger</Button>
      <Button variant="ghost">Ghost</Button>
    </div>
  ),
};

export const AllSizes: Story = {
  render: () => (
    <div className="flex items-center gap-2">
      <Button size="sm">Small</Button>
      <Button size="md">Medium</Button>
      <Button size="lg">Large</Button>
    </div>
  ),
};

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

export const A11yTest: Story = {
  args: { variant: 'primary', children: '확인' },
  parameters: {
    a11y: {
      config: {
        rules: [
          { id: 'color-contrast', enabled: true },
        ],
      },
    },
  },
};

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

export const ClickTest: Story = {
  args: { variant: 'primary', children: '클릭' },
  play: async ({ canvasElement, args }) => {
    const canvas = within(canvasElement);
    const btn = canvas.getByRole('button');

    await userEvent.click(btn);
    expect(btn).toHaveFocus();
  },
};

# 자동 배포 + 스냅샷 비교
pnpm dlx chromatic --project-token=<token>


# CI/CD 통합
# .github/workflows/chromatic.yml
- name: Publish to Chromatic
  uses: chromaui/action@v1
  with:
    projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
    onlyChanged: true   # 변경된 컴포넌트만

// .storybook/preview.tsx
import type { Preview } from '@storybook/react';
import { ThemeProvider } from 'next-themes';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

const queryClient = new QueryClient();

const preview: Preview = {
  decorators: [
    (Story) => (
      <ThemeProvider attribute="class">
        <QueryClientProvider client={queryClient}>
          <Story />
        </QueryClientProvider>
      </ThemeProvider>
    ),
  ],
  globalTypes: {
    theme: {
      description: '테마',
      defaultValue: 'light',
      toolbar: {
        items: ['light', 'dark'],
      },
    },
  },
};

export default preview;