Component Documentation Generator

Generate structured documentation for UI components across frameworks.

Overview

This skill guides the creation of component documentation by providing:

Structure templates for consistent documentation
API/Props table format compatible with TypeScript and PropTypes
Architecture diagrams using Mermaid syntax
Known issues format with severity classification
Usage examples from basic to advanced

This skill references official documentation instead of duplicating content. See external links for framework-specific details.

Prerequisites

Access to component source code
Understanding of component's purpose and usage
Optional: TypeScript types or PropTypes definitions
Optional: Existing tests or Storybook stories

Instructions

1. Identify Component Type

Before documenting, classify the component:

Type	Characteristics	Documentation Focus
Presentational	No state, receives props, renders UI	Props, variants, styling
Container	Manages state, data fetching	State flow, side effects
Composite	Combines multiple components	Internal structure, slots
Utility	Hooks, HOCs, render props	API, return values, usage patterns

Quick checklist:

Has internal state? → Document state management
Accepts children/slots? → Document composition API
Triggers events/callbacks? → Document event interface
Has side effects? → Document lifecycle and cleanup
Depends on context/providers? → Document dependencies

2. Document the API/Props

Use the standard props table format:

## Props

| Prop       | Type                          | Default     | Required | Description            |
| ---------- | ----------------------------- | ----------- | -------- | ---------------------- |
| `variant`  | `'primary' \| 'secondary'`    | `'primary'` | No       | Visual style variant   |
| `onClick`  | `(event: MouseEvent) => void` | -           | Yes      | Click handler callback |
| `children` | `ReactNode`                   | -           | Yes      | Content to render      |
| `disabled` | `boolean`                     | `false`     | No       | Disables interaction   |

For TypeScript projects, link to types:

See [ButtonProps](../types/button.ts#L12-L25) for complete type definition.

For events/callbacks:

## Events

| Event      | Payload                             | Description                |
| ---------- | ----------------------------------- | -------------------------- |
| `onChange` | `{ value: string, valid: boolean }` | Emitted on input change    |
| `onSubmit` | `FormData`                          | Emitted on form submission |

Official documentation:

3. Map Component Architecture

Document internal structure using Mermaid diagrams:

Component hierarchy:

## Architecture

`mermaid
graph TD
    A[DataTable] --> B[TableHeader]
    A --> C[TableBody]
    A --> D[TableFooter]
    C --> E[TableRow]
    E --> F[TableCell]
    A --> G[Pagination]
`

State flow (for stateful components):

## State Flow

`mermaid
stateDiagram-v2
    [*] --> Idle
    Idle --> Loading: fetch()
    Loading --> Success: data received
    Loading --> Error: request failed
    Success --> Idle: reset()
    Error --> Loading: retry()
`

Official documentation:

Mermaid: Diagram Syntax
Mermaid: Live Editor

4. Document Interactions

Describe how the component interacts with:

External dependencies:

## Dependencies

| Dependency              | Purpose               | Required |
| ----------------------- | --------------------- | -------- |
| `ThemeContext`          | Provides color tokens | Yes      |
| `useTranslation`        | i18n support          | No       |
| `@tanstack/react-query` | Data fetching         | Yes      |

Lifecycle events:

## Lifecycle

1. **Mount:** Registers event listeners, fetches initial data
2. **Update:** Re-renders on prop/state change, debounces API calls
3. **Unmount:** Cleans up listeners, cancels pending requests

5. Record Known Issues

Document limitations and edge cases:

## Known Issues

| Issue                           | Severity  | Workaround           | Status       |
| ------------------------------- | --------- | -------------------- | ------------ |
| Flickers on rapid re-render     | 🟡 Medium | Use `memo()` wrapper | Open         |
| Doesn't support RTL layout      | 🟢 Low    | Apply manual CSS     | Planned v2.1 |
| Memory leak with large datasets | 🔴 High   | Limit to 1000 items  | In Progress  |

Severity levels:

🔴 High: Causes crashes, data loss, or security issues
🟡 Medium: Degrades UX but has workaround
🟢 Low: Minor inconvenience, cosmetic issues

6. Add Usage Examples

Provide examples from basic to advanced:

## Examples

### Basic Usage

`tsx
<Button variant="primary" onClick={handleClick}>
  Click me
</Button>
`

### With Loading State

```tsx
<Button
variant="primary"
loading={isSubmitting}
disabled={!isValid}
onClick={handleSubmit}

> {isSubmitting ? 'Saving...' : 'Save'}
> </Button>
> ```

### Composition with Icons

`tsx
<Button variant="secondary">
  <Icon name="download" />
  <span>Download Report</span>
</Button>
`

For complex components, link to Storybook:

See [Storybook](https://your-storybook.com/?path=/docs/components-button) for interactive examples.

Quick Reference

Section	When to Include	Priority
Props/API	Always	🔴 Required
Examples	Always	🔴 Required
Architecture	Composite components	🟡 Recommended
State Flow	Stateful components	🟡 Recommended
Dependencies	Has external deps	🟡 Recommended
Known Issues	Has limitations	🟢 If applicable
Lifecycle	Complex side effects	🟢 If applicable

External Resources

Framework documentation:

Documentation tools:

Storybook - Interactive component documentation
JSDoc - API documentation from comments
TypeDoc - TypeScript documentation generator

Diagrams:

Mermaid - Diagrams as code
Excalidraw - Hand-drawn style diagrams

See references/templates.md for copy-paste ready templates.

create-component-docs