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
{컴포넌트의 구조와 구성 요소 설명}
## Props
{Props 테이블}
### Size
- {Size에 대한 상세 설명}
- {각 사이즈의 용도와 사용 시나리오}
### Variant
- {Variant에 대한 상세 설명}
- {각 variant의 특징과 사용 맥락}
### Layout
- {Layout 옵션에 대한 설명}
- {각 레이아웃의 활용 방법}
### State
- {상태별 동작 설명}
### Width
- {너비 설정 옵션 설명}
## Guidelines
### {Guideline Topic 1}
{가이드라인 내용 - 표, 리스트, 이미지 등을 활용}
#### {Sub-topic}
{세부 가이드라인}
<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}
{두 컴포넌트의 차이점과 사용 시나리오}
| | {Component A} | {Component B} |
| ---------- | ----------------------------- | ----------------------------- |
| 목적 | {purpose A} | {purpose B} |
| 예시 | {examples A} | {examples B} |
| 표현 | {expression A} | {expression B} |
## Differences from V2 (선택)
- {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로 변환:
``bash bun scripts/convert-images-to-webp.ts --path "docs/public/docs/components/{component-id}/**/*.png" --delete-original ``
- 변환된 WebP 이미지를 문서에서 참조
6. 한국어 작성 가이드라인
Tone & Voice:
- 전문적이고 명확한 어조
- 사용자 중심의 설명 (기술적 세부사항보다는 사용 맥락 중심)
- 존댓말 사용 ("~합니다", "