Component Guidelines Docs

Component Guidelines Documentation Generator

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

목적

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

사용 시나리오

1. 새로운 컴포넌트의 가이드라인 문서를 처음 작성할 때
2. 기존 컴포넌트의 가이드라인을 업데이트할 때
3. 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: { ... }

추출할 정보:

1. Component Name: metadata.name (예: "Action Button")
2. Component ID: metadata.id (예: "action-button")
3. Available Props:
   • Variants: definitions에서 variant= 로 시작하는 키 추출
   • Sizes: definitions에서 size= 로 시작하는 키 추출
   • States: definitions.base의 키들 (enabled, pressed, disabled, loading 등)
   • Layout: 컨텍스트나 관례를 통해 파악 (예: with text, icon only)
4. 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 차이점 이미지

이미지 준비 및 변환:

1. 사용자가 PNG 이미지를 /docs/public/docs/components/{component-id}/ 폴더에 준비
2. 다음 스크립트를 실행하여 WebP로 변환:

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

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

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

Tone & Voice:

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

Description (Frontmatter):

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

Props 설명:

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

Guidelines 작성:

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

테이블 작성:

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

7. 컴포넌트 참조

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

1. <PlatformStatusTable componentId="{id}" />

   • 플랫폼별 구현 상태 표시
   • 문서 최상단에 배치

2. <ComponentSpecBlock id="{id}" />

   • 컴포넌트의 기술 스펙 표시
   • 문서 최하단에 배치

3. <DoImage src="..." alt="..." />

   • 올바른 사용 예시 이미지
   • 반드시 한국어 alt 텍스트 작성

4. <DontImage src="..." alt="..." />

   • 잘못된 사용 예시 이미지
   • 반드시 한국어 alt 텍스트 작성

5. <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 타입 문서 생성

사용자 입력:

Component ID: action-button
Documentation Type: comprehensive
Custom Sections:
  - Anatomy: yes
  - Guidelines Topics: ["Hierarchy", "Variant Usage", "Brand Color Usage", "Multiple Buttons", "Long Label", "With Icon"]
  - Comparison: "Action Button vs Chip"
  - V2 Differences: yes

생성 결과: /docs/content/docs/components/action-button.mdx 파일 참조

도구 사용 권한

이 스킬은 다음 도구들을 사용합니다:

• Read: Rootage YAML 파일 읽기, 참조 문서 읽기
• Write: MDX 파일 생성
• Glob: 유사 컴포넌트 문서 검색
• Grep: 패턴 분석 및 정보 추출
• Bash: 이미지 변환 스크립트 실행 안내

추가 참고사항

1. YAML 파일이 없는 경우:

   • 사용자에게 YAML 파일 경로 확인 요청
   • 또는 수동으로 props 정보 입력 받기

2. 이미지 준비 안내:

   • 문서 생성 후 이미지 경로 목록을 사용자에게 제공
   • PNG→WebP 변환 명령어 안내

3. 기존 문서 업데이트:

   • 기존 문서를 먼저 읽어서 내용 보존
   • 변경이 필요한 부분만 수정

4. Guideline 작성 도움:

   • Action Button 문서의 Guidelines 섹션을 참고하여 구조와 스타일 참조
   • 디자인 원칙, 사용 시나리오, 주의사항을 포괄적으로 작성