game-fe-agent/skills/dev-storybook/SKILL.md

name, description

name	description
dev-storybook	Vue 3 컴포넌트를 받아 Storybook Story 파일과 Props/Emits/슬롯 사용 가이드를 자동 생성합니다. 팀 컴포넌트 카탈로그와 재사용 진입 장벽을 낮추는 데 사용합니다. 다음 상황에서 반드시 사용하세요: - "이 컴포넌트 Story 만들어줘", "Storybook 파일 생성해줘" - "컴포넌트 사용 가이드 문서 만들어줘", "Props 문서 작성해줘" - 컴포넌트 카탈로그에 새 컴포넌트를 등록해야 할 때

Storybook Story 생성 (dev-storybook)

.vue 컴포넌트 → .stories.ts 파일 + 사용 가이드 자동 생성.

언제 사용하는가

• 컴포넌트 완성 후 Storybook에 등록할 때
• 다른 팀원이 컴포넌트를 찾고 재사용할 수 있도록 문서화할 때
• Props 변형(variant)을 시각적으로 확인해야 할 때

입력

• 대상 .vue 파일 경로
• Storybook 버전 (없으면 Storybook 8 + CSF 3 포맷 기본 적용)

---

작업 순서

Phase 1: 컴포넌트 인터페이스 파악

1. .vue 파일을 읽어 아래 항목을 추출한다.
   • Props 목록 (타입, 기본값, 설명)
   • Emits 목록
   • 슬롯 목록 (default, named)
   • 주요 상태 변형 (size, variant, disabled, loading 등)

Phase 2: Story 파일 생성 (CSF 3 포맷)

파일 위치: 컴포넌트와 동일 디렉토리 또는 stories/ 파일명: <ComponentName>.stories.ts

기본 구조

import type { Meta, StoryObj } from '@storybook/vue3'
import ComponentName from './ComponentName.vue'

const meta: Meta<typeof ComponentName> = {
  title: '<Category>/<ComponentName>',
  component: ComponentName,
  tags: ['autodocs'],
  argTypes: {
    // Props 컨트롤 정의
    variant: {
      control: 'select',
      options: ['primary', 'secondary', 'ghost'],
      description: '버튼 스타일 변형',
    },
    onClick: { action: 'clicked' },
  },
}

export default meta
type Story = StoryObj<typeof ComponentName>

필수 Story 목록

// 1. 기본 상태
export const Default: Story = {
  args: {
    // 기본값으로 렌더링
  },
}

// 2. 각 변형(variant)별 Story
export const Primary: Story = {
  args: { variant: 'primary', label: '확인' },
}

// 3. 비활성 상태
export const Disabled: Story = {
  args: { disabled: true },
}

// 4. 로딩 상태 (해당 시)
export const Loading: Story = {
  args: { isLoading: true },
}

// 5. 슬롯 사용 예시 (슬롯 있을 때)
export const WithSlot: Story = {
  render: (args) => ({
    components: { ComponentName },
    setup() { return { args } },
    template: `<ComponentName v-bind="args">슬롯 내용</ComponentName>`,
  }),
}

Phase 3: 사용 가이드 주석

각 Story에 JSDoc 주석으로 사용 목적을 설명한다:

/**
 * 기본 상태. 가장 일반적인 사용 패턴.
 * @example
 * <ComponentName label="클릭" @click="handleClick" />
 */
export const Default: Story = { ... }

Phase 4: argTypes 컨트롤 매핑

Props 타입	Storybook 컨트롤
string	text
number	number
boolean	boolean
Union 타입 ('a' | 'b')	select
Array	object
Function (emit)	action

---

출력 형식

## Story: <ComponentName>.stories.ts

### Story 목록
1. Default — 기본 상태
2. Primary — 주요 variant
3. Disabled — 비활성
4. Loading — 로딩 (해당 시)

### 코드
\`\`\`ts
[전체 stories 파일]
\`\`\`

### Storybook 실행
\`\`\`bash
npx storybook dev
\`\`\`