@microi.net/cli 5.8.4 → 5.8.6

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

package/skills/ui-design/references/motion-and-media.md

@@ -1,78 +1,78 @@
-# Microi 动效与媒体规范
-
-## 预算先行
-
-| 项目 | 桌面建议 | 移动端建议 |
-| --- | --- | --- |
-| 首屏可读内容 | 尽快出现，不等待装饰资源 | 同左 |
-| 主转场 | 260-420ms | 220-340ms |
-| 微交互 | 140-220ms | 120-180ms |
-| 列表交错 | 30-60ms/项，最多前 8 项 | 20-40ms/项，最多前 6 项 |
-| Canvas/WebGL 像素比 | 上限 1.5-2 | 上限 1-1.5 |
-| 持续装饰动画 | 至少 4s/循环 | 默认减弱或关闭 |
-
-动画只使用 `transform`、`opacity` 和必要的 `background-position`。禁止持续动画布局属性、滤镜和阴影。
-
-## 首屏动效状态机
-
-```text
-idle -> entering -> settled -> interacting -> paused -> reduced
-```
-
-- `entering` 只运行一次，不能因局部数据更新整页重播。
-- `settled` 保留低振幅状态，主 CTA 始终可点击。
-- 页面隐藏、离开视口或系统省电时进入 `paused`。
-- `prefers-reduced-motion` 或低性能策略进入 `reduced`，直接显示最终布局。
-
-## 滚动叙事
-
-- 先把内容按无 JS 的普通页面排好，再增强 sticky 和进度。
-- 每个滚动段只映射一个明确状态；使用离散段落而非无限连续参数。
-- 粘性舞台不能捕获滚轮或阻止浏览器返回。
-- 移动端内容高度过长时取消 sticky，按图文段落顺序展示。
-
-## Canvas / WebGL
-
-- Canvas 仅负责展示；标题、按钮、表单和可访问文本保留在 DOM。
-- 初始化前显示同尺寸静态海报或骨架，失败时继续保留海报。
-- 使用 `IntersectionObserver` 控制启停，标签页隐藏时暂停 requestAnimationFrame。
-- 组件卸载时释放纹理、几何体、材质、事件和动画帧。
-- 纹理使用本地合法资源，压缩尺寸；禁止把远程大图直接作为不可控依赖。
-- 指针交互必须限定在容器，手机端改为陀螺仪前必须获得权限，否则使用静态视差。
-
-## 图片
-
-- 预览卡片先确定固定比例和 `object-fit`：人物/环境/商品通常 `cover`，完整界面/海报/移动端截图通常 `contain`。
-- 首屏关键图片提供 width/height 或 aspect-ratio，防止布局偏移。
-- 非首屏图片 `loading="lazy"`；首屏主图按需 preload，但不能一次 preload 多张大图。
-- 远程资源必须下载为本地合法资产或提供稳定降级；404 时显示有品牌感的空图，不显示破图图标。
-
-## 视频
-
-- 视频必须静音、可暂停、有海报；默认不在移动端自动播放背景视频。
-- 有声内容必须由用户主动触发，提供字幕或文字摘要。
-- 背景视频不承担唯一信息；失败后页面仍能理解和操作。
-
-## 可访问与低性能降级
-
-```css
-@media (prefers-reduced-motion: reduce) {
-  [data-mci-ui-root] *,
-  [data-mci-ui-root] *::before,
-  [data-mci-ui-root] *::after {
-    scroll-behavior: auto !important;
-    animation-duration: .01ms !important;
-    animation-iteration-count: 1 !important;
-    transition-duration: .01ms !important;
-  }
-}
-```
-
-同时检查低端 Android、后台标签页、弱网、资源失败、浏览器缩放 200% 和高对比模式。视觉效果不能成为业务完成事实源。
-
-## 复盘：烘焙棋格与可交互覆盖层错位
-
-- 触发场景：非母版比例屏幕、DPR 改变、横竖屏切换或背景呼吸动画后，点击/棋子未落在实际棋格。
-- 根因：图片 cover 尺寸、设计尺寸与 framebuffer 尺寸混用，或图片独立变换而交互层静止。
-- 通用规则：从实际图片尺寸与同一个父级变换推导烘焙 UV 位置；拾取为渲染的精确逆变换，棋子、提示、点击和特效共用坐标事实源。换肤与 resize 后重算，不增加第二层运行网格掩盖错位。
-- 自动化检查：逐格 round-trip；原生比例/16:9/超宽/竖屏与不同 DPR 的真实 pointer 点击；动画前后、resize 和换肤后核对索引与截图。
+# Microi 动效与媒体规范
+
+## 预算先行
+
+| 项目 | 桌面建议 | 移动端建议 |
+| --- | --- | --- |
+| 首屏可读内容 | 尽快出现，不等待装饰资源 | 同左 |
+| 主转场 | 260-420ms | 220-340ms |
+| 微交互 | 140-220ms | 120-180ms |
+| 列表交错 | 30-60ms/项，最多前 8 项 | 20-40ms/项，最多前 6 项 |
+| Canvas/WebGL 像素比 | 上限 1.5-2 | 上限 1-1.5 |
+| 持续装饰动画 | 至少 4s/循环 | 默认减弱或关闭 |
+
+动画只使用 `transform`、`opacity` 和必要的 `background-position`。禁止持续动画布局属性、滤镜和阴影。
+
+## 首屏动效状态机
+
+```text
+idle -> entering -> settled -> interacting -> paused -> reduced
+```
+
+- `entering` 只运行一次，不能因局部数据更新整页重播。
+- `settled` 保留低振幅状态，主 CTA 始终可点击。
+- 页面隐藏、离开视口或系统省电时进入 `paused`。
+- `prefers-reduced-motion` 或低性能策略进入 `reduced`，直接显示最终布局。
+
+## 滚动叙事
+
+- 先把内容按无 JS 的普通页面排好，再增强 sticky 和进度。
+- 每个滚动段只映射一个明确状态；使用离散段落而非无限连续参数。
+- 粘性舞台不能捕获滚轮或阻止浏览器返回。
+- 移动端内容高度过长时取消 sticky，按图文段落顺序展示。
+
+## Canvas / WebGL
+
+- Canvas 仅负责展示；标题、按钮、表单和可访问文本保留在 DOM。
+- 初始化前显示同尺寸静态海报或骨架，失败时继续保留海报。
+- 使用 `IntersectionObserver` 控制启停，标签页隐藏时暂停 requestAnimationFrame。
+- 组件卸载时释放纹理、几何体、材质、事件和动画帧。
+- 纹理使用本地合法资源，压缩尺寸；禁止把远程大图直接作为不可控依赖。
+- 指针交互必须限定在容器，手机端改为陀螺仪前必须获得权限，否则使用静态视差。
+
+## 图片
+
+- 预览卡片先确定固定比例和 `object-fit`：人物/环境/商品通常 `cover`，完整界面/海报/移动端截图通常 `contain`。
+- 首屏关键图片提供 width/height 或 aspect-ratio，防止布局偏移。
+- 非首屏图片 `loading="lazy"`；首屏主图按需 preload，但不能一次 preload 多张大图。
+- 远程资源必须下载为本地合法资产或提供稳定降级；404 时显示有品牌感的空图，不显示破图图标。
+
+## 视频
+
+- 视频必须静音、可暂停、有海报；默认不在移动端自动播放背景视频。
+- 有声内容必须由用户主动触发，提供字幕或文字摘要。
+- 背景视频不承担唯一信息；失败后页面仍能理解和操作。
+
+## 可访问与低性能降级
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  [data-mci-ui-root] *,
+  [data-mci-ui-root] *::before,
+  [data-mci-ui-root] *::after {
+    scroll-behavior: auto !important;
+    animation-duration: .01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: .01ms !important;
+  }
+}
+```
+
+同时检查低端 Android、后台标签页、弱网、资源失败、浏览器缩放 200% 和高对比模式。视觉效果不能成为业务完成事实源。
+
+## 复盘：烘焙棋格与可交互覆盖层错位
+
+- 触发场景：非母版比例屏幕、DPR 改变、横竖屏切换或背景呼吸动画后，点击/棋子未落在实际棋格。
+- 根因：图片 cover 尺寸、设计尺寸与 framebuffer 尺寸混用，或图片独立变换而交互层静止。
+- 通用规则：从实际图片尺寸与同一个父级变换推导烘焙 UV 位置；拾取为渲染的精确逆变换，棋子、提示、点击和特效共用坐标事实源。换肤与 resize 后重算，不增加第二层运行网格掩盖错位。
+- 自动化检查：逐格 round-trip；原生比例/16:9/超宽/竖屏与不同 DPR 的真实 pointer 点击；动画前后、resize 和换肤后核对索引与截图。