자동 문서 생성 (Auto-Docs)

// Button.tsx
export interface ButtonProps {
  /**
   * 버튼에 표시될 텍스트
   */
  children: React.ReactNode;
  
  /**
   * 버튼의 시각적 스타일
   * @default 'primary'
   */
  variant?: 'primary' | 'secondary' | 'danger' | 'ghost';
  
  /**
   * 버튼의 크기
   * @default 'medium'
   */
  size?: 'small' | 'medium' | 'large';
  
  /**
   * 비활성화 상태 여부
   * 비활성화되면 클릭할 수 없고 시각적으로 구분됩니다.
   * @default false
   */
  disabled?: boolean;
  
  /**
   * 전체 너비를 차지할지 여부
   * @default false
   */
  fullWidth?: boolean;
  
  /**
   * 로딩 중 표시 여부
   * 로딩 중에는 자동으로 disabled 상태가 됩니다.
   * @default false
   */
  loading?: boolean;
  
  /**
   * 아이콘 (왼쪽)
   * @example <Icon name="plus" />
   */
  leftIcon?: React.ReactNode;
  
  /**
   * 아이콘 (오른쪽)
   */
  rightIcon?: React.ReactNode;
  
  /**
   * 클릭 이벤트 핸들러
   */
  onClick?: (event: React.MouseEvent<HTMLButtonElement>) => void;
  
  /**
   * 버튼 타입
   * @default 'button'
   */
  type?: 'button' | 'submit' | 'reset';
  
  /**
   * ARIA 레이블
   * 접근성을 위해 명확한 설명 제공
   */
  'aria-label'?: string;
  
  /**
   * 테스트 ID
   * @internal
   */
  testId?: string;
}

export const Button: React.FC<ButtonProps> = ({
  children,
  variant = 'primary',
  size = 'medium',
  disabled = false,
  fullWidth = false,
  loading = false,
  leftIcon,
  rightIcon,
  onClick,
  type = 'button',
  'aria-label': ariaLabel,
  testId,
}) => {
  // 구현...
};

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

/**
 * Button 컴포넌트는 사용자 액션을 트리거하는 기본 UI 요소입니다.
 * 
 * ## 사용 가이드
 * - Primary: 주요 액션 (저장, 제출 등)
 * - Secondary: 보조 액션 (취소, 뒤로 등)
 * - Danger: 위험한 액션 (삭제, 초기화 등)
 * - Ghost: 최소한의 시각적 강조
 * 
 * ## 접근성
 * - 키보드 탐색 지원 (Tab, Enter, Space)
 * - ARIA 레이블 지원
 * - 색상 대비 WCAG AA 준수
 */
const meta: Meta<typeof Button> = {
  title: 'Components/Button',
  component: Button,
  tags: ['autodocs'], // 자동 문서화 활성화
  parameters: {
    docs: {
      description: {
        component: '이 컴포넌트는 모든 플랫폼에서 일관된 버튼 경험을 제공합니다.',
      },
    },
  },
  argTypes: {
    variant: {
      control: 'select',
      description: '버튼 스타일 변형',
      table: {
        type: { summary: "'primary' | 'secondary' | 'danger' | 'ghost'" },
        defaultValue: { summary: 'primary' },
      },
    },
    size: {
      control: 'radio',
      options: ['small', 'medium', 'large'],
    },
    disabled: {
      control: 'boolean',
    },
    loading: {
      control: 'boolean',
      description: '로딩 상태일 때 spinner가 표시됩니다.',
    },
    onClick: {
      action: 'clicked',
    },
  },
};

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

/**
 * 기본 Primary 버튼입니다.
 * 가장 중요한 액션에 사용하세요.
 */
export const Primary: Story = {
  args: {
    children: 'Primary Button',
    variant: 'primary',
  },
};

/**
 * Secondary 버튼은 보조 액션에 적합합니다.
 */
export const Secondary: Story = {
  args: {
    children: 'Secondary Button',
    variant: 'secondary',
  },
};

/**
 * 삭제나 초기화 같은 위험한 액션에 사용합니다.
 */
export const Danger: Story = {
  args: {
    children: 'Delete',
    variant: 'danger',
  },
  parameters: {
    docs: {
      description: {
        story: '사용자에게 경고 메시지를 먼저 표시하는 것이 좋습니다.',
      },
    },
  },
};

/**
 * 아이콘과 함께 사용하는 예제
 */
export const WithIcons: Story = {
  args: {
    children: 'Add Item',
    leftIcon: <span>➕</span>,
  },
};

/**
 * 비동기 작업 중 로딩 상태
 */
export const Loading: Story = {
  args: {
    children: 'Loading...',
    loading: true,
  },
};