@microi.net/cli 5.7.8 → 5.8.0

package/skills/ui-design/references/mci-design-contract.md

@@ -1,163 +1,163 @@
-# 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-*` 组件。
-- 修改契约后至少截图一张受影响页面的桌面和移动版本，并覆盖亮/暗主题及相关业务状态。
-- 契约、源码、浏览器截图三者冲突时不得宣称完成；修复后重新执行结构检查、定向测试和视觉验收。
+# 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-*` 组件。
+- 修改契约后至少截图一张受影响页面的桌面和移动版本，并覆盖亮/暗主题及相关业务状态。
+- 契约、源码、浏览器截图三者冲突时不得宣称完成；修复后重新执行结构检查、定向测试和视觉验收。