Material Component Doc

专业的 FlowGram 组件文档撰写和自动化工具

✨ The solution you've been looking for

Verified
Tested and verified by our team
7571 Stars

用于 FlowGram 物料库组件文档撰写的专用技能，提供组件文档生成、Story 创建、翻译等功能的指导和自动化支持

flowgram component-documentation material-library story-creation chinese-localization mdx technical-writing translation
Repository

See It In Action

Interactive preview & real-world examples

Live Demo
Skill Demo Animation

AI Conversation Simulator

See how users interact with this skill

User Prompt

帮我为 variable-selector 组件创建完整的文档，包括 API 表格和使用示例

Skill Processing

Analyzing request...

Agent Response

生成结构化的 MDX 文档文件，包含组件介绍、使用案例、API 参考和源码导读章节

Quick Start (3 Steps)

Get up and running in minutes

1

Install

claude-code skill install material-component-doc

claude-code skill install material-component-doc
2

Config

3

First Trigger

@material-component-doc help

Commands

CommandDescriptionRequired Args
@material-component-doc 组件文档撰写为 FlowGram 物料库组件创建完整的中英文文档，包括 API 参考、使用示例和源码解读None
@material-component-doc story-组件开发创建符合 FlowGram 规范的 Story 组件，用于文档中的交互式演示None
@material-component-doc 文档翻译和本地化将中文技术文档准确翻译为英文，保持术语一致性和格式规范None

Typical Use Cases

组件文档撰写

为 FlowGram 物料库组件创建完整的中英文文档，包括 API 参考、使用示例和源码解读

Story 组件开发

创建符合 FlowGram 规范的 Story 组件，用于文档中的交互式演示

文档翻译和本地化

将中文技术文档准确翻译为英文，保持术语一致性和格式规范

Overview

FlowGram 文档的组织结构

  • 英文文档: apps/docs/src/en
  • 中文文档: apps/docs/src/zh
  • Story 组件: apps/docs/components/form-materials/components
  • 物料源码: packages/materials/form-materials/src/components
  • 文档模板: ./templates/material.mdx

组件物料文档撰写流程

1. 源码定位

在 packages/materials/form-materials/src/components 目录下确认物料源代码地址。

操作：

  • 使用 Glob 工具搜索物料文件
  • 确认目录结构（是否有 hooks.ts, context.tsx 等）
  • 记录导出名称和文件路径

2. 需求收集

向用户询问物料使用实例和具体需求。

收集信息：

  • 主要使用场景
  • 典型代码示例（1-2 个）
  • 特殊配置或高级用法
  • 是否需要配图

3. 功能分析

深入阅读源代码，理解物料功能。

分析要点：

  • Props 接口（类型、默认值、描述）
  • 核心功能和实现方式
  • 依赖关系（FlowGram API、其他物料、第三方库）
  • Hooks 和 Context
  • 特殊逻辑（条件渲染、副作用等）

4. Story 创建

在 apps/docs/components/form-materials/components 下创建 Story 组件（详见下方 Story 规范）。

5. 文档撰写

基于模板 ./templates/material.mdx 撰写完整文档。

文档位置：

  • 中文：apps/docs/src/zh/materials/components/{物料名称}.mdx
  • 英文：apps/docs/src/en/materials/components/{物料名称}.mdx（翻译后）

6. 质量检查

检查清单：

  • Story 组件能正常运行
  • 代码示例准确无误
  • API 表格完整
  • 依赖链接正确可访问
  • 图片路径正确
  • Mermaid 流程图语法正确
  • CLI 命令路径准确

用户确认中文文档的撰写后，再执行翻译。 用户确认中文文档的撰写后，再执行翻译。 用户确认中文文档的撰写后，再执行翻译。

Story 组件规范

参考示例: apps/docs/components/form-materials/components/variable-selector.tsx

命名规范

文件命名: kebab-case，与物料名称一致

  • ✅ variable-selector.tsx
  • ✅ dynamic-value-input.tsx
  • ❌ VariableSelector.tsx

Story 导出命名: PascalCase + “Story” 后缀

  • BasicStory - 基础使用（必需）
  • WithSchemaStory - 带 Schema 约束
  • DisabledStory - 禁用状态
  • CustomFilterStory - 自定义过滤
  • 根据物料特性命名，见名知意

代码要求

1. 懒加载导入

1// ✅ 正确
2const VariableSelector = React.lazy(() =>
3  import('@flowgram.ai/form-materials').then((module) => ({
4    default: module.VariableSelector,
5  }))
6);
7
8// ❌ 错误
9import { VariableSelector } from '@flowgram.ai/form-materials';

2. 包装组件

 1// ✅ 正确
 2export const BasicStory = () => (
 3  <FreeFormMetaStoryBuilder
 4    filterEndNode
 5    formMeta={{
 6      render: () => (
 7        <>
 8          <FormHeader />
 9          <Field<string[]> name="variable_selector">
10            {({ field }) => (
11              <VariableSelector
12                value={field.value}
13                onChange={(value) => field.onChange(value)}
14              />
15            )}
16          </Field>
17        </>
18      ),
19    }}
20  />
21);
22
23// ❌ 错误：缺少包装
24export const BasicStory = () => (
25  <VariableSelector value={[]} onChange={() => {}} />
26);

3. 类型标注

1// ✅ 正确
2<Field<string[] | undefined> name="variable_selector">
3
4// ❌ 错误
5<Field<any> name="variable_selector">

4. 语言规范

代码和注释只使用英文，无中文。

完整示例

 1/**
 2 * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
 3 * SPDX-License-Identifier: MIT
 4 */
 5
 6import React from 'react';
 7import { Field } from '@flowgram.ai/free-layout-editor';
 8import { FreeFormMetaStoryBuilder, FormHeader } from '../../free-form-meta-story-builder';
 9
10const VariableSelector = React.lazy(() =>
11  import('@flowgram.ai/form-materials').then((module) => ({
12    default: module.VariableSelector,
13  }))
14);
15
16export const BasicStory = () => (
17  <FreeFormMetaStoryBuilder
18    filterEndNode
19    formMeta={{
20      render: () => (
21        <>
22          <FormHeader />
23          <Field<string[] | undefined> name="variable_selector">
24            {({ field }) => (
25              <VariableSelector
26                value={field.value}
27                onChange={(value) => field.onChange(value)}
28              />
29            )}
30          </Field>
31        </>
32      ),
33    }}
34  />
35);
36
37export const FilterSchemaStory = () => (
38  <FreeFormMetaStoryBuilder
39    filterEndNode
40    formMeta={{
41      render: () => (
42        <>
43          <FormHeader />
44          <Field<string[] | undefined> name="variable_selector">
45            {({ field }) => (
46              <VariableSelector
47                value={field.value}
48                onChange={(value) => field.onChange(value)}
49                includeSchema={{ type: 'string' }}
50              />
51            )}
52          </Field>
53        </>
54      ),
55    }}
56  />
57);

物料文档格式

使用模板

模板文件: ./templates/material.mdx

文档必须严格按照模板格式编写，包含以下章节：

  1. Import 语句
  2. 标题和简介（带可选配图）
  3. 案例演示（基本使用 + 高级用法）
  4. API 参考（Props 表格）
  5. 源码导读（目录结构、核心实现、流程图、依赖梳理）

参考示例

关键注意事项

API 表格要求：

  • 必须包含所有公开的 Props
  • 类型使用反引号（如 `string`）
  • 描述清晰简洁
  • 多个相关类型分开列表

源码导读要求：

  • 目录结构：展示文件列表及说明
  • 核心实现：用代码片段说明关键逻辑
  • 整体流程：Mermaid 流程图（推荐）
  • 依赖梳理：分类列出 FlowGram API、其他物料、第三方库

图片处理指南

截图要求

  1. 时机: Story 组件完成后，运行 docs 站点截图
  2. 内容: 捕获物料的典型使用状态，清晰可见
  3. 格式: PNG，适当压缩

命名和存储

  • 命名: {物料名称}.png（kebab-case）
  • 存储: apps/docs/src/public/materials/{物料名称}.png
  • 引用: /materials/{物料名称}.png

在文档中使用

<br />
<div>
  <img loading="lazy" src="/materials/{物料名称}.png" alt="{物料名称} 组件" style={{ width: '50%' }} />
</div>

翻译流程

翻译时机

  • ✅ 用户明确要求翻译
  • ✅ 中文文档已经用户审核确认
  • ❌ 文档还在修改中
  • ❌ 用户未确认最终版本

翻译原则

术语一致性：

  • ComponentName → ComponentName（组件名不翻译）
  • Props、Hook、Schema 等术语保持原文

代码不翻译：

  • 所有代码块、命令、路径保持原样

链接处理：

  • 内部链接：/zh/ → /en/
  • 外部链接和 GitHub 链接：保持不变

格式保持：

  • Markdown 格式、缩进、空行完全一致

翻译检查清单

  • 标题和描述已翻译
  • 代码示例未被翻译
  • 命令和路径保持原样
  • 内部文档链接已更新
  • API 表格描述列已翻译
  • Mermaid 图中文节点已翻译
  • 术语使用一致

最佳实践

Props 提取技巧

  1. 查找 interface 或 type 定义
  2. 检查组件函数参数类型
  3. 查找 defaultProps 确认默认值
  4. 阅读 JSDoc 提取描述

依赖分析方法

  1. 查看 import 语句（直接依赖）
  2. 分析 Hook 调用（FlowGram API）
  3. 查找组件引用（其他物料）
  4. 检查 package.json（第三方库）

Mermaid 流程图建议

  1. 简洁明了，关注核心流程
  2. 使用时序图绘制

常见错误避免

❌ 直接导入物料而不使用 React.lazy ❌ API 表格遗漏 Props ❌ 依赖链接失效 ❌ 中英文混用 ❌ 路径格式错误

✅ 参考优秀示例 ✅ 仔细阅读源码 ✅ 验证所有链接 ✅ 保持语言和格式一致 ✅ 使用项目约定的路径格式

相关工具和资源

开发命令

1# 启动文档站点
2rush dev:docs
3
4# 查看修改
5git diff
6git diff --cached

关键目录

目录说明
packages/materials/form-materials/src/components物料源码
apps/docs/src/zh/materials/components中文文档
apps/docs/src/en/materials/components英文文档
apps/docs/components/form-materials/componentsStory 组件
apps/docs/src/public/materials图片资源
./templates文档模板

What Users Are Saying

Real feedback from the community

Environment Matrix

Dependencies

Node.js (FlowGram 项目要求版本)
Rush.js (monorepo 管理)
@flowgram.ai/form-materials
@flowgram.ai/free-layout-editor

Framework Support

FlowGram ✓ (required) React ✓ (required) MDX ✓ (documentation format)

Context Window

Token Usage ~5K-10K tokens for complete component documentation workflow

Security & Privacy

Information

Author
bytedance
Updated
2026-01-30
Category
cms-platforms

Related Skills

Material Component Doc

用于 FlowGram 物料库组件文档撰写的专用技能，提供组件文档生成、Story 创建、翻译等功能的指导和自动化支持

View Details →

Write Docs

Write BrowserOS feature documentation. Use when the user wants to create or update documentation for …

View Details →

Write Docs

Write BrowserOS feature documentation. Use when the user wants to create or update documentation for …

View Details →