create-component-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Component Documentation Generator

组件文档生成器

Generate structured documentation for UI components across frameworks.

为多框架下的UI组件生成结构化文档。

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.

该技能通过以下内容指导你创建组件文档：

结构化模板：确保文档风格一致
API/Props表格格式：兼容TypeScript和PropTypes
架构图：使用Mermaid语法绘制
已知问题格式：包含严重程度分级
使用示例：覆盖从基础到高级的场景

本技能会参考官方文档而非重复内容，如需框架特定细节请查看外部链接。

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

可访问组件源代码
了解组件的用途和使用方式
可选：TypeScript类型或PropTypes定义
可选：已有的测试用例或Storybook示例

Instructions

操作步骤

1. Identify Component Type

1. 确定组件类型

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

在编写文档前，先对组件进行分类：

类型	特征	文档重点
展示型	无状态、接收Props、仅负责渲染UI	Props、变体、样式
容器型	管理状态、处理数据请求	状态流转、副作用处理
复合型	由多个组件组合而成	内部结构、插槽
工具型	Hooks、HOC、渲染Props	API、返回值、使用模式

快速检查清单：

包含内部状态？→ 记录状态管理逻辑
接收子元素/插槽？→ 记录组合API
触发事件/回调？→ 记录事件接口
存在副作用？→ 记录生命周期和清理逻辑
依赖上下文/提供者？→ 记录依赖关系

2. Document the API/Props

2. 编写API/Props文档

Use the standard props table format:

markdown

undefined

使用标准的Props表格格式：

markdown

undefined

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:**

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

For events/callbacks:

markdown

undefined

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


**对于TypeScript项目，可链接到类型定义：**

```markdown
查看 [ButtonProps](../types/button.ts#L12-L25) 获取完整类型定义。

对于事件/回调：

markdown

undefined

Events

事件

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


**Official documentation:**

- TypeScript: [Utility Types](https://www.typescriptlang.org/docs/handbook/utility-types.html)
- React: [Component Props](https://react.dev/learn/passing-props-to-a-component)
- Vue: [Props Declaration](https://vuejs.org/guide/components/props.html)

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


**官方文档参考：**

- TypeScript: [Utility Types](https://www.typescriptlang.org/docs/handbook/utility-types.html)
- React: [Component Props](https://react.dev/learn/passing-props-to-a-component)
- Vue: [Props Declaration](https://vuejs.org/guide/components/props.html)

3. Map Component Architecture

3. 梳理组件架构

Document internal structure using Mermaid diagrams:

Component hierarchy:

markdown

undefined

使用Mermaid图表记录内部结构：

组件层级：

markdown

undefined

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):**

```markdown

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


**状态流转（适用于有状态组件）：**

```markdown

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](https://mermaid.js.org/intro/syntax-reference.html)
- Mermaid: [Live Editor](https://mermaid.live/)

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


**官方文档参考：**

- Mermaid: [Diagram Syntax](https://mermaid.js.org/intro/syntax-reference.html)
- Mermaid: [Live Editor](https://mermaid.live/)

4. Document Interactions

4. 记录交互逻辑

Describe how the component interacts with:

External dependencies:

markdown

undefined

描述组件与外部的交互方式：

外部依赖：

markdown

undefined

Dependencies

依赖

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


**Lifecycle events:**

```markdown

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


**生命周期：**

```markdown

Lifecycle

生命周期

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

undefined

挂载阶段： 注册事件监听器，获取初始数据
更新阶段： 因Props/状态变化重新渲染，对API调用进行防抖处理
卸载阶段： 清理监听器，取消待处理请求

undefined

5. Record Known Issues

5. 记录已知问题

Document limitations and edge cases:

markdown

undefined

记录组件的限制和边缘情况：

markdown

undefined

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

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


**严重程度分级：**

- 🔴 **高：** 导致崩溃、数据丢失或安全问题
- 🟡 **中：** 影响用户体验但有解决方案
- 🟢 **低：** 轻微不便、 cosmetic issues（界面瑕疵）

6. Add Usage Examples

6. 添加使用示例

Provide examples from basic to advanced:

markdown

undefined

提供从基础到高级的示例：

markdown

undefined

Examples

示例

Basic Usage

基础用法

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

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

```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:**

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

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


**对于复杂组件，可链接到Storybook：**

```markdown
查看 [Storybook](https://your-storybook.com/?path=/docs/components-button) 获取交互式示例。
```

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

章节	适用场景	优先级
Props/API	所有组件	🔴 必须包含
示例	所有组件	🔴 必须包含
架构	复合型组件	🟡 推荐包含
状态流转	有状态组件	🟡 推荐包含
依赖	存在外部依赖的组件	🟡 推荐包含
已知问题	存在限制的组件	🟢 按需包含
生命周期	包含复杂副作用的组件	🟢 按需包含

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.

框架官方文档：

文档工具：

Storybook - 交互式组件文档工具
JSDoc - 通过注释生成API文档
TypeDoc - TypeScript文档生成器

图表工具：

Mermaid - 代码化图表工具
Excalidraw - 手绘风格图表工具

查看 references/templates.md 获取可直接复制使用的模板。