# MCI-DESIGN 设计契约

大型项目在根目录维护 `MCI-DESIGN.md`，让界面意图、精确取值和组件状态可以版本管理、自动检查，并由人和 AI 共同延续。它是 `Microi.UI/src/theme/tokens.css` 的项目级语义说明，不替代真实源码 token，也不替代线框、原型和视觉验收。

## 双层单源模型

设计契约必须同时包含两层，缺少任一层都不完整：

1. **机器可读层**：颜色、字体、间距、圆角、阴影、组件状态和引用关系。它回答“准确使用什么值”，用于检查、差异比较和生成运行时变量。
2. **人类可读层**：产品对象、受众、情绪目标、视觉隐喻、信息层级、选择理由和明确禁区。它回答“为什么这样设计”，帮助接手者在契约没有覆盖的新场景中作出一致判断。

精确值会随项目变化，设计理由决定取舍方向。若两层暂时冲突，先核对用户最新要求和合法源码，再同时修订契约与实现，禁止只改其中一边。

## 意图优先级

设计前按以下顺序收敛，不从颜色选择器开始：

1. 用户进入页面后的首要任务与成功结果。
2. 页面希望产生的一个主情绪，例如可信、安静、敏捷、温暖或专注。
3. 一个具体视觉隐喻，例如“安静的专业工作台”“柔和的手工纸张”“夜间发光仪表舱”。具体隐喻比堆叠“高级、现代、极简”等形容词更能约束色彩、材质、密度和动效。
4. 一组明确的“应当 / 禁止”，把隐含边界写出来。
5. 最后才是 token、组件和页面实现。

一个页面只保留一个主隐喻，辅助气质最多两项。不要把温暖圆润、深色霓虹、通透玻璃和高密度数据等多套语言同时堆在一个界面。

## 固定章节顺序

核心章节按以下顺序书写，便于稳定解析和审查：

1. 产品概览与目标用户
2. 视觉性格与情绪目标
3. 颜色
4. 字体
5. 布局与间距
6. 层级、材质与形状
7. 组件与状态
8. 页面模式与信息架构
9. 动效与媒体
10. 响应式与安全区
11. 可访问性、性能与降级
12. 应当与禁止

允许在末尾增加项目专属章节，但必须保留未知扩展内容，不能重复核心章节，也不能用近似拼写制造第二套同义章节。确实不适用的项目可以省略某一规则，但要在“有意省略”中说明理由。

## 机器可读层

机器块应使用语义命名，避免 `blue500`、`bigRadius`、`shadow2` 这类只描述外观、不说明用途的名字。组件可通过 `{路径}` 引用共享 token；引用必须存在，不能形成循环。

```yaml
contract:
  version: 1
  project: 示例项目
  mode: data-workspace
  intent: 安静、清晰、可快速扫描的专业工作台

tokens:
  color:
    canvas: var(--mci-bg-base)
    surface: var(--mci-bg-card)
    surfaceElevated: var(--mci-bg-elevated)
    textPrimary: var(--mci-text-primary)
    textSecondary: var(--mci-text-secondary)
    primary: var(--mci-color-primary)
    danger: var(--mci-color-danger)
  typography:
    title: { size: 16px, lineHeight: 1.45, weight: 700 }
    body: { size: 14px, lineHeight: 1.65, weight: 400 }
    meta: { size: 12px, lineHeight: 1.5, weight: 500 }
  spacing:
    compact: 8px
    control: 12px
    card: 16px
    section: 24px
  shape:
    control: var(--mci-shape-input)
    card: var(--mci-shape-card)
    pill: var(--mci-radius-full)
  elevation:
    card: var(--mci-shadow-card)
    cardHover: var(--mci-shadow-card-hover)

components:
  dataCard:
    background: "{tokens.color.surface}"
    radius: "{tokens.shape.card}"
    padding: "{tokens.spacing.card}"
    states:
      default: { elevation: "{tokens.elevation.card}" }
      hover: { elevation: "{tokens.elevation.cardHover}", lift: -2px }
      focus: { outline: "{tokens.color.primary}" }
      selected: { border: "{tokens.color.primary}" }
      disabled: { opacity: 0.56 }

omissions:
  - rule: backgroundVideo
    reason: 高频数据页不需要持续媒体，减少干扰与资源开销
```

机器块至少满足：

- 有主色、页面底色、表面色、主/次文字色和危险色。
- 字体角色包含字号、行高、字重；间距、圆角和层级都有明确单位或 `--mci-*` 引用。
- 组件状态覆盖适用的 default、hover、focus、pressed、loading、empty、error、disabled、selected、success。
- 同一语义只定义一次；组件优先引用共享 token，而不是重新复制值。
- Alpha、混色和玻璃表面必须说明叠加在哪种底色上；只给透明度不算完整颜色定义。

## 人类可读层

每个核心选择都要写一行理由，尤其是：

- 为什么这种气质适合目标用户与任务。
- 颜色如何区分主动作、状态、表面和内容层级。
- 字体如何形成阅读节奏，中文和数字如何共存。
- 内部紧凑与外部宽松分别使用哪些间距。
- 深度来自色调层、细边框、环境阴影、透明材质还是实体投影。
- 圆角、切角、胶囊或有机形状表达什么性格。
- 卡片、按钮、输入、导航、弹层在所有状态下如何变化。
- 哪些装饰会破坏任务，应明确禁止。

## 可迁移的视觉气质

以下不是成品主题，而是把意图翻译为系统规则的示例：

| 气质 | 色彩与材质 | 形状与间距 | 动效 | 禁止 |
| --- | --- | --- | --- | --- |
| 温暖友好 | 暖白或浅沙底、自然低饱和强调色、轻触感层次 | 圆润或轻微有机形，外部留白宽松 | 柔和上浮与按压 | 冷硬高对比、密集霓虹、尖锐切角 |
| 深色发光 | 深色表面、少量青蓝紫发光语义、清晰高对比文字 | 边界精确、圆角克制、层级紧凑 | 短促聚焦与状态脉冲 | 大面积炫光、彩虹状态色、持续漂移 |
| 雾感通透 | 灰白低彩底、细线边框、轻透明表面 | 大留白、轻圆角、细腻分层 | 慢速淡入与透明度变化 | 厚重投影、不透明色块堆叠、过度模糊 |

## 后台数据卡片契约

后台数据卡片是高频操作容器，不是营销海报：

- 固定信息顺序：真实图片或紧凑身份标记 → 标题与状态 → 2—4 个关键字段 → 时间/辅助标签 → 操作区。
- 配置了图片但当前行无图时，使用 40—44px 的首字/图标标记；禁止生成占据卡片三分之一以上的装饰占位图。
- 默认桌面四列，显式列数配置优先；中等宽度自动降为三列或两列，移动端单列。卡片最小可读宽度优先于“同屏塞更多”。
- 标题最多两行，主次文字、金额、状态与时间有固定层级；标签只表达状态或分类，不把每个字段都做成胶囊。
- 操作区优先一个主动作、一至两个次动作，其余收进“更多”；危险动作不得与主动作同权。移动端触控目标不小于 44px。
- 骨架屏必须复刻最终标题、字段和操作区的几何结构；空态解释原因并提供下一步。
- 整卡可进入详情时必须提供键盘焦点、Enter/Space 触发和可见 focus；内部按钮阻止事件冒泡。

## 契约检查、差异与输出

每次修改契约或 UI 时，按顺序检查：

1. **结构**：核心章节存在且顺序正确，无重复章节、疑似拼写错误或无法识别的 token 组。
2. **类型**：颜色、长度、数字、布尔值和状态对象类型正确，token 式文本没有被误放在普通说明里而漏解析。
3. **引用**：所有 `{路径}` 可解析，无循环引用；未被组件、页面或输出消费的孤立 token 要删除或说明用途。
4. **语义**：主色、表面、文字层级、组件状态和有意省略完整；命名能解释用途。
5. **可访问性**：正文和交互态对比度满足项目标准，焦点可见，键盘路径连续，低动效降级完整。
6. **差异门禁**：评审设计契约的语义变更和实现变更是否同时出现；意外删除、重命名或大范围 token 漂移应阻止合入。
7. **输出**：需要生成运行时变量或其它主题格式时，只由已校验的机器块派生，禁止维护第二份手工 token。

契约格式若仍在演进，项目必须锁定 `contract.version`，升级时先查看差异并一次性迁移。跨平台脚本要提供不依赖文件扩展名的稳定入口，避免不同终端执行出不同结果。

## AI 使用规则

- 开始实现前完整读取契约和 `ui-design` skill；先复述页面任务、主气质和三条禁止事项，再写页面。
- 契约缺少的精确值优先继承 Microi.UI token；不能用“看起来差不多”的硬编码补洞。
- 先稳定颜色、字体、间距、层级和形状，再定义组件状态；不要在基础 token 尚未收敛时过早堆复杂组件结构。
- 新模式在两个以上页面重复时，先更新契约，再抽成 `Mci*` 或项目级 `mci-*` 组件。
- 修改契约后至少截图一张受影响页面的桌面和移动版本，并覆盖亮/暗主题及相关业务状态。
- 契约、源码、浏览器截图三者冲突时不得宣称完成；修复后重新执行结构检查、定向测试和视觉验收。