本文へ移動
cccskills
無料GitHub で公開

component-guidelines-docs

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.

Microck/ordinary-claude-skills
インストール方法を見る

含まれるファイル（2）

  • SKILL.md14.8 KB
  • metadata.json737 B

SKILL.md（原文）

インストールする前に、エージェントに与えられる指示の中身を確認できます。

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 섹션을 참고하여 구조와 스타일 참조
    • 디자인 원칙, 사용 시나리오, 주의사항을 포괄적으로 작성

レビュー

まだレビューはありません。使ってみた感想をお寄せください。

ログインしてレビューを書く

同じリポジトリのスキル

概要と使いどころ

activitypub-testing

無料

Testing patterns for PHPUnit and Playwright E2E tests. Use when writing tests, debugging test failures, setting up test coverage, or implementing test patterns for ActivityPub features.

日本語の概要は準備中です。原文の説明を表示しています。

Microck/ordinary-claude-skills4052026年9月7日 更新

adaptyv

無料

Cloud laboratory platform for automated protein testing and validation. Use when designing proteins and needing experimental validation including binding assays, expression testing, thermostability measurements, enzyme activity assays, or protein sequence optimization. Also use for submitting experiments via API, tracking experiment status, downloading results, optimizing protein sequences for better expression using computational tools (NetSolP, SoluProt, SolubleMPNN, ESM), or managing protein design workflows with wet-lab validation.

日本語の概要は準備中です。原文の説明を表示しています。

Microck/ordinary-claude-skills4052026年9月7日 更新

add-uint-support

無料

Add unsigned integer (uint) type support to PyTorch operators by updating AT_DISPATCH macros. Use when adding support for uint16, uint32, uint64 types to operators, kernels, or when user mentions enabling unsigned types, barebones unsigned types, or uint support.

日本語の概要は準備中です。原文の説明を表示しています。

Microck/ordinary-claude-skills4052026年9月7日 更新

Agent Development

無料

This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.

日本語の概要は準備中です。原文の説明を表示しています。

Microck/ordinary-claude-skills4052026年9月7日 更新

AgentDB Advanced Features

無料

Master advanced AgentDB features including QUIC synchronization, multi-database management, custom distance metrics, hybrid search, and distributed systems integration. Use when building distributed AI systems, multi-agent coordination, or advanced vector search applications.

日本語の概要は準備中です。原文の説明を表示しています。

Microck/ordinary-claude-skills4052026年9月7日 更新

AgentDB Learning Plugins

無料

Create and train AI learning plugins with AgentDB's 9 reinforcement learning algorithms. Includes Decision Transformer, Q-Learning, SARSA, Actor-Critic, and more. Use when building self-learning agents, implementing RL, or optimizing agent behavior through experience.

日本語の概要は準備中です。原文の説明を表示しています。

Microck/ordinary-claude-skills4052026年9月7日 更新

Microck のスキルをすべて見る

このスキルの問題を報告する