从“讲不清”到“点得动”
每个原型都是单文件 HTML，双击即可打开；关键状态用 JS 演示，评审时可以直接验证流程、分支和反馈。
从团队代码库长出来的 UX 协作方法
把交互想法变成可评审、可提交、可复用的原型资产
这套工作流把团队代码库、Agent 约束、交互设计原则和 Git 提交流程串起来： 我们不再只靠口头描述方案，而是用自包含 HTML 演示状态，用 interaction-spec 写清逻辑， 再通过代码评审一起沉淀方法。
团队代码库
真实组件与业务上下文
AGENTS.md
项目边界与协作规则
SKILL.md
交互判断原则
HTML + Spec
可打开、可评审、可复现
Git 提交与评审
每次讨论都能留下可追溯资产
Effect
这套方法带来的直接效果
它不是为了“让 AI 画一个页面”，而是把设计讨论从截图和口头描述，推进到可运行、可对比、可提交的协作物。
从“临时产物”到“团队资产”
HTML 表达界面，interaction-spec 表达行为契约；二者一起进 Git，讨论结论可以被复用、回溯和继续迭代。
从“个人经验”到“共同方法”
被反复纠正的设计判断，会沉淀进 skill；只属于项目的信息，沉淀进 AGENTS 或当前规格，团队越用越顺。
Workflow
一次需求从想法到提交的路径
核心顺序是：先拿够上下文，再做交互判断，先写规格再改原型，最后通过代码提交进入团队协作。
拉取团队代码库
原型工作区跟真实项目放在一起，方便复用业务术语、页面结构和已有设计上下文。
够用就停地取上下文
有截图就先用截图；需要源码时只读相关文件，避免为原型展开整仓分析。
用 skill 做交互判断
先判断对象归属、入口层级、主路径和 UI 轻重，避免只做到功能可达。
先写 interaction-spec
规格文档写清操作流程、状态变化和异常分支，成为评审时的行为契约。
再做自包含 HTML
所有 CSS 和 JS 内联，保留方案切换栏，关键状态可通过页面直接演示。
同步入口与说明
新增原型时同步更新索引和 README，让同事能从统一入口找到它。
走 Git 提交流程
方案、规格和讨论结论都进入 commit / review，后续迭代有迹可循。
Principle
这套工作流背后的原理
AGENTS.md 负责“这个项目怎么做”，SKILL.md 负责“交互为什么这么判断”。二者分层，才能既贴近项目，又沉淀通用方法。
项目层：AGENTS.md 约束协作边界
它告诉 AI：uxdemo 是设计评审原型工作区，不是生产代码；原型必须自包含； 改 HTML 要同步规格；新增原型要同步入口；演示控件不能混入正式 UI。
管什么
目录结构、交付物格式、文档同步、Git 可维护性、与主项目隔离。
解决什么
避免原型散落、行为和文档不一致、临时页面污染主项目。
原则层：SKILL.md 约束交互判断
它让每次设计先回答：对象属于哪一层，入口应该放在哪，当前页面主路径是什么， 以及这个任务应该用轻量提示、弹窗、抽屉还是独立页面承接。
核心判断
归属先于可达，位置暗示范围，主路径保持主路径，轻重匹配决策成本。
解决什么
避免入口放错层级、资产和运行态混淆、低频管理压过高频任务。
只做“功能可达”
- 入口哪里方便就放哪里
- 口头说清楚，页面不一定能演示
- 讨论结论散在聊天记录里
- 下次需求又从零开始争论
→
做到“心智正确 + 可评审”
- 入口层级先匹配对象归属
- HTML 能演示关键状态与异常分支
- 规格文档记录当前设计结果
- 经验沉淀进 skill，项目规则沉淀进 AGENTS
Assets
每次协作都会产出四类资产
这些资产都能被版本管理，所以设计讨论可以像代码一样被 review、diff、回滚和继续演进。
AGENTS.md
记录当前工作区的项目级规则：目录、交付物、约束和自检项。
SKILL.md
沉淀跨项目复用的交互原则，让 AI 和团队逐渐形成共同判断语言。
prototype.html
承载可打开的交互演示，重点表达流程、状态切换、异常分支与方案差异。
interaction-spec.md
作为交互行为权威描述，只写当前设计结果、操作反馈和异常分支。
Loop
团队越参与，方法越可靠
这不是一次性模板，而是一个会随着真实评审不断进化的闭环。
最关键的变化：同事指出“这个入口层级不对”时，我们不只是修一个按钮位置，
而是把背后的判断抽象成原则，让下一次类似设计自动避坑。
Co-create
同事可以怎么一起共创
参与方式不必很重：可以评审原型、补充规则、提交模板，也可以直接在 PR 里对具体交互提出修改建议。
三种最轻量的参与方式
- ✓看原型：打开 HTML，直接验证主流程、空态、错误态、禁用态和方案差异。
- ✓评规格：看 interaction-spec 是否能独立复现交互，不清楚的地方直接提 review。
- ✓沉淀判断：如果某类问题反复出现，把通用原则补进 skill，把项目规则补进 AGENTS。
这几个文件最值得一起维护
项目协作规则
uxdemo/AGENTS.md交互判断原则
uxdemo/skills/interaction-design/SKILL.md规格模板
uxdemo/templates/interaction-spec-template.md原型导航
uxdemo/index.html