docs-consistency-checker

Documentation Consistency Checker

Validates consistency across three documentation layers in SEED Design System.

Purpose

이 스킬은 SEED Design System의 문서 레이어 간 일관성을 검증합니다. 디자인 가이드라인, Rootage 컴포넌트 스펙, React 구현 문서가 서로 일치하는지 확인하고, 불일치하거나 누락된 부분을 찾아냅니다.

When to Use

다음 상황에서 이 스킬을 사용하세요:

1. 릴리스 전 감사: 메이저 릴리스 전 모든 컴포넌트 문서 완전성 검증
2. 새 컴포넌트 검토: 새 컴포넌트 문서 발행 전 일관성 확인
3. 문서 정리: 고아 파일(orphaned files) 및 오래된 문서 식별
4. Props 검증: 컴포넌트 Props가 Rootage 스펙과 일치하는지 확인
5. 정기 감사: 월간/분기별 문서 품질 점검

트리거 키워드: "docs consistency", "documentation audit", "validate docs", "check documentation", "pre-release validation"

Documentation Layers

Layer 1: Design Guidelines

• Path: ./docs/content/docs/components/{component-id}.mdx
• Purpose: 디자인 명세 및 사용 가이드라인
• Key Sections: Props, Anatomy, Guidelines, Spec

Layer 2: Rootage Component Spec

• Path: ./packages/rootage/components/{component-id}.yaml
• Purpose: 기술적 컴포넌트 명세
• Key Data: metadata.id, metadata.name, schema.slots, definitions

Layer 3: React Implementation Docs

• Path: ./docs/content/react/components/{component-id}.mdx
• Purpose: React API 문서 및 예시
• Key Sections: Installation, Props, Examples

Consistency Requirements

1. Component Naming Consistency

검증 항목:

• Design guidelines title ≡ Rootage metadata.name
• React docs title ≡ Design guidelines title
• 모든 문서가 동일한 대소문자와 형식 사용

예시:

# Rootage YAML
metadata:
  id: action-button
  name: Action Button

# Design Guidelines MDX
---
title: Action Button  # Must match
---

# React Docs MDX
---
title: Action Button  # Must match
---

검증 로직:

rootage.metadata.name === designDocs.title === reactDocs.title

2. Description Consistency

검증 항목:

• React docs description ≡ Design guidelines description
• 양쪽 모두 동일한 사용자 설명 제공

예시:

# Design Guidelines
description: 사용자가 특정 액션을 실행할 수 있도록 도와주는 컴포넌트입니다.

# React Docs - MUST match exactly
description: 사용자가 특정 액션을 실행할 수 있도록 도와주는 컴포넌트입니다.

검증 로직:

designDocs.description === reactDocs.description

3. Props/Variants Consistency

검증 항목:

• Design guidelines Props 테이블이 Rootage YAML definitions를 반영
• Variants, sizes, states가 YAML에서 추출한 것과 일치

검증 워크플로우:

1. Rootage YAML definitions 읽기
2. Variants (variant=), sizes (size=), states (base.*) 추출
3. Design guidelines Props 테이블과 비교
4. 불일치 또는 누락된 문서화 플래그

예시:

# Rootage defines
definitions:
  variant=brandSolid: {...}
  variant=neutralSolid: {...}
  size=medium: {...}
  size=large: {...}

# Design guidelines MUST document
| 속성    | 값                              |
| variant | brand solid, neutral solid      |  # Must match YAML
| size    | medium, large                   |  # Must match YAML

검증 로직:

extractedPropsFromYAML ⊆ documentedPropsінDesignDocs
// Documented props should cover all YAML-defined props

4. Component ID Consistency

검증 항목:

• <PlatformStatusTable componentId="X" /> ≡ Rootage metadata.id
• <ComponentSpecBlock id="X" /> ≡ Rootage metadata.id

예시:

# Design Guidelines
<PlatformStatusTable componentId="action-button" />  # Must match metadata.id
<ComponentSpecBlock id="action-button" />             # Must match metadata.id

검증 로직:

<PlatformStatusTable componentId="X" /> where X === rootage.metadata.id
<ComponentSpecBlock id="X" /> where X === rootage.metadata.id

5. Slot/Part Documentation

검증 항목:

• Design guidelines에서 Rootage schema의 주요 slots 언급
• Anatomy 섹션이 주요 아키텍처 parts 커버

예시:

# Rootage defines
schema:
  slots:
    root: {...}
    label: {...}
    icon: {...}
    prefixIcon: {...}
    suffixIcon: {...}

# Design guidelines should explain:
- Icon usage (prefixIcon, suffixIcon, icon-only layout)
- Label positioning
- Root container behavior

검증 기준:

• 모든 주요 slots가 문서에 언급되는지 확인
• Anatomy 또는 Props 섹션에서 설명 확인

6. File Existence Check

검증 항목:

• Rootage YAML 존재 → Design guidelines 존재해야 함
• Design guidelines 존재 → React docs 존재해야 함
• 고아 파일 플래그

Coverage Matrix:

Component ID | Rootage YAML | Design Docs | React Docs | Status
-------------|--------------|-------------|-----------|-------
action-button|      ✓       |      ✓      |     ✓     | Complete
checkbox     |      ✓       |      ✓      |     ✓     | Complete
new-comp     |      ✓       |      ✗      |     ✗     | Missing docs

Workflow

Step 1: Discovery

컴포넌트 인벤토리 구축:

1. Glob all Rootage YAML files: packages/rootage/components/*.yaml
2. Extract component IDs from metadata.id
3. Build component inventory

도구 사용:

// Glob to find all YAML files
const yamlFiles = await glob('packages/rootage/components/*.yaml')

// Read each file and extract metadata.id
for (const file of yamlFiles) {
  const content = await read(file)
  const yaml = parseYAML(content)
  const componentId = yaml.metadata.id
  inventory.push(componentId)
}

Step 2: Cross-Reference Check

각 컴포넌트 ID에 대해 파일 존재 확인:

For each component ID:
  1. Check existence:
     - docs/content/docs/components/{id}.mdx
     - docs/content/react/components/{id}.mdx
  2. Flag missing files

도구 사용:

for (const id of inventory) {
  const designDocsPath = `docs/content/docs/components/${id}.mdx`
  const reactDocsPath = `docs/content/react/components/${id}.mdx`

  const designExists = await fileExists(designDocsPath)
  const reactExists = await fileExists(reactDocsPath)

  if (!designExists) issues.push({ id, type: 'missing_design_docs' })
  if (!reactExists) issues.push({ id, type: 'missing_react_docs' })
}

Step 3: Content Validation

완전한 세트(YAML + Design + React)에 대해 내용 검증:

For each complete set:
  1. Read all three files
  2. Extract metadata:
     - Names (title, metadata.name)
     - Descriptions
     - Props/variants/sizes
     - Component references (componentId, id)
  3. Compare values
  4. Report inconsistencies

도구 사용:

// Read files
const yamlContent = await read(yamlPath)
const designContent = await read(designPath)
const reactContent = await read(reactPath)

// Parse frontmatter
const designFrontmatter = parseFrontmatter(designContent)
const reactFrontmatter = parseFrontmatter(reactContent)

// Compare names
if (yaml.metadata.name !== designFrontmatter.title) {
  issues.push({
    id,
    type: 'name_mismatch',
    expected: yaml.metadata.name,
    actual: designFrontmatter.title
  })
}

// Compare descriptions
if (designFrontmatter.description !== reactFrontmatter.description) {
  issues.push({
    id,
    type: 'description_mismatch',
    design: designFrontmatter.description,
    react: reactFrontmatter.description
  })
}

Step 4: Props Deep Validation

Props 상세 검증:

For each component:
  1. Parse Rootage YAML definitions
  2. Extract:
     - Variants: keys matching "variant="
     - Sizes: keys matching "size="
     - States: base.* keys
  3. Read design guidelines Props table
  4. Compare extracted vs documented
  5. Flag missing or extra props

도구 사용:

// Extract props from YAML
const definitions = yaml.data.definitions
const variants = Object.keys(definitions)
  .filter(key => key.startsWith('variant='))
  .map(key => key.replace('variant=', ''))

const sizes = Object.keys(definitions)
  .filter(key => key.startsWith('size='))
  .map(key => key.replace('size=', ''))

const states = Object.keys(definitions.base || {})

// Extract props from design docs (using Grep)
const propsTableMatch = await grep({
  pattern: '\\| variant\\s+\\|.*\\|',
  path: designPath,
  output_mode: 'content'
})

// Parse table and compare
const documentedVariants = parsePropsTable(propsTableMatch)

const missingVariants = variants.filter(v => !documentedVariants.includes(v))
if (missingVariants.length > 0) {
  issues.push({
    id,
    type: 'missing_variants',
    missing: missingVariants
  })
}

Step 5: Component ID Val