Next.js Storybook CSF3 스토리 생성 (nextjs-storybook-story)

Next.js Storybook CSF3 스토리 생성 (nextjs-storybook-story)은(는) 무엇을 하나요?

동일 위치에 배치된 Storybook 스토리([ComponentName].stories.tsx)를 Component Story Format 3(CSF3)으로 생성하고 업데이트하기 위한 전문 워크플로우입니다.

[!TIP] 모듈식 에셋:

• 스토리 구현 참조: examples/
• 검증 스크립트: scripts/verify-storybook.ps1 (Windows) / scripts/verify-storybook.sh (Linux)

---

아키텍처 규칙 및 표준

1. 메인 컴포넌트 범위만 (마이크로 리프 클라이언트 제외)

• 대화형 클라이언트 로직은 작은 리프 클라이언트 컴포넌트(예: 토글 버튼, 클릭 리스너)로 하향 이동됩니다.
• 내부 마이크로 리프 클라이언트 헬퍼에 대한 스토리를 생성하지 마십시오.
• 오직 메인 컴포넌트(주요 기능 섹션 또는 복합 UI 블록)에만 Storybook 스토리가 필요합니다.

2. CSF3 구조 및 대화형 컨트롤

• Meta<typeof ComponentName> 및 StoryObj<typeof ComponentName>과 함께 Component Story Format 3(CSF3)을 사용하십시오.
• 태그 포함: tags: ["autodocs", "ai-generated"].
• TypeScript Props를 meta.argTypes의 대화형 컨트롤(text, select, boolean, number)에 매핑하십시오.
• args에 현실적인 기본 prop 값을 제공하십시오.

3. 액션 스파이(storybook/test의 fn())

• 모든 콜백 및 뮤테이션 prop(예: onClick, onToggle, onSubmit)에 대해 기본 args에 'storybook/test'의 fn()을 바인딩하여 사용자 상호 작용이 Storybook Actions 패널에 깔끔하게 기록되도록 하십시오.

4. 구조화된 문서(parameters.docs)

• meta.parameters.docs.description.component에 포괄적인 마크다운을 작성하십시오:
  • 개요 및 목적: 컴포넌트가 무엇이며 왜 존재하는지.
  • 아키텍처 및 경계: RSC vs 리프 클라이언트 컴포넌트("use client"), 훅, 캐싱.
  • 주요 상호 작용: 클릭 핸들러, 상태 토글 및 애니메이션.
  • 접근성 및 모션: ARIA 역할/레이블 및 prefers-reduced-motion.
• 개별 스토리에 parameters.docs.description.story로 주석을 추가하십시오.

5. 4가지 표준 스토리 변형 및 프로덕션 토큰 (필수)

• 하드코딩된 색상 없음: 어떤 상황에서도 임의의 16진수 값(#FAFAFA, #050505)이나 비토큰 팔레트 색상(border-zinc-200, text-zinc-500)을 사용하지 마십시오.
• 의미론적 프로덕션 토큰: app/globals.css의 의미론적 테마 토큰(bg-background, text-foreground, border-border, text-muted-foreground)만 독점적으로 사용하십시오.
• 범위가 지정된 .light 및 .dark 클래스가 있는 의미론적 컨테이너 카드에 정확히 4가지 스토리 변형을 내보내십시오:
  1. Light: { themes: { themeOverride: "light" }, backgrounds: { default: "light" } }로 구성되고 "Light Mode"라고 레이블이 지정된 .light bg-background text-foreground border-border 카드에 있습니다.
  2. Dark: { themes: { themeOverride: "dark" }, backgrounds: { default: "dark" } }로 구성되고 "Dark Mode"라고 레이블이 지정된 .dark bg-background text-foreground border-border 카드에 있습니다.
  3. SkeletonLight: render: () => <[ComponentName]Skeleton />이고 "Skeleton (Light)"라고 레이블이 지정된 .light bg-background text-foreground border-border 카드에 있습니다.
  4. SkeletonDark: render: () => <[ComponentName]Skeleton />이고 "Skeleton (Dark)"라고 레이블이 지정된 .dark bg-background text-foreground border-border 카드에 있습니다.

---

워크플로우 단계

• 1단계: 컴포넌트 계약 및 Props 검사

  • [ComponentName].tsx를 읽고 내보낸 모든 props, 콜백 핸들러 및 시각적 상태를 확인합니다.

• 2단계: 동일 위치 스토리 생성 ([ComponentName].stories.tsx)

  • [ComponentName].stories.tsx를 [ComponentName].tsx와 직접적으로 동일한 위치에 배치합니다.
  • CSF3 메타데이터, argTypes, fn() 액션 스파이, 마크다운 문서 및 4가지 표준 스토리 변형을 구현합니다.

• 3단계: 검증 및 스모크 테스트 실행

  • 검증 스크립트를 실행하여 스토리 존재 여부를 확인하고 Storybook 스모크 테스트를 실행합니다:
    • Windows (PowerShell):

      pwsh .agents/skills/nextjs-storybook-story/scripts/verify-storybook.ps1 -ComponentPath <target_component_dir>
      

    • Linux / macOS (Bash):

      bash .agents/skills/nextjs-storybook-story/scripts/verify-storybook.sh <target_component_dir>
      

  • 구문 충돌이나 누락된 내보내기 오류를 수정합니다.