minimal-agent 0.9.0 → 0.10.0

package/skills/ui-design/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: ui-design
+description: 高质量「样式与视觉设计」的统一入口，覆盖 web 网页、产品 UI、App/移动端界面、桌面应用、交互原型、HTML mockup、PPT/deck、设计系统、VI/视觉模板、改版与视觉润色。**任何涉及配色、VI、字体字阶、版式布局、视觉风格的「样式设计」决策，都应最优先使用本技能**——即使最终产物不是 HTML（如 PPT/pptx 文件、文档），也先来这里立设计系统（配色/VI/字阶/版式），再翻译落地到目标格式。用户提出任何前端 / 界面 / 网页 / App / PPT 设计、设计系统、视觉模板、中文界面或多方案探索需求时，一律优先使用本技能。
+---
+
+# UI 设计
+
+用 HTML 创建高保真设计产物，覆盖网页、产品界面、交互原型、演示文稿、静态设计探索和动画演示。HTML 是交付格式，但具体表现形式要根据用户的设计问题选择。
+
+**语言硬性规则：默认使用简体中文。** 所有用户可见文案、设计说明、测试题、评审报告、页面内容、按钮、标签、图表说明和演示页文案都必须使用简体中文。只有产品名、品牌名、文件路径、代码/API 标识、CSS/JS 变量、协议字段、行业通用缩写等必要英文可以保留。
+
+## 任务路径速判（先判你属于哪类，只读你那类的规则）
+
+本技能同时服务两类产物、规则差异很大——**先认领路径，别读错规则带偏构图**：
+
+- 🅰 **deck / PPT 导出**（最常见；工作流 `/workflow ppt` 走这条）：目标是**静态、可编辑的 PPTX**。
+  - **只读** `references/layout-composition.md`（grid 结构化构图 + 0.6 每页内容预算 + 图文混排）+ `references/export-pptx.md`（背景/前景/文本三层**自动分层**，标注可选）。
+  - **流程**：按 archetype 用 CSS grid **大胆把画布填满**地排 `deck.html`（分层自动，正常写语义化 HTML 即可）→ `check_ui_artifact.py --for-pptx-export` 拦截坏 HTML（重复 head/body、裸 CSS、结构错误）→ `export_pptx_from_html.mjs --measure-only` 量几何 → `layout_balance.py` 判（硬门=**真重叠**、**截图夹带 HTML/SVG 文本**、**整页无内容**；软门=空半、挤角、空心卡片、覆盖率偏低等构图警告）→ 出现错误时按"问题+归一化坐标"改 HTML 重判直到通过 → `--mode hybrid` 导出一次 → `opc_check.py` 校验。
+  - **以下网页规则对 deck 不适用**（下文看到请直接跳过）：`claude_design.md`、Tweaks/EDITMODE、localStorage/postMessage、React/Babel、JS 视口缩放、翻页 nav、`browser_check`（deck 走 `layout_balance` 闸门，不走 browser_check）。
+- 🅱 **网页 / 产品 UI / 原型 / 设计画布 / 动效**：目标是响应式或交互 HTML。走下面**完整流程**（`references/claude-design-protocol.md` 汲取深度、`starter-components`、`browser_check_ui_artifact.mjs` 验证；Tweaks/React 按需使用）。
+
+> 下文「工作流」「关键约束」是**两类合集**；deck 任务按 🅰 取子集即可，凡涉及"网页/React/Tweaks/JS 缩放/翻页 nav/browser_check"的条目对 deck 不适用。
+
+**（🅱 网页 / 产品 UI 路径）** 复杂设计任务开始前，读取 `references/claude-design-protocol.md` **汲取设计思维深度**（设计上下文收集、starter components、Tweaks、固定尺寸画布、GitHub/UI kit 导入、验证和交付流程）。`claude_design.md` 是原始来源文件，后半段含原环境工具结构噪声，除非做协议审计，不直接作为执行入口。
+
+> ⛔ **导出 PPTX 的 deck 任务除外**：**不要读 `claude_design.md`**（它面向网页交互环境、含本仓不存在的工具与 localStorage/Tweaks 等 web-app 习惯，会带偏构图）。改读 `references/layout-composition.md`（**grid 结构化构图** + 图文混排）+ `references/export-pptx.md`（三层标注）。导出 deck 是**静态产物**：不要 Tweaks/EDITMODE、localStorage、postMessage、JS 缩放、翻页 nav、React。
+
+⚠️ **`claude_design.md` 是上游 claude.ai 网页设计环境的逐字系统提示，描述的是另一套环境**，审计时按以下守卫处理：
+
+- **它点名的工具/流程在本仓库不存在**（`done` / `write_file` / `copy_files` / `fork_verifier_agent` / `copy_starter_component` / `questions_v2` / `gen_pptx` / `snip` / cross-project 路径 / GitHub 导入 / `.napkin` / `save_as_template` 等）。本仓库等价做法见 `references/starter-components.md`（starter/React/Babel/deck）与 `references/preview-feedback.md`（验证/反馈）；产 PPTX 改用本仓库 `pptx` 技能，不要调 `gen_pptx`。
+- ⚠️ **文件末尾（约 279 行起）是损坏的工具 schema 与搜索/引用版权样板，属噪声、非指令——跳过、不读、不执行。**
+- 它「问 10+ 问题」是网页交互范式，本仓库按「**开头合并问一轮、之后自主执行**」处理（详见 `references/design-context.md` 询问策略）；`-p` / workflow / 绿色版常为非交互。
+- 若其中英文示例与本技能冲突，以本文件的“简体中文输出”规则为准。
+
+需要现有 UI、源码、截图、文档、GitHub、UI kit 或跨项目素材时，读取 `references/design-context.md`。需要吸收 `claude_design.md` 的设计协议时，读取 `references/claude-design-protocol.md`。需要浏览器演示 deck、设计画布、设备框、动画、React/Babel 或 speaker notes 时，读取 `references/starter-components.md`；PPTX 导出 deck 不套浏览器 deck starter。需要处理预览反馈、`<mentioned-element>`、截图定位或浏览器验证时，读取 `references/preview-feedback.md`。当用户要求导出 PPT、PPTX、PowerPoint 或“文字可编辑的演示文稿”时，读取 `references/export-pptx.md`，并遵守 `pptx` skill 中 PptxGenJS 必须用 Node 运行、生成后必须做 OPC 校验的要求。当 deck/PPT 需要插图、需要决定「图片当背景还是前景、放哪一半、配什么比例、怎么不遮挡文字、怎么写贴切的生图提示词」时，读取 `references/layout-composition.md`（图文混排方法论，配合 `ai-image` 技能的 generate.mjs 生图）。
+
+需要新增、总结、优化或复用 VI 模板制作流程时，读取 `references/vi-template-workflow.md`。当任务较复杂、需求较空、需要使用 VI 模板，或执行者可能缺少设计判断时，读取 `references/design-execution-playbook.md`，并按其中模板写出设计执行声明与评审结论。
+
+当用户要求更有设计感、更大胆、更高级、更独特、更有品牌记忆点，或没有现成品牌/VI 但需要从零建立视觉方向时，读取 `references/aesthetic-direction.md`。它只提供审美方向方法，最终仍必须遵守本技能的中文、结构、验证和评审流程。
+
+## 视觉模板库
+
+默认根据用户当前需求和已有品牌/设计上下文进行全新设计，不要把某个存量模板强行套到所有任务上。
+
+当用户明确要求使用历史成功风格、任务明显匹配某个模板，或缺少品牌上下文但需要一个成熟起点时，再读取对应模板文件。只读取相关模板，不要一次性加载所有模板。
+
+### ★ 编辑式最高原则（所有 VI 模板共享继承 —— deck/PPT 版式的最高标准）
+
+无论选用下面哪个 VI 模板，**deck/PPT 的版式都遵循「苹果/大疆产品详情页式编辑式」最高标准**（详见 `references/layout-composition.md` §0）：
+**图片作背景、文字作前景、需要数据时插图表、需要特写时插插图，不靠卡片墙 / 网格 / 表格划分区域。**
+- 每个内容页都有背景层（客户图 / AI 图 / VI 同色系渐变·纹理 + scrim），标题/要点/参数**直接浮在背景上**，不靠白底悬浮卡片分区。
+- 数据 → 图表（柱/饼/折线/进度环/参数胶囊/对比列），不堆表格/div 对比表；特写 → 插图（含透明背景前景切图）。
+- **卡片墙 / 网格 = 罕见例外**：仅真·并列指标矩阵且做成图表/指标面板浮背景时才用。**VI 模板只决定配色 / 气质 / 母题，不改变这条版式标准**——dashboard 型 VI 的"数据面板"也是图表/指标浮背景，不是白底卡海。
+
+**怎么选（按配色 + 需求匹配，给用户推之前先想清楚）**：把客户需求拆成三维——**行业属性 + 情绪基调 + 任何品牌/偏好色**，再映射到下面某个模板的**配色**。用户没明说颜色偏好时，按**行业惯例配色**兜底推荐：能源/电力→绿(verdant-grid)、军工/国防/政企工业→蓝(aegis-vector)、金融/物流/B2B 管理→暖白纸感(comfort-vision)、AI 模型发布→红(ember-prism)/橙金(amber-prism)、影像/创作硬件→黑+红(obsidian-optics)、高端消费硬件→黑白极简(precision-horizon／深色版 -dark)、云/开发者/数据/安全平台→蓝黑(nebula-console／obsidian-xui)、通用 AI 产品/SaaS/官网→蓝白通透(aqua-glass)、AI 工作台/智能路径→紫(violet-meridian)、网络加速/连接/移动活力→红橙多彩(solar-relay)。
+
+**按配色速查**（一个模板可跨组；先定色系再看下面详条）：
+- **浅色/通透底**：aqua-glass(蓝白玻璃)、violet-meridian(紫白蓝)、ember-prism(白底红)、amber-prism(白底橙金)、verdant-grid(白底深绿)、aegis-vector(白底兵工蓝)、precision-horizon(灰白黑极简)、comfort-vision(暖白纸感)、solar-relay(暖白多彩)
+- **深色/科技底**：nebula-console(蓝黑)、obsidian-xui(更黑 XUI)、obsidian-optics(黑+信号红)、precision-horizon-dark(黑+暖橙产品剧场)
+- **暖色/活力**：solar-relay(红橙多彩)、ember-prism(红发布)、amber-prism(橙金亲和)、precision-horizon-dark(暖橙性能)、comfort-vision(铁锈橙纸感)
+- **冷色/理性**：aqua-glass(蓝青)、nebula-console／obsidian-xui(电光蓝)、violet-meridian(紫+钴蓝)、aegis-vector(兵工蓝)
+- **行业专用色**：能源绿(verdant-grid)、军工政企蓝(aegis-vector)、金融物流纸感(comfort-vision)、影像黑红(obsidian-optics)
+
+每条格式：**配色**（底色 + 主强调色 + 冷暖）｜**气质**｜**适合**｜**慎用/原创边界**。
+
+- `references/vi-aqua-glass.md` **浅蓝白玻璃**：冰雾白通透底 + 近黑蓝文字 + 蓝紫/蓝青渐变行动信号（浅色冷调）｜清澈、可信、轻盈、现代、专业不冰冷、编辑式图文融合｜AI 产品/通用 SaaS 官网/AI 模型多模态产品页/知识库/协作/数据分析/云服务活动页/官网首屏/deck（玻璃作前景浮层面板、非卡海）｜慎用于高风险运营台、重金融风控、强权威政企、儿童娱乐、暗黑游戏、奢侈品牌；不复刻火山引擎等真实品牌的页面结构/文案。
+- `references/vi-violet-meridian.md` **紫曜经线**：冷白底 + 近黑紫文字 + 主紫 `#7c3aed` + 钴蓝状态信号（浅色冷调偏紫）｜清爽、智能、清晰科技、路径感、编辑式图文融合｜AI 工作台/开发者工具/任务编排/智能路径与推理链路展示/智能建议页/图标配色方向（路径与节点打底、数据图表浮前景）｜不复刻 Codex/OpenAI 的名称、标识、图标轮廓；慎用高风险运营台/重金融风控/温暖手工感，别堆白底三栏面板卡海。
+- `references/vi-ember-prism.md` **棱焰智能**：暖白底 + 黑色信息锚点 + 红色主视觉 + 少量橙火花 + 蓝紫能力点缀（浅底暖强调、发布感）｜明亮、前沿、开放、工程可信、有发布感、编辑式图文融合｜AI 科技公司官网/模型发布/多模态产品/通用 SaaS 官网（红色主视觉作背景、数据图表浮前景）｜不复刻 MiniMax 等真实 AI 公司的名称/产品名/页面结构；卡片仅作图表/指标面板浮背景例外、不堆白底卡海。
+- `references/vi-amber-prism.md` **琥珀棱镜**：暖白底 + 黑文字 + 主橙 `#ff7a2f` + 金黄高光 + 少量红（浅底暖橙、更亲和）｜明亮、温暖、开放、工程可信、轻发布感、编辑式图文融合｜AI 科技/模型官网/多模态产品/通用 SaaS 官网，温暖亲和发布感（比 ember 更暖更柔）｜用户明确要更强红色发布感时改用 ember-prism；卡片仅作图表/指标面板浮背景例外、不堆白底卡海。
+- `references/vi-verdant-grid.md` **绿脉电网**：白底 + 黑色权威文字 + 深绿主色 + 浅绿分区 + 蓝色数字化信号（白绿、行业能源色）｜稳健、可信、清洁、公共基础设施感强、编辑式图文融合｜能源/电力/电网调度汇报 deck、智能电网/虚拟电厂/储能态势、电力经营分析与年度总结（电网场景图/线稿打底、负荷与碳减排数据图表浮前景）｜不复刻国家电网等真实能源企业的标准色手册与 PPT 版式；慎用消费娱乐/潮流奢侈/科幻蓝黑，别堆绿色表格卡海。
+- `references/vi-aegis-vector.md` **蓝盾矢量**：白底 + 黑色中文大字 + 兵工蓝导航/焦点块 + 浅蓝光电高光（白蓝、行业军工政企色）｜稳定、权威、工业、科技准星感、编辑式图文融合｜央企工业/国防科技/装备制造/光电雷达/智能制造/政企汇报 deck·能力平台·展厅（装备/工厂/光电画面作背景、图表化指标浮前景）｜不复刻中国兵器工业集团、北方工业等真实军工央企的标识/官网版式；消费潮流/轻 SaaS/医疗金融柔和场景改选他法。
+- `references/vi-precision-horizon.md` **精密地平线**：祖传灰白底 + 近黑文字 + 克制黑白灰盘 + 可按产品换的行动蓝/暖金点缀（浅色极简）｜产品主角、图文融合编辑式、材质光、高级克制｜高端产品详情页/硬件官网/产品发布页/影像/智能硬件/产品介绍 deck（Apple·DJI 图文融合气质）｜不复刻 Apple/DJI 的字体、产品摄影、页面结构；非产品对象的抽象 SaaS 改选他法。
+- `references/vi-comfort-vision.md` **舒适视觉**：雾灰纸色暖白底 + 深墨绿文字 + 克制铁锈橙信号（暖中性纸感）｜克制、舒适、纸感、工程笔记感、基础设施感、管理层可读、编辑式图文融合｜经营分析/管理层编辑式数据展示 deck、运营/风控/资金/合规的数据叙事页（图表+前景论点）、物流/能源/工厂/公共基础设施对外汇报、高密度决策叙事｜别当后台软件用——密集表格行操作/增删改查的真后台界面不适合；别把“舒适视觉”当品牌名，别复用旧样张港口内容（除非任务本身是港口/物流）。
+- `references/vi-nebula-console.md` **星云控制台**：深空黑半透明底 + 冷白文字 + 电光蓝 `#3aa7ff`（少量紫做空间光）（深色冷调）｜蓝黑、理性、可信、未来感、工程感、可商用、编辑式图文融合｜AI 平台/云服务/数据基础设施/网络安全/科技公司官网与发布 deck、深色科技编辑式数据叙事（图表+前景文字+节点拓扑）｜别铺透明卡海——密集行操作的真后台监控软件/长文内容站/温暖消费品牌不适合；保持商用品质与中文可读，别做成纯电影道具/游戏 HUD。
+- `references/vi-obsidian-xui.md` **黑曜界面**：极黑底 + 冷白文字 + 电光蓝 `#33b8ff`（比 nebula 更黑更锋利）｜黑色、锋利、精密、未来、系统在线、科技强度高、编辑式图文融合｜比 Nebula 更黑更锋利的深色科技编辑式数据可视化（图表+前景论点+精密线框拓扑）、工业数据可视化/数字孪生/设备能力 deck/黑色科技官网、AI·安全·机器人·空间·工业产品展示｜别铺发光卡片矩阵/HUD 卡海——密集行操作的真后台软件/长文内容站/温暖消费品牌不适合；必须保证深色阅读面中文可读，别做成游戏 HUD/电影道具/廉价蓝光大屏。
+- `references/vi-obsidian-optics.md` **黑曜影像**：黑底 + 冷白主体 + 少量信号红 `#e21b2d`（深色冷调、红点睛）｜精密、锋利、专业、轻科技、高端影像硬件、暗场图文融合编辑式｜摄影器材/电影机/镜头/影像工作流详情页·发布页·监看调色·创作者硬件·HTML deck（画面铺底、参数视觉化图表浮前景）｜不复刻 RED/红龙等真实影像品牌，红色不做大面积背景；轻消费/医疗金融柔和/霓虹赛博改选他法。
+- `references/vi-precision-horizon-dark.md` **精密地平线·深色**：石墨黑底 + 冷白文字 + 暖橙 `#ff7a1a` 材质强调（黑橙/黑蓝产品剧场）｜专业、强性能、沉浸、高端、锋利不沉闷、暗场图文融合编辑式｜深色产品详情页/专业硬件发布页/高性能设备/黑色产品剧场/黑橙性能/黑蓝影像/iPhone Pro·MacBook Pro 深色气质｜别做成游戏 HUD、赛博朋克或真实品牌复刻；轻生活亲和产品改选浅色他法。
+- `references/vi-solar-relay.md` **日冕中继**：冷暖白底 + 深墨蓝文字 + 红橙日冕主轴(珊瑚/橙/日色弧带) + 青蓝网络 + 少量品红跳点（暖色多彩、活力）｜活力、连接、移动产品感、编辑式图文融合｜网络加速/VPN/连接/流量/安全/移动应用/活力科技官网与推广 deck（日冕弧带与网络路径打底、连接状态与速度数据图表浮前景）｜不复刻 Cloudflare/WARP+/1.1.1.1 的名称、标识、广告卡结构；慎用严肃金融政企/暗色硬件/低调奢侈，别堆套餐卡·广告卡墙。
+
+未来新增 VI 模板时，使用独立的 `references/vi-*.md` 文件，并按上面「配色 + 气质 + 适合 + 慎用」同一格式在这里登记、同时归入「按配色速查」对应色系。
+
+## 任务分流
+
+- **网页或落地页**：创建精致、响应式 HTML 页面。首屏必须直接体现真实产品、对象或服务，不要做空泛营销页。
+- **产品 UI 或应用界面**：创建高保真界面或可点击原型。若有源码、截图或 UI kit，先理解现有视觉语言再延展。
+- **HTML deck 或 PPT 风格演示**：先判用途。浏览器演示 deck 可持久化当前页并做视口自适应缩放；PPTX 导出 deck 必须是静态 16:9 页面，使用 1 起始编号如 `01 标题`，不使用 Tweaks、localStorage、postMessage、JS 缩放或翻页 nav。
+- **静态设计画布**：并排比较视觉方向、组件、字体、配色或布局方案。
+- **动画或演示 demo**：创建时间线或动效导向 HTML artifact，包含播放状态和控制。
+- **现有 UI 改版**：先检查现有代码和设计系统，再在保留产品识别度的基础上提升质量。
+
+## 工作流
+
+1. 明确目标、受众、保真度、约束、输出格式和方案数量。
+2. 先收集设计上下文，再创造视觉：读取相关代码、设计 token、截图、UI kit、品牌文档或组件示例。缺少关键上下文时要询问用户。
+3. 判断是全新设计还是使用存量 VI 模板。若使用模板，读取对应参考文件，并将视觉 DNA 迁移到用户领域。
+4. 选择任务类型，并写出简短设计执行声明：任务类型、上下文来源、是否使用 VI、读取的 reference、视觉系统策略、中文排版策略、Tweaks 计划、输出文件和验证计划。没有明确品牌/VI 时，必须先选择审美方向和一个可记忆的视觉概念，再进入 HTML 构建。复杂任务或空白需求必须先完成这一步，再构建。
+5. 对浅色、玻璃、通透、渐变类需求，先明确本次视觉系统：背景渐变方向、主 surface 不透明度、辅助浮层透明度、边缘高光、主按钮渐变、状态色和文字对比策略。若这些策略说不清，先不要生成页面。
+6. 构建一个主要 HTML artifact，文件名要清晰。大型工作可以拆分辅助文件，但最终入口要明确。
+   若预期导出 PPTX，按**三层（背景 / 前景 / 文本）**思维排版即可——**分层现在由导出脚本自动完成，无需逐个标注**（`tagLayers` 截图前按结构判定）：
+   - **文本**（含卡内、SVG `<text>`、散字）→ 自动提到顶层**原生可编辑文本框**，永不烧进图。
+   - **前景** → 离散视觉块（带底色/边框/阴影的块、卡片、色块、选项卡、`<img>`/`<svg>`/图表）只要非全幅且够大，**自动**逐元素切图成**独立可编辑图片对象**（可拖拽/复制/删除）；去嵌套（只切最外层，内层烘进外层切图）。带底色的药丸/标签其**底色留切图、文字自动提顶层**。
+   - **背景** → 仅 AI 氛围底图 + CSS 纯色/透明/渐变的页/section 级基底 + scrim → 整页截图垫底，不可编辑。
+   - override（仅自动判定不符时用）：`data-pptx-layer="foreground"` 强制某块为中层切图；`data-pptx-export="ignore"` 让元素保留烧进底图。
+   这样 `hybrid` 做到「背景当底图、前景每块独立可编辑图片、文本是真文本框」，且不依赖标注齐全。细节见 [references/export-pptx.md](references/export-pptx.md)。
+7. 当用户需要探索方案时，通过 Tweaks 或页面内控制暴露有意义的变体。设计探索默认提供 3 个以上方向或可调 Tweaks，除非用户明确只要单案。优先用一个主文件切换方案，而不是散落多个无关联文件。
+8. 对根 HTML 文件运行 `scripts/check_ui_artifact.py`；若预期导出 PPTX，必须改用 `scripts/check_ui_artifact.py --for-pptx-export <html>`，先拦截重复 `<head>/<body>`、裸露 CSS、坏结构和导出风险。对 Markdown/HTML 运行 `scripts/check_language_policy.py`。发现阻断问题或不必要英文时先修复。
+9. 使用浏览器或 `scripts/browser_check_ui_artifact.mjs` 做桌面与移动端截图检查，确认控制台错误、横向溢出、按钮触达、中文断行和核心屏幕标签。脚本不可用时要记录限制，并用可用截图方式替代。
+   **固定画布产物（deck / app 固定框 / canvas）额外过一道确定性构图闸门**：先 `export_pptx_from_html.mjs --measure-only` 写 `layout-report.json`，再 `layout_balance.py` 判重叠、截图夹带文本、空半、挤角和覆盖率。出现 `ERROR` 必须按它指出的页与缺陷改 HTML 再判，直到 PASS；`WARNING` 是构图改进建议，通常要人工评审决定是否继续优化。响应式网页不套这道（留白/滚动合理），仅走上面的 browser_check。
+10. 交付前写简短评审结论：配色、字色、信息密度、留白、移动端、是否通用 AI 味、是否需要返修。脚本通过不等于设计通过；必须结合截图判断。浅色玻璃风还要检查是否只是半透明卡片、渐变是否有层级和方向、文字是否在渐变和玻璃上仍清楚、移动端是否因为渐变/模糊导致脏、糊、低对比。
+11. 若评审发现配色、结构、排版、移动端或视觉完成度问题，先修改再复跑检查。交付时简短说明输出路径、完成内容、验证结果和必要注意事项。
+12. 若交付 PPTX，必须说明可编辑程度：`flat` 为全图不可编辑；`hybrid` 为三层——背景整页底图不可编辑、前景每个元素是独立可编辑图片对象（可移动/缩放/替换）、文本是原生可编辑文本框。用户要「可编辑」时用 `--mode hybrid`（默认 `flat` 是全图保真版）。
+
+## 关键约束
+
+- 用户可见界面和说明默认简体中文；不要生成英文 UI、英文 deck 或英文评审报告。
+- 优先使用现有设计系统、源码、token 和组件；截图作为校验与补充。没有设计系统时，要声明假设并选择清晰、有观点的审美方向，不能退回默认 SaaS 模板。
+- 对需求很空或执行者没有审美上下文的任务，不允许直接写页面。必须先读取 `references/design-execution-playbook.md`，选择从零设计或 VI 模板路线，并写出可执行的视觉系统声明。
+- 色彩优先来自品牌或设计系统；需要扩展时可用 `oklch()`、`color-mix()` 或同色相明度/彩度变化生成协调层级。
+- 避免通用 AI 味：紫色渐变、**卡片墙 / 重复圆角卡片堆叠**（deck/PPT **默认不用"白底卡海"分区**——走编辑式「图打底 + 前景浮层」，见上「编辑式最高原则」；卡片仅作真·并列数据的**图表/指标面板浮背景**例外用、非装饰卡海）、左边框强调卡、无意义数据、占位假文、纯 SVG 假图、过度常见字体栈（如 `Inter` / `Roboto` / `Arial` / `Fraunces` / 系统默认字体栈）、不必要表情符号、装饰性堆砌。
+- 玻璃浅色风不是简单的 `rgba + backdrop-filter`。必须把玻璃理解为“渐变光感 + 半透明层级 + 边缘高光 + 清晰文字”的系统：背景用低对比冷暖渐变建立空气感，主面板用更高不透明度保证阅读，按钮和状态用有方向的蓝青渐变引导行动。不要把所有卡片做成同一种毛玻璃。
+- 渐变必须服务信息结构。可以用于背景光、面板边缘、主行动按钮、状态轨道和视觉焦点，但不能堆成装饰性彩色雾团。浅色风格要保持干净、克制、可读。
+- 不要填充无意义内容。每个区块、指标、图标和文案都必须服务用户目标。
+- 小产物可以单文件交付；大型原型应拆分入口、样式、脚本或组件文件。根 HTML 超过 1000 行时优先考虑拆分。
+- 重大修订和对比实验要保留旧版本，使用 `v2`、`iteration-2` 或清晰命名的新文件。
+- 禁止使用 `scrollIntoView`；需要滚动时使用其他 DOM 滚动方法。
+- 使用 React + inline JSX 时，采用固定版本和 integrity 的 React/Babel script tag（具体三条标签已抄录于 `references/starter-components.md`，以本仓库这份为准，不依赖 `claude_design.md`），不要用未固定版本；不要混用 `type="module"`，不要使用全局 `const styles = {}`。
+- 固定尺寸 deck、演示和视频类产物必须实现 JS 缩放，确保任意 viewport 都能完整显示。导航控制要位于可用区域。（**例外：导出 PPTX 的 deck** 是静态导出目标，导出脚本自处理尺寸/分页——无需 JS 缩放、翻页 nav、Tweaks、localStorage。）
+- **deck 排版用 CSS Grid，不要逐元素绝对定位**：每张 slide 是一个 grid 容器（`display:grid` + 统一 padding + 按版式选 `grid-template`/`align`），让布局引擎铺满画布、产生均衡构图；`position:absolute` 仅用于全幅背景图+浮层文字。详见 `references/layout-composition.md`。
+- 幻灯片和高级屏幕容器添加 `data-screen-label`；幻灯片编号从 1 开始，并包含中文标题。
+- `1920x1080` deck 正文通常不低于 24px；移动端可点击目标不低于 44px；打印/文档正文不低于 12pt。单个 deck 背景色控制在 1–2 种，避免每页换底色。
+- **deck/PPT 每页构图以「强主视觉 + 短文案 + 合理留白」为先**（美感优先口径以 `references/layout-composition.md` §0/§0.6 为准——**「乱」比「空」更糟**，目标不是把每个角落填满，而是一眼看见主视觉与一句重点）。视觉焦点放黄金分割≈0.618 或三分线，横版 16:9 善用左右分栏/上下分带互补。构图闸门只**确定性抓真缺陷**：真重叠、截图夹带文本、**内容严重飞出画布（可见 <20% = 观众看不到，`layout_balance --strict-offcanvas/--catastrophic-only`）**——**不以占空比逼填、也不逼改颜色**（占空/对比度是 WARNING 提示不拦）。**别为躲重叠而缩字/留大白，也别为凑覆盖率硬塞图文致挤压**；留白是给主体呼吸的有意负空间。
+- **deck/PPT 上屏文案承载实质**：每页文字从内容源（如工作流 `outline.json` 的 key_point/evidence）浓缩，**每条要点须承载一个具体主张/事实**（专业、精确、并列、可验证），禁止"重要/高效/赋能/助力"等空话填充——slide 是把干货浓缩、不是删成空壳。构图均衡绝不能靠"放大字/塞大图"凑覆盖率而牺牲内容密度；**页显空先补实质内容/改用更密版式，别塞 airy 图填空**（薄文字+空图＝双重空）；**deck/PPT 默认走编辑式前景浮层（要点浮在背景上）而非卡海**——真要用图表/指标面板作容器时每张装满实质、别空卡（见「编辑式最高原则」）。
+- 讲者备注仅在用户明确要求时添加，且必须随 slide 变化同步。
+- 需要导出 PPTX 时，三层（背景/前景/文本）**自动分层**，正常写语义化 HTML 即可：复杂渐变/玻璃/阴影/氛围底图自动留背景，离散视觉块（卡片/色块/选项卡/图标/插图/图表）自动切中层，文字自动提顶层可编辑。标注仅作 override（`data-pptx-layer="foreground"` 强制成块、`data-pptx-export="ignore"` 保留烧进底图）。不要为了“全可编辑”牺牲 `ui-design` 的视觉质量。
+- 添加 Tweaks 时，先注册 message listener，再发送 `__edit_mode_available`；根 HTML 中必须且只能有一个合法 JSON 的 `/*EDITMODE-BEGIN*/ ... /*EDITMODE-END*/` block，并用 `__edit_mode_set_keys` 持久化修改。新产物推荐发送 `{ edits: patch }`，旧产物的 `keys` 仅作兼容。
+- 尊重版权。除非用户拥有权利，不要复刻他人独特专有 UI；应基于用户目标创造原创设计。
+
+## 配套脚本
+
+- `scripts/scaffold_ui_artifact.py`：生成 `webpage`、`app-ui`、`deck-browser`、`deck-pptx`、`deck`、`canvas`、`animation` 单文件 HTML 起始模板；`deck-pptx` 是静态 PPTX 导出起点，旧 `deck --pptx-export` 仍兼容。
+- `scripts/check_ui_artifact.py`：静态检查 HTML artifact 的结构、协议、占位内容、deck 机制、Tweaks 和 React/Babel 固定版本；并**确定性 WARNING** 提示两类 AI 味残留——**过度常见字体栈**（Inter/Roboto/Fraunces 当主字体；末位 Arial/Helvetica 兜底不误报）与**左边框强调圆角卡**（border-left + border-radius 共现）。这两条是 WARNING 级（不改退出码/不硬拦），把「避免通用 AI 味」铁律从 prose 落成机械背书，交付评审须据此复核。
+- `scripts/check_language_policy.py`：检查 Markdown/HTML 中是否存在不必要的长英文可见文案。
+- `scripts/browser_check_ui_artifact.mjs`：用浏览器打开 HTML，输出桌面/移动截图、console/overflow/button 检查 JSON，用作本地替代预览验证流程（**响应式网页**走这个）。原型/变体页需要强制 Tweaks 时传 `--require-tweaks`。
+- `scripts/export_pptx_from_html.mjs`：用 Playwright 截图与 PptxGenJS 生成 PPTX，支持 `flat` 和 `hybrid` 导出。`hybrid` 三层**自动分层**（`tagLayers` 截图前按结构判定：离散块自动切中层、文字自动提顶层、其余留底图），无需逐个标注。输出截图、manifest、导出报告和 OPC 校验。带 `--measure-only` 时**只渲染量构图、写 layout-report.json**（不截图/不切图/不出 pptx），供构图闸门在 HTML 层廉价循环；再加 `--with-bg-shots` 顺带落两张整页截图 + report 带 textRuns（供像素级文字可读性门采样）：`slide-NN-background.png`（背景态,隐前景+隐文字,给 `fgParent=null` 直接压背景层的文字用）与 `slide-NN-foreground.png`（foreground 态,隐文字、卡片/SVG/渐变/图片原样渲染,2026-07-03 新增,给 `fgParent` 非空的卡内/前景块内文字用——此前这类文字被整体跳过,真机占比高达 81%,是可读性检测的最大盲区）。
+- `scripts/layout_balance.py`：**构图均衡确定性闸门**，硬门（ERROR）= **真重叠**（主门，报元素 + 重叠范围 + 归一化坐标 0–1）+ **截图夹带 HTML/SVG 文本** + 整页无内容且无真实视觉；软门（WARNING）= 页面过空、空半/挤角、空心卡片、文本显著裁切、字号偏小、对比不足和轻微越界。它像 zod 一样**只报问题（`【问题类型】页 · 位置 · 量化范围`）、不替你定方案**。读 `layout-report.json` / `export-manifest.json` 逐页判。
+  - `--strict-offcanvas`：**内容严重飞出画布**（元素可见部分 < 20% = 观众根本看不到，如轨道被大图撑爆致标题正文跑到 x≈0.99）升为 **ERROR**（默认仅 WARNING）。
+  - `--catastrophic-only`：**只**报「内容不可见灾难」（严重越界 + 无真实视觉的空页），**抑制**重叠/占空族噪声——供导出阶段做**回归安全的几何硬门**（不误伤只有良性相邻/嵌套重叠的干净 deck）。治本仍在 `layout-composition.md` §0.7 的 `min-width:0` 骨架。
+  - `--ppt-strict`（2026-07-02，ppt 视觉门专用、默认关 = webppt 行为不变）：①重叠**去噪**——剔行盒贴边/膨胀父盒包含/行盒尾部（纵横）四类 box 模型伪象，只留真碰撞（真机 57 条→9 条全真）；②任何越界（含「超出下边缘」）升 ERROR；③**大空卡**（≥15% 页面、填充 <10%、且没被媒体块盖住 ≥70%——需 measure 产物带 mediaRects）升【空心大卡】ERROR；④（2026-07-03）**R6 导出加宽框幻影剔除**——重叠框按原点匹配回原始 textRuns 行盒重算，交叠归零的整条剔除（副标题导出框 h 达真实 2×、凭空压到下方卡片的假 ERROR）；⑤**R5 媒体卡内文字降 WARNING**——文字 ≥85% 落在含媒体前景卡内（caption/图内说明字，fgParent 断链才漏成重叠）降【媒体卡内文字】WARNING，可读性交像素门裁决；非媒体卡包含/骑边/text⊃fg 仍 ERROR（裸 `<img>` 自身作前景块时 hasMedia 恒 false，靠 fgRects 加性 `tag` 字段识别）。
+
+**ppt 工作流专属脚本（`/workflow ppt` 按序调用，细节 `--help`）**：
+- 素材摄取：`resolve_source_input.py` → `extract_source_assets.py` → `assemble_material.py` → `plan_source_layout.py`（每张客户图确定性算定 route/模板/文字落区/是否图生图）。
+- 设计文档（design.json）：`normalize_design_json.py`（归一化字段）→ `design_budget_check.py`（每页要点数/字数预算防溢出，纯文本层）→ `design_style_check.py` / `deck_visual_style_check.py`（构图风格枚举 / 卡片墙·表格墙倾向 / **视觉优先内容形状**：max_visible_words 对账 + 影像叙事页 ≤3 条短语 + 文章化倾向 WARNING——治「文本阅读型页面」；`speaker_notes` 讲稿字段不计上屏、不参与倾向扫描，经 deck 的 `<aside class="speaker-notes" hidden>` 导出进 PPT 备注栏）→ `design_repair_hints.py`（有 ERROR 时收敛成小批修复提示）。
+- 配图：`image_prompt_rewrite.py`（t2i 提示词**唯一生产/净化点**：绑定页面锚点，且与 image_plan_lint **共享黑名单词表**——design 字段/原 prompt 里的结构词·坏审美词在拼接前被剥掉或触发安全重组，产出保证过 lint。**2026-07-03 背景层去内容化**：背景 t2i/i2i 提示词不再拼 `Slide title:/Core message:` 字面正文与图表描述——Seedream 类文字渲染型模型会照着画出整版烘字假幻灯片（ai_p9 事故），页面绑定只靠去数字化/去句子碎片的场景名词锚）→ `image_plan_lint.py`（兜底验证；ppt 链路只扫 img_plan prompt 不带 `--outline`，webppt 仍扫 note；新增 slide_copy 检查：背景 t2i prompt 含页标题/正文标记/图表词 → ERROR）/ `generated_image_review_collect.py`（生成图语义复核汇总——**已屏蔽**：2026-07-02 用户裁决验证只走确定性脚本，ppt.yaml 阶段14-16 when:"false"，恢复方法见该处注释；生成图带字风险由前述提示词去内容化+lint 从源头拦）。
+- 页/素材闸门：`deck_pages_check.py`（分批页数完成度；`--check-order` 额外查 `data-screen-label` 编号在 DOM 中单调递增，错乱=导出播放顺序错）/ `source_usage_check.py`（客户图是否全用上；规划 `usage_intent:discard` 的弃用图豁免；`--layout-intent-only` 单跑【版式违规】——contain 类客户图被铺成 `.bg-img`/CSS 整页背景 → ERROR 进视觉门**可修档**驱动修复，2026-07-03 第4页「影子标题」事故：识图/规划都判 contain、build 仍铺背景，prompt 拦不住靠确定性比对）。
+- 像素/图表闸门（2026-07-02 新增，逐页体检产物）：`text_readability_pixel.py`（**像素级**文字压图可读性——CSS 对比度在图片背衬上物理测不准，按 textRun 矩形采真实像素（`fgParent=null` 采背景截图、`fgParent` 非空采 foreground 截图，2026-07-03 补全卡内文字覆盖面），≥35% 采样点对比 <3.0 → ERROR + 建议 scrim/移位/换色；**分段局部判定（2026-07-03）**：矩形横切 6 段，任一段失败率 ≥70% → 升 ERROR/【文字局部压图不可读】——治「列表行一半压平板黑边框、整框平均被稀释到不报」；装饰大序号/被媒体块盖住的 `fgParent=null` 文字自动豁免；缺 PIL/截图响亮 SKIP 不阻断）/ `chart_sanity_check.py`（SVG 图表**数据一致性**：百分比柱高与数值排序颠倒→ERROR、标签估宽超出所属图形→ERROR；复杂图 fail-open）。
+- **最终裁决**：`visual_quality_gate.py`（有界视觉质量门，聚合 image_plan_lint / source_usage / deck_visual_style **+ 几何 `layout_balance --ppt-strict` 全量 + text_readability_pixel + chart_sanity_check**；生成图语义复核（LLM 识图）已屏蔽出硬门、仅信息性记录——门只吃确定性脚本信号）。质量门循环**起头先 `export_pptx_from_html.mjs --measure-only --with-bg-shots`** 渲染 `layout-report.json` + 背景截图，几何/像素门才判得到。分档：**lint/素材=硬门**（直接 halt）；**几何/风格/像素/图表=可修门**（fast/best 统一驱动 ≤2 轮 repair 修复，2026-07-02 由 3 轮调 2 轮且开放 fast；达轮数仍不净 → **带残留放行**（`visual_quality_ok` + `visual_quality_residual.md` 并存）；「内容不可见」零容忍由**导出阶段的 catastrophic 硬门兜底 halt**，绝不因放行出货不可见 deck）。报告 `visual_quality_report.md` **ERROR 行提头再截断**（防长报告尾截裁掉前几页缺陷）。deck_visual_style_check **只在质量门里跑**（导出阶段不再同参双跑）。
+
+使用任何脚本前，先运行 `--help` 查看参数。