# 设计系统工作原则

## 原则 0：边界翻译层（最高原则）
- Figma 侧命名服务设计师可读性（保持 Figma 原名）
- Code 侧命名服务开发可读性（遵循 Vue 生态约定）
- 任何两侧不一致必须在 src/design-system/translation/ 下显式登记
- 无登记的不一致 = bug
- 设计态属性（仅设计预览）不映射代码，在 divergences.md 说明
- 组件粒度的拆分/合并（一对多、多对一）登记在 divergences.md 的“组件级映射”节
- 常见组件级映射模式：仅命名差异（登记于 prop-aliases.md）/ 双家族风格聚合 / 容器+Item 拆分 / 多 set 聚合 / 资产 registry 聚合（后四种登记于 divergences.md “组件级映射”节）

## 原则 1：API 形态判定
- 给设计师看的（hover 预览、装饰开关） = 设计态，不映射
- 给开发用的（运行时行为/外观） = 运行时，映射
- 不确定时：单值或 Yes/No 大概率设计态；多值且每值有业务语义大概率运行时

## 原则 2：命名优先级
- Vue 生态通行命名（closable / disabled / size）优先于 Figma 命名
- 差异必须在 prop-aliases.md 登记

## 原则 3：图标 alias 层
- src/icons/ 用 Figma 原名
- 组件用 alias
- 映射在 icon-aliases.ts 维护
- alias 指向错的 Figma 图标（glyph family 错）= bug

## 原则 4：尺寸与颜色 token
- 颜色硬编码 = bug，必须用 token
- Figma 是内容驱动尺寸时代码必须 fit-content / max-content
- "代码偏好简单实现"导致的不一致 = bug

## 原则 5：审计粒度
- API 层 SSOT = component-spec.md（由 code+Figma 双向 diff 生成）
- 视觉层 SSOT = 本地 JSON + token 文件
- 视觉层 audit 用脚本，不用 AI
- API 层 audit 仅审 diff 表的 ⚠️ 行

## 原则 6：决策默认值
- 🟢 仅代码 prop：默认删除；Vue 约定 → 保留 + 登记
- 🟡 仅 Figma 设计态：不映射 + 登记
- 🟡 仅 Figma 运行时态：加进代码
- 🟠 命名不同语义同：Vue 命名 + 登记

## 决策 Log

- **2026-04-28：Phase 6.1 批量登记**
  - 类别 A：~47 项 🟢 / 🟡 / 🟠 项按 Vue 生态标准 / 设计态不映射 / 命名 alias 批量登记
  - 类别 B：10 项决策（B1–B10），全部按推荐方案执行
  - 详见：`src/design-system/translation/prop-aliases.md`、`src/design-system/translation/divergences.md`、`docs/internal/runtime-additions.md`
  - 后续修复阶段计划：
    - 6.2 视觉层 token 替换
    - 6.3 删除自创内容（Notification.success / type）
    - 6.4 新增运行时能力（showCount / multiple / editable）
    - 6.5 微结构修复（Notification side pop / warning glyph / 按钮颜色 / PromptMessage L width）
    - 6.6 双形态 API（FormItem.label / Tooltip.content）
    - 6.7 Badge prop 拆分
    - 6.8 Button canonical 完成迁移

- **2026-05-09：F25 cleanup — Icon default color 决策**
  - 设计意图：单色非品牌 icon 默认色 = figma `Color Type/Icon/Default` Variable = code `--icon-default` token (dark `#9e9e9e` / light `#595959`)
  - Figma SVG export pipeline 限制：Variable 引用解析为 literal hex `#dbdbdb`（实际是 `UX/Grey/grey-4` palette 值，designer 用作占位语义）
  - **Code 端治本**：`figma-sync/export-icons.mjs` 的 `transformSvgCurrentColor` 把 `#dbdbdb` per-path 转 `currentColor`；audit 回归保护只 ERROR 残留 `#dbdbdb`
  - **消费方 responsibility**：消费组件容器自己设 `color: var(--icon-default)` 提供 fallback；**不**在 `Icon.vue` 的 `.icon` 元素层强制设 color——会破坏现有 `InputNumber:disabled` / `PromptMessage status icon` / `Notification --error` 等 cascade-based color override pattern
  - **AI 工具未来生成 figma 效果图**：单色非品牌图标 path fill 必须绑 `Color Type/Icon/Default` Variable，不写 hex literal——详见 [`docs/internal/mockup-conventions.md`](./internal/mockup-conventions.md) §M10
  - **第三方 logo / app icon hex (Facebook 蓝 / Twitch 紫 / etc.)**：保留 hex literal，**不**加进 TVU color token 表——它们封装在 catalog SVG 内，外部组件通过 `<Icon name="..." />` 引用，颜色不泄漏
  - 详见 [`docs/internal/_reports/f25-cleanup-2026-05-09.md`](./internal/_reports/f25-cleanup-2026-05-09.md) + [`src/design-system/translation/divergences.md`](../src/design-system/translation/divergences.md) §"Figma SVG export pipeline limitation"