Design WeChat Miniapp
把产品目标、视觉决策、工程落地和小程序验收串成一条有阶段门的流程。以用户任务和已选视觉目标为准；第三方 Web UI 工具只能作为可选助手，不能取代小程序方法和真机验证。
配套能力
- 在设计、实现或评审任何界面前，读取并遵守
ui-craft。 - 用户要求学习 App、竞品或截图目录时，读取
references/app-pattern-transfer.md，先完成结构迁移记录，再进入视觉探索。 - 涉及知识卡动画、教学图解、播放器或系统动效时，读取
references/knowledge-card-motion.md，先完成静态状态与 Motion Spec，再实现动画。 - 新产品、重设计或视觉探索时，先走 Product Design 的 context 与 ideate 流程。
- 已有界面审查时，先走 Product Design audit；实现后再做 design QA。
- 只有用户明确要求分享、发布或部署时，才进入发布流程。
不可跳过的阶段门
- 先明确用户、核心任务和成功结果，再讨论风格。
- 先完成用户流、页面图和状态矩阵，再产出高保真方向。
- 使用外部参考时，先写清“来源任务 → 可迁移原则 → 小程序改写 → 禁止复制”，不能把 App 名当风格提示词。
- 没有已选视觉目标时，生成恰好三套可见且明显不同的高保真方向；用户选定前禁止搭项目或写 UI。
- 选稿后先固化
DESIGN.md、Tokens、组件状态和禁止项，再实现。 - 知识卡或教学图解涉及动画时，先完成动画价值判断、无声分幕、状态板、静态替代、减少动画与弱网方案；没有可测试关键帧和失败退路时禁止实现。
- 实现时复用现有项目的组件、Token、路由、数据和命名约定。
- 开发完成后先审查、再精修；审查阶段不要一边诊断一边无边界重设计。
- 浏览器预览不能替代微信开发者工具和真机验收。
不要用 emoji、ASCII、占位框、CSS 图形、手写临时 SVG 或不匹配的素材冒充正式资产。不要在未经用户允许时发布或部署。
开始前
确定以下最小信息：
- 产品做什么；
- 目标用户是谁；
- 用户唯一最重要的任务；
- 目标是原生小程序、Taro、uni-app，还是仅做交互原型。
只有缺失信息会显著改变方案时才问一个问题；否则声明合理假设并继续。
如果已有代码库，先只读检查 project.config.json、app.json、package.json、页面、组件、全局样式、Tokens 和相似流程。使用 rg --files 与 rg，不要另起平行设计系统。
按以下优先级使用设计依据：
- 用户选中的视觉稿、截图或 Figma frame；
- 产品现有设计系统、品牌资产与组件；
- 用户明确提供的参考和约束；
- 当前 Brief 中声明的假设。
学习参考而不复制表面
用户提供 App 截图、竞品或参考目录时，不要从单张首页直接推断完整产品。执行以下最小流程：
- 为当前核心任务选择 2–3 个同任务参考，再选 1 个相反气质的参考检验取舍；
- 先均匀抽看入口、中段和终点，再连续查看目标任务的 5–9 张相邻截图；
- 识别任务时刻、信息拓扑、唯一主动作、操作前后状态、中断恢复和再次进入；
- 记录
来源 App → 任务时刻 → 可迁移原则 → 小程序改写 → 禁止复制； - 先画去品牌的灰度骨架，再使用当前产品的内容、品牌与小程序约束完成设计。
截图只能证明可见结构与状态，不能证明真实动效、触感、无障碍或运行时行为。Logo、吉祥物、标志性配色、品牌文案、独有图标、奖励系统和具有来源识别度的整屏组合都不得直接迁移。详细方法、任务索引与小程序改写表见 references/app-pattern-transfer.md。
八阶段工作流
1. Brief 与成功标准
输出一页以内的设计 Brief：用户、场景、入口、核心任务、业务结果、首批页面、技术目标、品牌约束和本次不做的内容。为核心任务写一句可验证的成功标准。
2. UX 骨架与灰度结构
先产出：
- 入口场景矩阵，包括搜索、扫码、分享、消息和直接打开；
- 信息架构与页面清单；
- 正常路径、异常路径、中断恢复与再次进入；
- 页面状态矩阵；
- 关键页面灰度线框和操作优先级。
先按任务选择信息拓扑：连续画布、同质列表、媒体货架/网格、自包含卡片或上下文面板。不要默认把每个区块都套成卡片。明确哪些页面属于保留导航的浏览态，哪些属于隐藏 TabBar、保留退出和进度的专注态；专注任务退出时保存上下文并提供恢复入口。
核心流程必须闭环：入口 → 操作 → 异常 → 恢复 → 成功 → 再次进入。
纯设计讨论可在对话中交付；进入实现时，把模板 assets/UX-STATE-MATRIX.md.template 复制为项目设计文档，路径优先遵循仓库约定，否则使用 docs/design/UX-STATE-MATRIX.md。
3. 三套视觉方向
使用 Product Design ideate 与 ImageGen 生成恰好三套方向。三套方案使用同一信息架构、同一核心任务和真实感内容，但在视觉气质、信息密度、层级策略和组件语言上明显不同。不能只做同一模板换色。
每套至少展示主屏和一个关键状态，标明适用场景与取舍。已有参考图时必须附带参考图，并指出只借了哪条结构原则、如何转译成微信小程序、哪些表面被刻意排除；不得只用文字描述替代视觉稿。展示三套方案后停止，等待用户选择。
如果任务仅是 UX 流程、审计或规范，可不生成视觉方向；仍不得在没有视觉目标时擅自实现新 UI。
4. 固化设计语言
选稿后读取 ui-craft，再使用 assets/DESIGN.md.template 建立设计事实来源。至少定义：
- 色彩角色与完整主色/灰阶；
- 字阶、行高和字重；
- 间距、圆角、层级、阴影和动效；
- 导航、胶囊区和安全区策略；
- 基础组件、业务组件、变体与完整状态；
- 图标、图片、文案和内容密度规则；
- 参考模式迁移记录、页面拓扑、浏览态/专注态和再次进入策略；
- 代码变量映射与禁止项。
先在灰度下确认层级，再上品牌色。主色只服务少数关键动作。
5. 知识卡动画与动效原型
先完成可独立理解和操作的静态界面，再增加动画。把动画分为按下/选择反馈、界面转场、知识解释、品牌庆祝四类；每段只承担一个主要任务。静态图加标注已足够清楚时，不制作语义动画。
知识卡按复杂度选择：卡内微演示、短图解、分幕专注课程。使用 assets/MOTION-SPEC.md.template 依次完成：知识事实 → 动画价值 → 无声分幕 → 状态板 → 关键帧/animatic → 渲染方式 → 完整/精简/关闭 → 弱网与失败 → 可测试交付。静态卡必须先提供标题、一句话结论、有意义的海报、时长/幕数和静态阅读入口。进入实现时，按仓库约定保存 Motion Spec；没有约定时使用 docs/design/MOTION-SPEC.md。
知识动画默认由用户触发、播放一次；多幕内容必须能暂停、继续、重播和退出，结束时停在可读终态。实现前读取 references/knowledge-card-motion.md；选定渲染方式前用目标项目做最小性能验证。包体、首播、帧率和内存预算必须来自项目约束或实测基线；没有证据时标记待测并写测量方法，不编造通用数字。
6. 小程序实现
优先沿用现有技术栈。新项目按以下规则选择：
- 仅微信、深度平台能力或性能敏感：原生 WXML/WXSS/TypeScript；
- React 团队、需要高速 H5 视觉迭代或未来多端：Taro + React + TypeScript；
- Vue/HBuilderX 团队或明确需要 uni-app 生态：uni-app + Vue + TypeScript；
- 只验证体验：先做移动端交互原型，明确标注它不是微信运行时。
实现核心任务需要的导航、表单、筛选、弹层、反馈、权限和状态，使用稳定的真实感 mock 数据。把 Tokens 映射到语义变量，组件至少覆盖默认、按下、选中、禁用、加载、错误、成功和只读状态。
用 motion_state、beat_id 和组件状态驱动动画，不用散落的 setTimeout 拼接流程，也不用逐帧 setData。页面隐藏、组件离屏或卸载时暂停并释放非必要资源；返回后等待用户继续。远程动画失败时保留静态结论、最后完成关键帧和重试入口。
复杂表单、日期、选择器等可复用项目已有小程序组件；不要把 shadcn、Radix 或 DOM/CSS 组件直接搬到微信运行时。技术选择细节见 references/technology-and-tools.md。
7. Audit 与 Polish
先做只读审查并按 P0/P1/P2 排序，再进入精修。审查至少覆盖：任务层级、信息拓扑、浏览态/专注态、再次进入、间距、排版、对比度、组件一致性、状态、素材质量、参考迁移边界和小程序平台适配。
视觉 QA 必须把选定视觉稿与实现截图放在同一个比较输入中，保持相同视口、内容和状态。修复可见差异后重新截图比较，直到关键差异关闭。使用 assets/QA-REPORT.md.template 记录证据、取舍和未解决项。
动画 QA 只对稳定语义关键帧做截图回归；对完整、精简、关闭、弱网和错误分别录屏。检查开始、暂停、结束、失败和再次进入，不能只评审一段理想录屏。
8. 平台验证与交付
浏览器或 H5 只用于快速迭代。实际小程序目标必须在微信开发者工具检查；面向上线的核心任务至少在 iOS 与 Android 真机各走一遍。
读取并执行 references/quality-gates.md。交付时给出可运行预览或导入方式、源码、DESIGN.md、状态矩阵、需要时的 MOTION-SPEC.md、视觉/动画 QA 结果、真机结果、已知取舍和一个明确的下一步。
工具分工
- Product Design + ImageGen：从 Brief 生成视觉目标。
- UI Craft：给出可执行的像素级规范与精修标准。
- 设计画布 + ImageGen：制作知识卡状态板、海报、关键帧和 animatic 参考；不替代运行时验证。
- Open Design：仅在其可用且适合当前任务时作为设计工作台；不是必选依赖。
- 浏览器：验证 H5 原型、交互和快速截图，不代表微信真机。
- 微信开发者工具或 Computer Use：验证小程序页面、路由、权限和平台行为。
- Playwright：可做 H5 快速视觉回归。
miniprogram-automator与miniprogram-ci：项目已配置或用户要求自动化时使用。
分享者的 Web UI 工具映射与取舍见 references/technology-and-tools.md。
沟通与交付规则
- 先说用户可见的决定、结果或阻塞，不先说内部工具。
- 每个阶段只要求一个明确决定；不要一次抛出长问卷。
- 视觉方向必须可比较，不能只是同一模板换颜色。
- 说明参考时，使用“借鉴某 App 的某个任务时刻和结构原则”，不要说“做成某 App 的风格”。
- 明确说明浏览器原型、开发者工具和真机之间的验证边界。
- 最终回复以一个具体、自然的下一步结束。
