05 — Storybook과 문서: Storybook 9 + MDX + Chromatic 시각 회귀

import type { StorybookConfig } from '@storybook/react-vite';
 
const config: StorybookConfig = {
  framework: {
    name: '@storybook/react-vite',
    options: {},
  },
  stories: [
    '../src/**/*.mdx',
    '../../packages/react/src/**/*.stories.@(ts|tsx)',
  ],
  addons: [
    '@storybook/addon-essentials',
    '@storybook/addon-a11y',
    '@storybook/addon-themes',
    '@storybook/addon-designs',          // Figma embed
    '@storybook/addon-interactions',     // play function
  ],
  docs: {
    autodocs: 'tag',                    // tags: ['autodocs'] 붙은 것만
  },
  typescript: {
    reactDocgen: 'react-docgen-typescript',
    reactDocgenTypescriptOptions: {
      shouldExtractLiteralValuesFromEnum: true,
      propFilter: (prop) =>
        !/node_modules/.test(prop.parent?.fileName ?? ''),
    },
  },
  staticDirs: ['../public'],
  viteFinal: async (config) => {
    // 토큰 CSS 자동 주입
    return config;
  },
};
 
export default config;

import type { Preview } from '@storybook/react';
import { withThemeByDataAttribute } from '@storybook/addon-themes';
import '@org/tokens/dist/css/tokens.css';
import '@org/react/styles.css';
import '../src/styles/preview.css';
 
const preview: Preview = {
  parameters: {
    layout: 'centered',
    backgrounds: { disable: true },     // theme addon에 맡김
    docs: {
      toc: { headingSelector: 'h2, h3' },
      source: { language: 'tsx' },
    },
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/i,
      },
    },
  },
  decorators: [
    withThemeByDataAttribute({
      themes: { light: 'light', dark: 'dark' },
      defaultTheme: 'light',
      attributeName: 'data-theme',
    }),
  ],
};
 
export default preview;

import type { Meta, StoryObj } from '@storybook/react';
import { expect, within, userEvent } from '@storybook/test';
import { Button } from './Button';
 
const meta = {
  title: 'Components/Button',
  component: Button,
  tags: ['autodocs'],                   // ← autodocs 활성화
  parameters: {
    design: {
      type: 'figma',
      url: 'https://www.figma.com/file/XXX/Design-System?node-id=12-34',
    },
    docs: {
      description: {
        component: `
**Button**은 사용자의 명시적 행동을 받는 인터랙티브 요소다.
\`variant\`로 의미(primary/secondary/danger)를, \`size\`로 크기를 조절한다.
        `,
      },
    },
  },
  argTypes: {
    variant: {
      control: { type: 'select' },
      options: ['primary', 'secondary', 'danger'],
      description: '버튼의 의미적 역할',
      table: { defaultValue: { summary: 'primary' } },
    },
    size: {
      control: { type: 'inline-radio' },
      options: ['sm', 'md', 'lg', 'xl'],
    },
    disabled: { control: 'boolean' },
  },
} satisfies Meta<typeof Button>;
 
export default meta;
type Story = StoryObj<typeof meta>;
 
export const Primary: Story = {
  args: { variant: 'primary', children: '저장' },
};
 
export const Sizes: Story = {
  render: () => (
    <div style={{ display: 'flex', gap: 12, alignItems: 'center' }}>
      <Button size="sm">Small</Button>
      <Button size="md">Medium</Button>
      <Button size="lg">Large</Button>
      <Button size="xl">XLarge</Button>
    </div>
  ),
};
 
export const InteractionTest: Story = {
  args: { variant: 'primary', children: '클릭' },
  play: async ({ canvasElement, args }) => {
    const canvas = within(canvasElement);
    const btn = canvas.getByRole('button', { name: '클릭' });
    await userEvent.click(btn);
    await expect(btn).toHaveAttribute('data-clicked');
  },
};

import { Canvas, Meta, ArgTypes, Source } from '@storybook/blocks';
import * as ButtonStories from './Button.stories';
 
<Meta of={ButtonStories} />
 
# Button
 
명시적 사용자 행동을 받는 컴포넌트.
 
## 언제 쓰나
 
- 폼 제출, 모달 확인, 페이지 이동 *외*의 액션
- 결과가 *즉시 발생*하는 인터랙션 (라우팅이 아니라)
 
링크가 필요하면 `<Link>`를 쓴다.
 
## Variants
 
<Canvas of={ButtonStories.Primary} />
 
## Sizes
 
<Canvas of={ButtonStories.Sizes} />
 
## Props
 
<ArgTypes of={ButtonStories.Primary} />
 
## Accessibility
 
- `role="button"`이 자동 부여
- `disabled` 시 포커스 불가, `aria-disabled` 부여
- Enter·Space로 활성화

name: Chromatic
 
on:
  push:
    branches: [main]
  pull_request:
 
jobs:
  chromatic:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
 
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20, cache: pnpm }
 
      - run: pnpm install --frozen-lockfile
      - run: pnpm turbo run build --filter=@org/react
 
      - name: Publish to Chromatic
        uses: chromaui/action@latest
        with:
          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
          workingDir: apps/docs
          buildScriptName: build-storybook
          onlyChanged: true              # turborepo와 연동
          exitZeroOnChanges: true        # PR 댓글로 처리, CI는 통과

🦋 Chromatic Build #142
✅ 0 new components
⚠️  2 stories with visual changes — review required
  - Button — Sizes
  - Dialog — Default

[Review changes](https://www.chromatic.com/build?appId=...)

// Button.stories.tsx
export const Primary: Story = {
  args: { variant: 'primary', children: '저장' },
  parameters: {
    chromatic: {
      // 폰트 로드 대기 — 한글 폰트가 늦게 그려지는 문제 회피
      delay: 300,
      // 다중 viewport
      viewports: [375, 768, 1280],
      // diff threshold (0~1)
      diffThreshold: 0.1,
    },
  },
};