docs-consistency-checker

Documentation Consistency Checker

Validates consistency across three documentation layers in SEED Design System.

Purpose

This skill verifies consistency between the documentation layers of the SEED Design System. It checks whether the design guidelines, Rootage component specs, and React implementation documentation match each other, and identifies inconsistencies or missing parts.

When to Use

Use this skill in the following situations:

Pre-release audit: Verify the completeness of all component documentation before a major release
New component review: Check consistency before publishing documentation for a new component
Documentation cleanup: Identify orphaned files and outdated documentation
Props verification: Check whether component Props match the Rootage spec
Regular audit: Monthly/quarterly documentation quality check

Trigger keywords: "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: Design specifications and usage guidelines
Key Sections: Props, Anatomy, Guidelines, Spec

Layer 2: Rootage Component Spec

Path: ./packages/rootage/components/{component-id}.yaml
Purpose: Technical component specifications
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 documentation and examples
Key Sections: Installation, Props, Examples

Consistency Requirements

1. Component Naming Consistency

Verification items:

Design guidelines title ≡ Rootage metadata.name
React docs title ≡ Design guidelines title
All documentation uses the same capitalization and format

Example:

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

Verification logic:

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

2. Description Consistency

Verification items:

React docs description ≡ Design guidelines description
Both provide the same user description

Example:

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

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

Verification logic:

designDocs.description === reactDocs.description

3. Props/Variants Consistency

Verification items:

Design guidelines Props table reflects Rootage YAML definitions
Variants, sizes, and states match those extracted from the YAML

Verification workflow:

Read Rootage YAML definitions
Variants (variant=*), sizes (size=*), states (base.*) Extract
Compare with the Design guidelines Props table
Flag inconsistencies or missing documentation

Example:

# 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

Verification logic:

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

4. Component ID Consistency

Verification items:

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

Example:

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

Verification logic:

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

5. Slot/Part Documentation

Verification items:

Design guidelines mention the main slots of the Rootage schema
The Anatomy section covers the main architectural parts

Example:

# 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

Verification criteria:

Check whether all main slots are mentioned in the documentation
Check the explanation in the Anatomy or Props section

6. File Existence Check

Verification items:

Rootage YAML exists → Design guidelines must exist
Design guidelines exist → React docs must exist
Flag orphaned files

Coverage Matrix:

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

Workflow

Step 1: Discovery

Build a component inventory:

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

Use tools:

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

For each component ID, check file existence:

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

Use tools:

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

For a complete set (YAML + Design + React), verify the content:

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

Use tools:

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

Detailed Props verification:

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

Use tools:

// 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 Validation

Check component ID references in the Design guidelines:

// Check PlatformStatusTable componentId
const platformStatusMatch = await grep({
  pattern: '<PlatformStatusTable componentId="([^"]+)"',
  path: designPath,
  output_mode: 'content'
})

const extractedId = extractComponentId(platformStatusMatch)
if (extractedId !== yaml.metadata.id) {
  issues.push({
    id,
    type: 'platform_status_id_mismatch',
    expected: yaml.metadata.id,
    actual: extractedId
  })
}

// Check ComponentSpecBlock id
const specBlockMatch = await grep({
  pattern: '<ComponentSpecBlock id="([^"]+)"',
  path: designPath,
  output_mode: 'content'
})

const specId = extractComponentId(specBlockMatch)
if (specId !== yaml.metadata.id) {
  issues.push({
    id,
    type: 'spec_block_id_mismatch',
    expected: yaml.metadata.id,
    actual: specId
  })
}

Step 6: Report Generation

Generate verification results as a user-friendly report:

# Consistency Report

## Summary
- Total components: 28
- Fully consistent: 22
- Issues found: 6

## Issues

### Critical (Must Fix)
1. **badge**: Design docs missing Props table
2. **chip**: Description mismatch between design/react docs

### Warnings (Review)
1. **avatar**: Rootage defines size=xlarge but design docs don't document it
2. **callout**: ComponentSpecBlock id="callouts" (should be "callout")

### Missing Documentation
1. **divider**: Has YAML, missing design guidelines
2. **dialog**: Has YAML, missing React docs

## Recommendations
{Actionable fixes with file paths and specific changes}

Usage Scenarios

Scenario 1: Full Audit

User request:

"Run docs consistency checker on all components"

Execution process:

Search all Rootage YAML files
Run the 6 verification items for each component
Generate a comprehensive report

Scenario 2: Single Component

User request:

"Check docs consistency for action-button"

Execution process:

Validate only the action-button
Output results in Detailed mode

Scenario 3: Focus on Missing Docs

User request:

"Find components with missing documentation"

Execution process:

Run only file existence check (Step 2)
Output list of missing documents

Scenario 4: Props Validation

User request:

"Validate that all component props match Rootage specs"

Execution process:

Run only Props validation (Step 4)
Output list of mismatched props

Output Formats

Compact Mode (default)

Simple status summary:

✅ action-button - Fully consistent
⚠️  checkbox - Warning: Description differs slightly
❌ badge - Critical: Missing Props table
📋 divider - Missing: Design guidelines not found

Status icons:

✅ Fully consistent: all validations passed
⚠️ Warning: minor inconsistency, review needed
❌ Critical: important issue, immediate fix needed
📋 Missing: file missing

Detailed Mode (--verbose)

Detailed validation results:

## action-button
Status: ✅ Fully consistent

Checks performed:
- ✅ Name consistency (Action Button)
- ✅ Description matches
- ✅ Props table matches YAML (6/6 props documented)
- ✅ Component IDs correct
- ✅ All files exist

## checkbox
Status: ⚠️  Warning

Checks performed:
- ✅ Name consistency (Checkbox)
- ⚠️  Description differs:
  - Design: "사용자가 하나 이상의 옵션을 선택할 수 있게 해주는..."
  - React:  "사용자가 하나 이상의 옵션을 선택할 수 있게 해주는..."
  - Diff: Extra text in react docs
- ✅ Props table matches YAML
- ✅ Component IDs correct
- ✅ All files exist

Recommendation: Align descriptions in both files

Summary Report

Overall project status:

# SEED Design Documentation Consistency Report
Generated: 2025-01-21

## Overall Status
- Total Components: 58
- Fully Consistent: 48 (82.8%)
- With Warnings: 6 (10.3%)
- Critical Issues: 2 (3.4%)
- Missing Docs: 2 (3.4%)

## Critical Issues (Must Fix Immediately)

### 1. badge
**Issue**: Design docs missing Props table
**Impact**: Users cannot understand component options
**Fix**: Add Props table to `/docs/content/docs/components/badge.mdx`

### 2. chip
**Issue**: Description mismatch
**Details**:
- Design: "정보를 표현하고 선택을 나타내는 컴포넌트입니다."
- React: "사용자 입력을 나타내는 컴포넌트입니다."
**Fix**: Align descriptions in both files

## Warnings (Review Soon)

### 1. avatar
**Issue**: Missing variant documentation
**Details**: Rootage defines `size=xlarge` but design docs only show small, medium, large
**Fix**: Add xlarge size to Props table

### 2. callout
**Issue**: ComponentSpecBlock ID typo
**Details**: Uses `id="callouts"` but should be `id="callout"`
**Fix**: Change ComponentSpecBlock id in design docs

## Missing Documentation

### 1. divider
**Missing**: Design guidelines
**Path**: `/docs/content/docs/components/divider.mdx`
**Status**: Rootage YAML exists, React docs exist

### 2. dialog
**Missing**: React documentation
**Path**: `/docs/content/react/components/dialog.mdx`
**Status**: Rootage YAML exists, design docs exist

## Recommendations

1. **Immediate Actions** (Critical):
   - Fix badge Props table
   - Align chip descriptions

2. **This Week** (Warnings):
   - Document avatar xlarge size
   - Fix callout ComponentSpecBlock ID

3. **This Sprint** (Missing Docs):
   - Create divider design guidelines
   - Write dialog React documentation

## Next Steps

1. Assign issues to owners
2. Create tracking tasks
3. Re-run validation after fixes
4. Schedule regular monthly audits

Validation Rules

Rule 1: Exact Name Match

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

Rule 2: Exact Description Match

designDocs.description === reactDocs.description

Rule 3: Props Coverage

extractedPropsFromYAML ⊆ documentedPropsInDesignDocs
// Documented props should cover all YAML-defined props

Rule 4: Component ID Match

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

Rule 5: File Completeness

if (rootageYAML.exists()) {
  designDocs.shouldExist() // Warning if missing
  reactDocs.shouldExist()  // Info if missing (may be WIP)
}

Implementation Guidelines

Tool Usage

Read:

Parse YAML file
Extract MDX frontmatter
Check file existence

Grep:

Extract Props table
Find Component ID references
Search specific patterns

Glob:

Find all component YAML files
Generate document file list

Error Handling

try {
  const content = await read(filePath)
} catch (error) {
  if (error.code === 'ENOENT') {
    issues.push({ type: 'file_not_found', path: filePath })
  } else {
    throw error
  }
}

Performance

Parallel processing: run independent component validations in parallel
Caching: cache to avoid reading the same file multiple times
Early termination: report immediately when a Critical issue is found (optional)

Extensibility

Future Enhancements

Image path validation:
- Check existence of image files referenced in Design guidelines
- Validate whether image files are in WebP format
Example code validation:
- Check whether React examples reference the correct props
- Validate whether example code is actually executable
Accessibility check:
- Check whether Design docs mention a11y features
- Validate documentation of ARIA attributes
Localization validation:
- Check consistency of Korean descriptions
- Check translation quality

Checklist

Checklist before running validation:

Are all Rootage YAML files up to date?
Is the Git working directory clean? (no uncommitted changes)
Is the validation scope clear? (full vs specific components)
Has the output format been decided? (Compact vs Detailed)

Checklist after running validation:

Are all Critical issues documented?
Is a fix method specified for each issue?
Have the issues been registered in the tracking system?
Has an assignee been assigned?
Has the next validation schedule been planned?

Reference

Similar tools:

ESLint (code consistency checking)
Vale (document style checking)
markdownlint (Markdown rule checking)

SEED Design documentation layers:

Design Guidelines: design principles and usage guides
Rootage Spec: technical specifications and style definitions
React Docs: Implemented APIs and usage examples

Tips

Scheduled execution:
- Required execution before release
- Establish a monthly regular audit schedule
- Consider integration into the CI/CD pipeline
Incremental improvement:
- Resolve Critical issues first
- Include Warnings in sprint planning
- Add Missing docs to the backlog
Automation:
- Automatic verification on PRs with GitHub Actions
- Issue notifications via Slack/Discord
- Visualize with a Dashboard
Documentation quality:
- Passing verification is not the goal
- Clarity from the user's perspective comes first
- Consistency is the means, quality is the purpose
Team collaboration:
- Share verification results with the team
- Analyze problem patterns and improve
- Update the documentation writing guide

About this skill

Purpose

When to Use

Documentation Layers

Layer 1: Design Guidelines

Layer 2: Rootage Component Spec

Layer 3: React Implementation Docs

Consistency Requirements

1. Component Naming Consistency

2. Description Consistency

3. Props/Variants Consistency

4. Component ID Consistency

5. Slot/Part Documentation

6. File Existence Check

Workflow

Step 1: Discovery

Step 2: Cross-Reference Check

Step 3: Content Validation

Step 4: Props Deep Validation

Step 5: Component ID Validation

Step 6: Report Generation

Usage Scenarios

Scenario 1: Full Audit

Scenario 2: Single Component

Scenario 3: Focus on Missing Docs

Scenario 4: Props Validation

Output Formats

Compact Mode (default)

Detailed Mode (--verbose)

Summary Report

Validation Rules

Rule 1: Exact Name Match

Rule 2: Exact Description Match

Rule 3: Props Coverage

Rule 4: Component ID Match

Rule 5: File Completeness

Implementation Guidelines

Tool Usage

Error Handling

Performance

Extensibility

Future Enhancements

Checklist

Reference

Tips