component-guidelines-docs

Component Guidelines Documentation Generator

This skill generates component guideline documents for the SEED Design System. It helps you write high-quality design guideline documents such as for the Action Button.

Purpose

Generate component guideline documents with a consistent structure
Automatically extract Props information linked with the Rootage YAML spec
Write detailed design principles and usage guidelines in Korean
Generate standardized image paths and component references

Usage Scenarios

When writing a guideline document for a new component for the first time
When updating the guidelines for an existing component
When adding a migration guide from V2 to V3

Workflow

1. Receive user input

Request the following information from the user:

Required information:

Component ID: 예) action-button, checkbox, badge
- This ID must be the same as the Rootage YAML file name
- /packages/rootage/components/{component-id}.yaml The file must exist

Optional information:

Documentation Type: simple or comprehensive
- simple: Includes only basic Props and Spec (e.g., checkbox, badge)
- comprehensive: Includes all sections such as Anatomy, Guidelines, Comparison, etc. (e.g., action-button)
Custom Sections (if comprehensive):
- Anatomy: Whether to include a component structure diagram
- Guidelines Topics: List of guideline topics to write
  - 예) Hierarchy, Variant Usage, Brand Color Usage, Multiple Buttons, Long Label, With Icon
- Comparison: Other components to compare (e.g., "Action Button vs Chip")
- V2 Differences: Whether to include an explanation of differences from V2

2. Read the Rootage YAML file

/packages/rootage/components/{component-id}.yaml Read the file and extract the following information:

Understanding the YAML structure:

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: { ... }

Information to extract:

Component Name: metadata.name (예: "Action Button")
Component ID: metadata.id (예: "action-button")
Available Props:
- Variants: definitionsExtract keys starting with variant= from
- Sizes: definitionsExtract keys starting with size= from
- States: definitions.base's keys (enabled, pressed, disabled, loading, etc.)
- Layout: Determine through context or convention (e.g., with text, icon only)
Slots: schema.slots's keys (root, label, icon, prefixIcon, suffixIcon, etc.)

3. Generate the Props table

Generate the Props table from the information extracted from the YAML:

## 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                                                                                   |           |

Reference example (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. Generate the document structure

Simple type document structure:

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

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

## 개요

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

### 옵션 테이블

{Props 테이블}

## 스펙

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

Comprehensive type document structure:

---
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. Image path rules

All images follow the following path pattern:

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

Image naming rules:

anatomy.webp: Component structure diagram
props-{property}.webp: Props description image
- 예) props-size.webp, props-variant.webp, props-layout.webp, props-state.webp
guidelines-{topic}-{number}.webp: Guideline image
- 예) guidelines-hierarchy-1.webp, guidelines-variant-usage-1.webp
guidelines-{topic}-{do|dont}-usage-{number}.webp: Do/Don't examples
- 예) guidelines-with-icon-do-usage-1.webp, guidelines-with-icon-dont-usage-1.webp
comparison-{component1}-vs-{component2}-{number}.webp: Comparison image
- 예) comparison-action-button-vs-chip-1.webp
differences-with-v2-{number}.webp: V2 differences image

Image preparation and conversion:

The user prepares PNG images in the /docs/public/docs/components/{component-id}/ folder

Run the following script to convert to WebP:

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

Reference the converted WebP images in the document

6. Korean writing guidelines

Tone & Voice:

Professional and clear tone
User-centered descriptions (focus on usage context rather than technical details)
Use polite language ("~합니다", "~해주세요")

Description (Frontmatter):

Clearly explain the role of the component
Concise, in 1-2 sentences
e.g., "This is a component that helps users perform a specific action."

Props descriptions:

Explain the purpose and usage scenarios of each prop
Specify the characteristics and recommended use cases by size/variant
e.g., "Small and Medium are used universally in the center of the screen, while Large is mainly used as a CTA."

Writing Guidelines:

Provide specific, practically applicable guidelines
Clearly distinguish correct usage from incorrect usage
Present design principles together with their rationale
Actively use examples and visual materials

Creating tables:

Clear headers and consistent formatting
Appropriately mix Korean and English (keep technical terms in English)

7. Component Reference

Special components available in the documentation:

<PlatformStatusTable componentId="{id}" />
- Indicate implementation status by platform
- Place at the very top of the document
<ComponentSpecBlock id="{id}" />
- Indicate the technical specifications of the component
- Place at the very bottom of the document
<DoImage src="..." alt="..." />
- Images of correct usage examples
- Always write Korean alt text
<DontImage src="..." alt="..." />
- Images of incorrect usage examples
- Always write Korean alt text

<Grid>

Container that places Do/Don't images side by side

Example:

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

8. Reference Materials

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

Best practices from the Comprehensive type documentation
Refer to the Guidelines section structure
Refer to the Korean writing style
Refer to the image usage patterns

Other component documentation:

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

9. Checklist

After generating the documentation, check the following:

Are the title and description in the Frontmatter accurate?
<PlatformStatusTable>과 <ComponentSpecBlock>Are the componentId/id of the correct?
Does the information in the Props table match the YAML file?
Do all image paths follow the standard pattern?
Are the Korean descriptions clear and consistent?
Are the Guidelines specific and applicable in practice?
Are the Do/Don't examples <Grid> properly composed with the component?
Is the overall structure of the documentation consistent?

Usage examples

Example 1: Generating Simple type documentation

User input:

Component ID: checkbox
Documentation Type: simple

Generated result:

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

<PlatformStatusTable componentId="checkbox" />

## 개요

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

### 옵션 테이블

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

## 스펙

<ComponentSpecBlock id="checkbox" />

Example 2: Generating Comprehensive type documentation