name	component-guidelines-docs
description	Generate comprehensive component guideline documentation for SEED Design System. Use when creating or updating design guideline documentation in ./docs/content/docs/components directory. This skill helps create high-quality documentation similar to action-button.mdx.
allowed-tools	Read, Write, Glob, Grep, Bash

Component Guidelines Documentation Generator

이 스킬은 SEED Design System의 컴포넌트 가이드라인 문서를 생성합니다. Action Button과 같은 고품질 디자인 가이드라인 문서를 작성할 수 있도록 돕습니다.

목적

일관된 구조의 컴포넌트 가이드라인 문서 생성
Rootage YAML 스펙과 연동된 Props 정보 자동 추출
한국어 기반의 상세한 디자인 원칙과 사용 가이드 작성
표준화된 이미지 경로와 컴포넌트 참조 생성

사용 시나리오

새로운 컴포넌트의 가이드라인 문서를 처음 작성할 때
기존 컴포넌트의 가이드라인을 업데이트할 때
V2에서 V3로 마이그레이션 가이드를 추가할 때

작업 흐름

1. 사용자 입력 받기

사용자에게 다음 정보를 요청합니다:

필수 정보:

Component ID: 예) action-button, checkbox, badge
- 이 ID는 Rootage YAML 파일명과 동일해야 합니다
- /packages/rootage/components/{component-id}.yaml 파일이 존재해야 합니다

선택 정보:

Documentation Type: simple 또는 comprehensive
- simple: 기본적인 Props와 Spec만 포함 (예: checkbox, badge)
- comprehensive: Anatomy, Guidelines, Comparison 등 전체 섹션 포함 (예: action-button)
Custom Sections (comprehensive인 경우):
- Anatomy: 컴포넌트 구조도 포함 여부
- Guidelines Topics: 작성할 가이드라인 주제 목록
  - 예) Hierarchy, Variant Usage, Brand Color Usage, Multiple Buttons, Long Label, With Icon
- Comparison: 비교할 다른 컴포넌트 (예: "Action Button vs Chip")
- V2 Differences: V2와의 차이점 설명 포함 여부

2. Rootage YAML 파일 읽기

/packages/rootage/components/{component-id}.yaml 파일을 읽어서 다음 정보를 추출합니다:

YAML 구조 이해:

kind: ComponentSpec
metadata:
  id: action-button
  name: Action Button
data:
  schema:
    slots:                    # 컴포넌트의 구성 요소
      root:
        properties:
          backgroundColor: { type: color }
          borderRadius: { type: dimension }
      label:
        properties:
          color: { type: color }
          fontSize: { type: dimension }
  definitions:
    base:                     # 기본 상태별 스타일
      enabled: { ... }
      pressed: { ... }
      disabled: { ... }
    variant=brandSolid:       # variant별 스타일
      enabled: { ... }
    size=medium:              # size별 스타일
      enabled: { ... }
    variant=brandSolid, size=medium:  # 복합 조건
      enabled: { ... }

추출할 정보:

Component Name: metadata.name (예: "Action Button")
Component ID: metadata.id (예: "action-button")
Available Props:
- Variants: definitions에서 variant= 로 시작하는 키 추출
- Sizes: definitions에서 size= 로 시작하는 키 추출
- States: definitions.base의 키들 (enabled, pressed, disabled, loading 등)
- Layout: 컨텍스트나 관례를 통해 파악 (예: with text, icon only)
Slots: schema.slots의 키들 (root, label, icon, prefixIcon, suffixIcon 등)

3. Props 테이블 생성

YAML에서 추출한 정보로 Props 테이블을 생성합니다:

## Props

| 속성        | 값                                                                                     | 기본값    |
| ----------- | -------------------------------------------------------------------------------------- | --------- |
| size        | {extracted sizes}                                                           | {default} |
| variant     | {extracted variants} |           |
| layout      | {inferred or provided}                                                                   | {default} |
| disabled    | true, false                                                                            | false     |
| loading     | true, false                                                                            | false     |
| prefix icon | icon                                                                                   |           |
| suffix icon | icon                                                                                   |           |

참고 예시 (Action Button):

| 속성        | 값                                                                                     | 기본값    |
| ----------- | -------------------------------------------------------------------------------------- | --------- |
| size        | xsmall, small, medium, large                                                           | medium    |
| variant     | brand solid, neutral solid, neutral weak, critical solid, brand outline, neutral outline |           |
| layout      | with text, icon only                                                                   | with text |
| disabled    | true, false                                                                            | false     |
| loading     | true, false                                                                            | false     |
| prefix icon | icon                                                                                   |           |
| suffix icon | icon                                                                                   |           |

4. 문서 구조 생성

Simple 타입 문서 구조:

---
title: {Component Name}
description: {한국어 설명 - 컴포넌트의 역할과 목적을 1-2문장으로}
---

<PlatformStatusTable componentId="{component-id}" />

## 개요

{컴포넌트에 대한 간단한 소개}

### 옵션 테이블

{Props 테이블}

## 스펙

<ComponentSpecBlock id="{component-id}" />

Comprehensive 타입 문서 구조:

---
title: {Component Name}
description: {한국어 설명 - 컴포넌트의 역할과 목적을 1-2문장으로}
---

<PlatformStatusTable componentId="{component-id}" />

## Anatomy

![Anatomy Image](/docs/components/{component-id}/anatomy.webp)

{컴포넌트의 구조와 구성 요소 설명}

## Props

{Props 테이블}

### Size

![Size](/docs/components/{component-id}/props-size.webp)

- {Size에 대한 상세 설명}
- {각 사이즈의 용도와 사용 시나리오}

### Variant

![Variant](/docs/components/{component-id}/props-variant.webp)

- {Variant에 대한 상세 설명}
- {각 variant의 특징과 사용 맥락}

### Layout

![Layout](/docs/components/{component-id}/props-layout.webp)

- {Layout 옵션에 대한 설명}
- {각 레이아웃의 활용 방법}

### State

![State](/docs/components/{component-id}/props-state.webp)

- {상태별 동작 설명}

### Width

![Width](/docs/components/{component-id}/props-width.webp)

- {너비 설정 옵션 설명}

## Guidelines

### {Guideline Topic 1}

![Guideline Image](/docs/components/{component-id}/guidelines-{topic}-1.webp)

{가이드라인 내용 - 표, 리스트, 이미지 등을 활용}

#### {Sub-topic}

![Sub-guideline](/docs/components/{component-id}/guidelines-{topic}-{subtopic}-1.webp)

{세부 가이드라인}

<Grid>
  <DoImage src="/docs/components/{component-id}/guidelines-{topic}-do-usage-1.webp" alt="{올바른 사용 설명}" />
  <DontImage src="/docs/components/{component-id}/guidelines-{topic}-dont-usage-1.webp" alt="{잘못된 사용 설명}" />
</Grid>

### {Guideline Topic 2}

{반복...}

## Comparison (선택)

### {Component A} vs {Component B}

![Comparison](/docs/components/{component-id}/comparison-{component-a}-vs-{component-b}-1.webp)

{두 컴포넌트의 차이점과 사용 시나리오}

|    | {Component A}                        | {Component B}             |
| ---------- | -----------------------------  | ----------------------------- |
| 목적       |   {purpose A}   |  {purpose B}       |
| 예시       |  {examples A}    |    {examples B}     |
| 표현       | {expression A}     |    {expression B}     |

## Differences from V2 (선택)

![Differences from V2](/docs/components/{component-id}/differences-with-v2-1.webp)

- {V2와의 차이점 나열}
- {마이그레이션 가이드}

## Spec

<ComponentSpecBlock id="{component-id}" />

5. 이미지 경로 규칙

모든 이미지는 다음 경로 패턴을 따릅니다:

/docs/public/docs/components/{component-id}/{section-name}.webp

이미지 명명 규칙:

anatomy.webp: 컴포넌트 구조도
props-{property}.webp: Props 설명 이미지
- 예) props-size.webp, props-variant.webp, props-layout.webp, props-state.webp
guidelines-{topic}-{number}.webp: 가이드라인 이미지
- 예) guidelines-hierarchy-1.webp, guidelines-variant-usage-1.webp
guidelines-{topic}-{do|dont}-usage-{number}.webp: Do/Don't 예시
- 예) guidelines-with-icon-do-usage-1.webp, guidelines-with-icon-dont-usage-1.webp
comparison-{component1}-vs-{component2}-{number}.webp: 비교 이미지
- 예) comparison-action-button-vs-chip-1.webp
differences-with-v2-{number}.webp: V2 차이점 이미지

이미지 준비 및 변환:

사용자가 PNG 이미지를 /docs/public/docs/components/{component-id}/ 폴더에 준비

다음 스크립트를 실행하여 WebP로 변환:

bun scripts/convert-images-to-webp.ts --path "docs/public/docs/components/{component-id}/**/*.png" --delete-original

변환된 WebP 이미지를 문서에서 참조

6. 한국어 작성 가이드라인

Tone & Voice:

전문적이고 명확한 어조
사용자 중심의 설명 (기술적 세부사항보다는 사용 맥락 중심)
존댓말 사용 ("~~합니다", "~~해주세요")

Description (Frontmatter):

컴포넌트의 역할을 명확히 설명
1-2문장으로 간결하게
예) "사용자가 특정 액션을 실행할 수 있도록 도와주는 컴포넌트입니다."

Props 설명:

각 prop의 용도와 사용 시나리오 설명
사이즈별/variant별 특징과 권장 사용처 명시
예) "Small과 Medium은 화면 중앙에서 범용적으로 사용되며, Large는 주로 CTA 역할로 사용됩니다."

Guidelines 작성:

실무 적용 가능한 구체적인 가이드 제공
올바른 사용법과 잘못된 사용법을 명확히 구분
디자인 원칙과 근거를 함께 제시
예시와 시각 자료를 적극 활용

테이블 작성:

명확한 헤더와 일관된 형식
한국어와 영어를 적절히 혼용 (기술 용어는 영어 유지)

7. 컴포넌트 참조

문서에서 사용 가능한 특수 컴포넌트들:

<PlatformStatusTable componentId="{id}" />
- 플랫폼별 구현 상태 표시
- 문서 최상단에 배치
<ComponentSpecBlock id="{id}" />
- 컴포넌트의 기술 스펙 표시
- 문서 최하단에 배치
<DoImage src="..." alt="..." />
- 올바른 사용 예시 이미지
- 반드시 한국어 alt 텍스트 작성
<DontImage src="..." alt="..." />
- 잘못된 사용 예시 이미지
- 반드시 한국어 alt 텍스트 작성

<Grid>

Do/Don't 이미지를 나란히 배치하는 컨테이너

예시:

<Grid>
  <DoImage src="/path/to/do.webp" alt="올바른 사용법" />
  <DontImage src="/path/to/dont.webp" alt="잘못된 사용법" />
</Grid>

8. 참조 자료

Action Button 문서 (/docs/content/docs/components/action-button.mdx):

Comprehensive 타입 문서의 모범 사례
Guidelines 섹션 구조 참조
한국어 작성 스타일 참조
이미지 활용 패턴 참조

다른 컴포넌트 문서들:

Simple 타입: /docs/content/docs/components/checkbox.mdx, /docs/content/docs/components/badge.mdx
Comprehensive 타입: /docs/content/docs/components/action-button.mdx

9. 체크리스트

문서 생성 후 다음 사항을 확인합니다:

Frontmatter의 title과 description이 정확한가?
<PlatformStatusTable>과 <ComponentSpecBlock>의 componentId/id가 올바른가?
Props 테이블의 정보가 YAML 파일과 일치하는가?
모든 이미지 경로가 표준 패턴을 따르는가?
한국어 설명이 명확하고 일관된가?
Guidelines가 실무에 적용 가능하고 구체적인가?
Do/Don't 예시가 <Grid> 컴포넌트로 적절히 구성되었는가?
문서의 전체 구조가 일관성 있는가?

사용 예시

예시 1: Simple 타입 문서 생성

사용자 입력:

Component ID: checkbox
Documentation Type: simple

생성 결과:

---
title: Checkbox
description: 사용자가 하나 이상의 옵션을 선택할 수 있도록 하는 컴포넌트입니다.
---

<PlatformStatusTable componentId="checkbox" />

## 개요

Checkbox는 사용자가 여러 옵션 중 하나 이상을 선택할 수 있게 합니다.

### 옵션 테이블

| 속성        | 값                           | 기본값    |
| ----------- | ---------------------------- | --------- |
| size        | small, medium, large         | medium    |
| disabled    | true, false                  | false     |
| checked     | true, false                  | false     |

## 스펙

<ComponentSpecBlock id="checkbox" />

예시 2: Comprehensive 타입 문서 생성