Tai Component Sync

Token 体系要点

颜色

• 公开语义颜色只有 4 类：textColor、bgColor、borderColor、functionalColor
• 不允许为新组件创建组件级颜色 token 包装层
• 组件内部实现可使用 primitive（STATIC.*、SHADOW.* 等），但不向文档/用户暴露

排版

• 组件代码统一使用 tokens.typography.*（如 tokens.typography.title.page.fontSize）
• 旧常量 FONT_SIZE / FONT_WEIGHT / LINE_HEIGHT 保留在 tokens/index.ts 供过渡期
• 静态配置常量（编译时）使用硬编码数值 + 注释标注对应语义 token
• 图标 fontSize 属性（非排版语义）保持硬编码数值

5 大排版类别

Sync Workflow

1. 找到真实样式源

• 先确认样式的单一事实源是在组件本体、token 还是组合组件。
• 如果发现重复定义，优先收敛到组件包或统一 token，避免 docs 层自己再画一份样式。
• 同步检查相关类型文件，例如 Button.types.ts。

2. 找全调用链

• 搜索直接和间接使用该组件的地方，至少覆盖：
  • 组件包内部复用
  • packages/docs/src/design-system/*Component.tsx
  • packages/docs/src/design-system/pages/*
  • 路由入口、组合展示页
• 对"文档演示组件自己实现一套样式"的情况保持高警惕。

3. 同步调用方和文案

• 如果底层组件行为变了，更新上层包装组件和文档描述。
• 文档页中的状态文案必须与真实渲染一致，例如"无描边""轻描边""透明背景"。
• 优先让展示组件直接复用基础组件，而不是再维护一套原生 DOM 样式。

4. 输出 Token 使用清单

每个组件同步完成后，必须输出该组件真实使用的全部公开 token 清单，分两类：

颜色 token

列出所有使用的 textColor.*、bgColor.*、borderColor.*、functionalColor.*、组件级 token（如 input.*、checkbox.*）和静态色（STATIC.*、PRESSED_OVERLAY）。

排版 token

列出所有使用的 tokens.typography.* 语义路径。

格式示例：

## Button Token 清单

### 颜色 token
- `bgColor.brand` — primary 变体背景
- `textColor.anti` — primary 变体文字
- `STATIC.transparent` — ghost 变体背景
...

### 排版 token
- `tokens.typography.label.buttonLarge` — xlarge 尺寸文字
- `tokens.typography.label.buttonMedium` — large 尺寸文字
...

5. 重建预览

• 在仓库根目录执行：
  • pnpm build
  • 如需本地持续联调可用 pnpm dev
  • 仅预览文档可用 pnpm preview
• 不能只改源码不重建预览产物。

6. 完成前核对

只有下面四层都一致，才能对用户说"已改好"：

1. 组件源码、类型、token 已同步
2. 已接入该组件的调用方和包装组件已同步
3. 文档预览已重建，文案与实际渲染一致
4. Token 使用清单已输出

Common Failure Modes

• token 前后定义打架，后面的返回值把前面的修复覆盖掉
• docs 包装组件未复用基础组件，导致预览与真实组件分叉
• 只改了 packages/components，没改 pages/* 或 *Component.tsx
• 文案还写旧行为，例如"无描边"但真实仍有边框
• 构建未刷新，预览仍在看旧产物
• 没有输出 token 使用清单，用户无法验证改动是否正确
• 组件本体和 docs 页面的排版 token 不一致

Response Contract

• 如果只完成了一部分，必须明确说明哪一层未同步
• 不得把"源码已改但未重建/未核对调用方"的状态表述为"已改好"
• 汇报结果时优先说明：源组件、调用方、预览 是否都完成
• 必须附上每个组件的 token 使用清单