create-component-docs（创建组件文档）

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:

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:

• TypeScript: Utility Types
• React: Component Props
• Vue: Props Declaration

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

External Resources

Framework documentation:

• React: Component API Reference
• Vue: Component Basics
• Angular: Component Overview
• Web Components: MDN Web Components

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.