用途:为 Coinbase CDS 组件在 docsite(apps/docs/)创建或更新文档。若未提供组件名,需先询问用户要记录哪个组件。
主要能力与流程:
- 检查已有文档:查看 apps/docs/docs/components/*/[ComponentName]/。已有则按需增改,避免整体重写;没有则走完整新建流程。
- 参考组件与文件:可参考 LineChart、Button、IconButton、Sidebar 的文档风格;图标名参考 packages/icons/src/IconName.ts;设计令牌参考 components.best-practices SKILL。
- 调研阶段:新建或大改前,用网络搜索参考 Material UI、Radix UI、Mantine、Ant Design、Base UI 对同类组件的文档组织、示例、边界情况与无障碍说明。
- 检查组件可用性:确认 packages/web/src/[source-category]/[ComponentName].tsx 或 packages/mobile/src/[source-category]/[ComponentName].tsx 是否存在;检查 Storybook stories,存在则在 webMetadata.json 添加 storybook 字段;检查类型定义中是否有 styles/classNames 属性,以决定是否生成样式文档。
- 新建文档的必需设置:在 apps/docs/src/components/page/ReactLiveScope.ts 添加组件导入并加入 scope;在 apps/docs/sidebars.ts 的分类 items 中加入 'components/category/ComponentName/index';在 apps/docs/docgen.config.js 的 web/mobile 分类下添加组件 source 路径。
- 目录结构:index.mdx 必需;web 版对应 webMetadata.json、_webExamples.mdx、_webPropsTable.mdx、_webStyles.mdx;mobile 版对应 mobileMetadata.json、_mobileExamples.mdx、_mobilePropsTable.mdx、_mobileStyles.mdx。
- 元数据:webMetadata.json 含 import、source、description、可选 figma/storybook、relatedComponents、可选 dependencies(须与 package.json 中 peerDependencies 版本范围一致);mobileMetadata.json 类似,figma 可选。
- Props 表:_webPropsTable.mdx 与 _mobilePropsTable.mdx 使用 ComponentPropsTable,并引入对应 docgen 数据与 sharedParentTypes、sharedTypeAliases。
- 样式文档:仅当组件支持 styles/classNames API 时创建。Web 版同时包含 StylesExplorer 交互示例与 ComponentStylesTable 选择器表;多形态组件可加多个 explorer 小节。Mobile 版仅含选择器表。示例应覆盖全部选择器,注意条件渲染、嵌套结构与真实数据。
- index.mdx:按平台使用 platform_switcher_options 区分 web-only、mobile-only 或跨平台,组合 ComponentHeader 与 ComponentTabsContainer,并按需引入 examples、props、styles 的 toc 与内容。
适用场景:CDS 组件库文档维护、新组件文档落地、文档更新与示例补充。
限制:资料未提供具体命令、安装步骤、收费与平台支持等细节;所有路径、导入与配置须以仓库实际结构为准。