docs(design): add HTML prototype input convention (H-412)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
chengma
2026-07-17 10:25:10 +08:00
co-authored by Claude Fable 5
parent da2e5effb5
commit 79fe234c29
6 changed files with 49 additions and 1 deletions
+1
View File
@@ -118,6 +118,7 @@ MVP 不做:
- 再看 `08-interaction-checklist.md` 的关联 IX 条目、状态和无障碍要求。
- 再看 `routes.md` 的页面职责。
- 最后看 `04-architecture.md` 的组件边界。
- 若 `docs/design/` 有关联原型,可作为页面结构参考;行为以交互清单为准,不复制原型代码(约定见 [`design/README.md`](design/README.md))。
做后端 API:
+2
View File
@@ -43,6 +43,7 @@ P0 交互必须使用本模板;非 P0 交互只有在高风险、不可逆、
- 触发方式:【点击 / 键盘 / 输入 / 手势 / 自动触发】
- 用户操作:【用户具体做什么】
- 服务 / 数据依赖:【引用 API、事件或本地模块合约;无则写不适用】
- 关联原型(可选):【`docs/design/` 下的原型文件,约定见[设计原型输入约定](design/README.md);无原型时写不适用】
**正常路径**
@@ -124,6 +125,7 @@ IX-001 与 IX-003 规则清楚、风险低,只保留总表条目;IX-002 是
- 触发方式:点击行内删除按钮。
- 用户操作:点击删除 → 在确认对话框中确认或取消。
- 服务 / 数据依赖:【API 合约中的删除接口】;错误格式以合约为准。
- 关联原型(可选):`docs/design/【条目列表页】.html`;无原型时写不适用。
**正常路径**
+1
View File
@@ -29,6 +29,7 @@
- [API 合约](api.md):前后端接口形状、错误格式、鉴权约定。
- [路由与页面结构](routes.md):页面路由、页面职责、组件归属。
- [交互清单](08-interaction-checklist.md):页面 / 组件交互、状态反馈、无障碍与验收证据。
- [设计原型输入约定](design/README.md):单文件 HTML 低保真原型的形态、权威性边界和工作流,用于生成交互清单。
- [当前实现状态](current-state.md):可覆盖的当前快照,记录仓库现实状态、可运行命令和下一步可做任务。
- [Agent 上下文清单](agent-context.md) / [`agent-context.json`](agent-context.json) / [`Schema`](agent-context.schema.json):按任务类型选择文档、用提交 / 文件 SHA 避免重复读取。
- [Gitea MCP 接入](gitea-mcp.md):可选的共享文档、Issue / PR 协调、安全配置和断连降级规则。
+43
View File
@@ -0,0 +1,43 @@
# 设计原型输入约定
> 本目录存放页面原型,作为生成[用户故事清单](../07-user-stories.md)和[交互清单](../08-interaction-checklist.md)的**一次性输入物**。
> 原型回答"页面上有什么";"该怎样表现"的权威始终是交互清单,不是原型。
## 一、定位与边界
- 原型的唯一用途:让 agent 据图枚举页面、控件和用户可见动作,产出 IX 总表草稿,避免凭空发明界面或漏项。
- **行为权威是[交互清单](../08-interaction-checklist.md)**:加载、空态、错误、权限、确认等行为以 IX 条目为准;原型与清单冲突时,以清单和[需求](../02-requirements.md)为准,或先对齐再动手。
- 原型不定义需求范围:原型里出现、但[需求](../02-requirements.md)未收录的功能,不能因为"图上有"就实现。
- **禁止把原型代码直接复制进生产实现**:原型没有组件抽象、状态管理和可访问性实现,实现时按[架构设计](../04-architecture.md)的组件边界重写。
## 二、默认形态:单文件 HTML 原型
- 一个页面一个 `.html` 文件,按路由或页面名命名,例如 `【items-list】.html`、`【login】.html`。
- CSS / JS 全部内联,零构建依赖,双击即可在浏览器打开。
- 低保真优先:结构和控件齐全即可,不追求视觉完成度。
- 使用语义化标签(`button`、`form`、`table`、`dialog`、`nav`),标签本身就是控件清单。
- 数据一律用假数据,页面顶部放固定横幅标注:`PROTOTYPE - 仅供枚举交互,非实现依据`。
- 需要演示空态、加载、错误等状态时,可用少量内联 JS 做状态切换按钮,对应交互清单状态表的行。
## 三、替代形态:SVG / 手绘草图
布局说不清、画得快时,可用 SVG(Excalidraw、Penpot、Figma 导出)代替:
- 文字必须保留为真文本(`<text>` 元素),不要导出为轮廓路径,否则 agent 读不到按钮文案。
- 分组 / 图层使用语义命名。
- 静态图只能表达一帧,状态与异常仍须在交互清单里逐项约定。
## 四、工作流
1. 用一两句话描述页面:有哪些区块、控件和主要动作。
2. AI 生成低保真原型(HTML 或 SVG),存入本目录。
3. 人工在浏览器查看并调整,直到布局与控件集合认可。
4. AI 据原型产出[交互清单](../08-interaction-checklist.md)的 IX 总表草稿,状态全部标【待确认】。
5. 人工逐条确认行为决策(优先级、状态与异常、无障碍),P0 交互按详情模板展开。
6. 对应 IX 条目在「关联原型」字段引用本目录文件;原型更新后检查受影响的 IX 条目。
## 五、维护规则
- 原型是输入素材,不追求与实现持续同步;页面显著改版时重新生成,而不是逐次修补旧原型。
- 已无对应页面或已完成使命的原型可以删除;删除前确认没有 IX 条目仍在引用。
- 本目录不放业务敏感数据、真实用户数据或生产接口地址。