这节给你一份"组件契约模板"。它的写法重点不是把信息堆满，而是把争议点提前固定成条款。你们可以把它放进组件库站点、README、或直接放进设计稿旁边的说明区；只要团队默认"以契约为准"，沟通成本会明显下降。
1）基本信息（让人快速定位）
- 组件名 / 英文标识 ：例如
Button/AppButton - 组件目标（一句话） ：它解决什么问题，不解决什么问题
- 适用场景 / 不适用场景：例如"用于提交/确认动作；不用于页面跳转（应使用 Link）"
- 依赖与前置：是否依赖主题系统、国际化、表单框架、路由等
写法提示：目标要写"边界"，别写口号。边界越清晰，越少被滥用。（Krug, 2014）
2）视觉与布局约束（设计最关心，但要写成可验收条款）
- 尺寸与密度：size 列表（S/M/L）、高度、左右 padding 的区间
- 层级与变体：primary/secondary/text/danger 等，哪些必须提供
- 图标规则：leading/trailing icon 是否允许、大小、间距
- 对齐规则：文本对齐、按钮组间距、换行策略
- 主题与暗色模式：是否支持、失败时的降级策略
条款化例子（比"看起来差不多"更可判定）：
- "同一按钮在 S/M/L 三个尺寸下，高度固定为 28/32/36px（或按你们系统），文本基线居中。"
- "danger 变体在 hover/focus/disabled 三态下都要有视觉区分，否则视为不合格。"
3）API 契约（研发最关心：输入、输出、默认值）
建议用表格写清楚，每一项都要回答：类型、是否必填、默认值、是否受控、与其他属性的联动。
-
Props/Slots
value/modelValue：受控还是非受控？defaultValue：只在首次生效还是每次都生效？disabled/readonly：差异是什么？
-
Events/Callbacks
- 触发时机：onChange 在输入中触发还是失焦触发？
- 参数形状：回传值、错误对象、原生 event 是否暴露
-
Methods/Ref（如果有）
- 是否提供
focus()/scrollIntoView()
- 是否提供
-
A11y Props（可访问性）
- 是否透传
aria-*，有哪些必填项（如aria-label）
- 是否透传
写法提示：API 要写"互斥关系"和"优先级"。例如
disabled=true时，onClick是否还会触发？如果会触发，那测试与埋点都要跟着改。
4）状态机（测试和联调最需要：什么时候是什么状态）
这是减少扯皮的关键段落。用"状态 + 触发条件 + UI 表现 + 交互限制"写清。
建议最少覆盖：
- default：默认态
- hover / active / focus：交互态（含键盘 focus）
- loading：加载态（是否可点击、是否展示 spinner、是否保留宽度防抖动）
- disabled：禁用态（是否可聚焦、tooltip 是否可用）
- error / warning / success：反馈态（尤其对表单类组件）
- empty：空态（列表、下拉、表格常见）
推荐写成表格或小型状态图。状态越多，越要用"表格化表达"降低理解负担。（Miller, 1956）
5）边界条件与异常处理（最容易引发争论的一块）
把"极端情况怎么做"写成条款，避免每次都临时决定。常见边界包括：
- 超长文本：截断/换行/tooltip 规则
- 无数据 / null：展示什么文案，是否允许自定义
- 慢请求：loading 延迟阈值（比如 >300ms 才显示 spinner，防闪烁）
- 并发更新：最后一次写入优先还是队列处理
- 错误呈现：红字、红框、toast、还是静默；是否可重试
- 国际化：文字长度变化对布局的影响，是否允许两行
这段要写得"像判例"。你写得越具体，回归越省力。
6）一致性与可替换性（面向设计系统/组件库治理）
- 与设计 Token 的关系：哪些颜色/圆角/间距必须来自 Token
- 可替换约束：未来升级版本时，哪些 API 不能动（兼容承诺）
- 弃用策略（Deprecation） ：老属性何时废弃，如何提示迁移
这块能让组件库变成"可演进的产品"，而不是一次性工程。（Gamma et al., 1994）
7）验收标准（Definition of Done）
把"验收"从口头变成清单：
- 功能验收：列出必须通过的用例
- 视觉验收：列出必须对齐的点（像素级还是容差范围）
- 可访问性验收：键盘可操作、读屏标签、对比度要求
- 性能验收：渲染耗时、列表虚拟化阈值（如适用）
- 兼容性验收：浏览器/端侧范围
写法提示：验收标准要能被测试自动化部分覆盖，剩下才是人工 spot check。
8）测试建议与用例（让测试能直接抄）
- 最小回归集（必须自动化的 5--10 条）
- 关键交互用例（键盘、焦点、复制粘贴、拖拽如有）
- 异常用例（超时、接口报错、空数据、权限不足）
- 可视化回归建议（截图点位、状态覆盖）
这里建议引用"测试金字塔"的思想：单测覆盖逻辑、集成测覆盖组件行为、少量 e2e 覆盖关键链路。（Cohn, 2009）
一句话总结（给你放在模板顶部）
组件契约文档 = 视觉条款 + API 条款 + 状态机 + 边界判例 + 验收清单。