| name | cloudtower-eagle-dev |
| description | Use when working on @cloudtower/eagle component library: adding or modifying components, writing JSDoc/Storybook/Markdown docs, adding data-testid for e2e testing, deprecating components, updating Props types, or auditing doc freshness. Triggers when editing files under packages/eagle/src/, or when user mentions: 写文档, 加 story, 组件废弃, 加 data-testid, testid 透传, Props 变更, 文档过时, agent 友好化, 写 JSDoc, 补充 Storybook, add component, write docs, deprecate.
|
CloudTower Eagle 组件开发指南
场景
1. 组件 Agent 友好化 / 新增组件文档
当需要给已有或新增组件编写完整的 Agent 友好文档时：
流程： 增强 JSDoc → 补充 Storybook → 编写 Markdown → 更新索引
详细步骤见 references/doc-workflow.md，文档模板见 references/doc-template.md。
2. 新增/修改组件时添加 data-testid 支持
新增组件或修改已有组件时，必须确保 data-testid 能正确透传到 e2e 工具实际交互的 DOM 元素上。
不同类型的组件需要不同的处理方式（共四层策略 + 多个补充策略）。
详细策略和代码示例见 references/add-testid.md（文件较长，开头有目录可快速定位）。
速查决策树：
- 组件是 Radio / Checkbox 等隐藏 input + label 点击的控件？→ 第一层补充（marker ref 到 label）
- 组件是基础 Input 封装（antd 有 affix-wrapper）？→ 第一层补充（ref 回调到原生 input）
- 组件渲染单一根元素且根元素就是交互目标？→ 第一层（显式透传）
- 组件有
input prop 对象（react-final-form Fields）？→ 第二层（注入 input 对象）
- 组件渲染可点击选项列表（菜单、标签页、分段控制器）？→ 第三层（选项级 testid）
- 根组件下有多个独立操作目标（button、dropdown 等）？→ 第四层（前缀 + 子元素后缀）
关键原则：
- 仅做透传，不自动生成 testid 值
- antd 会在原生元素外包裹额外 DOM 层，需要特别处理
- 改动后编写测试验证 testid 到达了正确的目标元素
3. Props 变更后同步文档
当修改了组件的 Props 类型定义后：
- 更新对应 type.ts 中的 JSDoc（属性描述、默认值、新增/移除的标注）
- 如果 Storybook 中没有覆盖新 Props 的场景，补充 Story
- 运行
yarn typings 确认类型无误
4. 废弃组件
详细步骤见 references/deprecation-workflow.md。
5. 检查文档是否过时
对比组件的 type.ts 与其 Markdown 文档，检查是否存在：
- type.ts 中有但 Markdown Props 表缺失的属性
- type.ts 中已删除但 Markdown 仍列出的属性
- JSDoc 中的
@default 与 Markdown 描述不一致
- 废弃标记不同步（type.ts 标了
@deprecated 但文档未说明）
列出差异清单，由开发者确认后再修改。
6. Typography 和 Color 的维护规则
当修改或新增 Typography、Color 相关内容时，按下面的规则处理。
Color
src/styles/token/color.ts 和 src/styles/token/color.scss 是当前和 Figma 对齐的颜色定义。src/styles/common/variables.scss 主要用来兼容旧的 Sass 变量名，不建议继续把新颜色优先加在这里。- 外部项目真正会用到的是
dist/variables.scss，所以旧的 Sass 变量名不能轻易删除或改名。
- 如果任务是“同步 / 对齐 / 更新 Color”，先运行
yarn check:color。
- 如果
check:color 报告有漂移，再运行 yarn sync:color，然后查看 diff，再决定是否继续。
- 不要在没有先跑
check:color 的情况下手写 Color token 对齐改动。
- 从 Figma 读取颜色时，先看
get_design_context 结果里的 var(--...)，不要先猜旧变量名。
Typography
Typo 是对外公开的用法，现有 key 不要直接删除，也不要随意改名。- 如果任务是“同步 / 对齐 / 更新 Typography”，先运行
yarn check:typography。
- 如果
check:typography 报告有漂移，再运行 yarn sync:typography，然后查看 diff，再决定是否继续。
- 不要在没有先跑
check:typography 的情况下手写 Typography 对齐改动。
- Typography 同步遵循这条规则：
- 上游新增 key：本地新增
- 上游同 key 改值：本地同步改值
- 上游删除 key：本地不删除，只在报告里提示
- 从 Figma 读取字体时，先看 design context 里的字体 token，再查
FIGMA_TO_TYPO。
- 如果 Figma 名字和代码名字不完全一样，再按字号、行高、字重、是否大写来判断，不要只靠名字猜。
文档
- 不要在多个地方各写一份完整映射表，避免以后不同步。
- 如果这次改动会影响 agent 查找 Typography 或 Color 的方式，再同步更新：
packages/eagle/docs/llms.txtskills/cloudtower-eagle/SKILL.md
共用规则
- 始终用 package.json 定义的 script：
yarn lint, yarn format, yarn typings, yarn test:ci, yarn build-storybook
- 代码示例统一从
@cloudtower/eagle 主入口导入
- 弹窗打开方式：
pushModal({ component: () => (<Component />), props: {} })
- 文档和注释用中文编写
- 不要使用 emoji
- 组件改动需同步测试：新增组件、修改 Props 行为、添加 data-testid 时，编写或更新对应的单元测试（
src/<layer>/<Component>/__test__/），验证新行为符合预期
产出物检查清单
每次改动完成后，确认：
