cs-build-ui-mockup

根据计划构建可点击的模型

书面计划无法表达视觉焦点。 它无法表达屏幕顺序、位置、层级，也无法说明一组选项是否完整。这些恰恰是容易出错的地方，反复阅读笔记也找不出问题——客户认可了文字，看到屏幕后却提出完全不同的意见。

这项技能会将计划转化为可供他们查看的内容，开展能揭示差异的评审，并将发现的问题写回 CodeSpring。

它在流程中的位置：

cs-build-plan-app  or  cs-build-import-codebase        (map + notes exist)
        │
        ▼
   cs-build-ui-mockup   ← you are here
        │            build it, show it, feed corrections back
        ▼
  cs-build-create-prd → cs-build-create-tasks → cs-build-feature

在 PRD 之前运行。 根据一份没人看过的计划生成 PRD，只会把误解写得更详细，也会让纠正起来更加昂贵。

阅读：codespring 技能中的 references/project-state.md、references/pitfalls.md，以及本技能自己的参考资料——

参考资料	何时阅读
references/design-system.md	编写任何 CSS 之前。 了解令牌架构、比例、圆角关系、品牌替换，以及浅色／深色模式。
references/review-method.md	展示给任何人之前。了解如何开展不受干扰的评审、模型能可靠发现哪些问题，以及如何将修正写回。

如果运行环境支持，也请加载 Anthropic 的 frontend-design 技能（https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md）。它提供了让成品独具特色而非流于模板的方法；这里的 design-system.md 则是它所依托的结构。如果无法在此环境中安装技能，请阅读该 URL 并直接遵循其中的指导。

---

0. 检查计划是否已准备就绪

bash ../codespring/scripts/fetch-project.sh --out /tmp/cs-state
node ../codespring/scripts/state.mjs       /tmp/cs-state

你需要附有说明的核心功能。没有说明就无从绘制——屏幕的内容、状态和规则都写在说明里。

• 没有地图 → 用错了技能。先运行 cs-build-plan-app（无代码）或 cs-build-import-codebase（已有代码）。
• 有地图，但说明过于简略或缺失 → 说明这一点，并先补全说明。只根据卡片标题构建模型，就得靠想象补全一切，而且什么也测试不了。
• 已经生成 PRD → 仍然值得执行，但要明确说明，修正之后需要重新生成 PRD。

1. 开始绘制前，先明确需求

结合说明和使用者，敲定以下事项。它们是每项视觉决策的依据：

• 谁会使用它，以及这会带来哪些限制——年龄、能力、使用环境、设备，以及他们的耐心程度。
• 主屏幕的唯一核心任务。
• 产品最令人印象深刻的时刻。 大胆的设计应集中于此；其他一切都应保持克制。
• 已有品牌——配色、字体、标志，以及需要对齐的现有产品。
• 客户提供的任何参考资料。 如果他们指定了设计方向，就严格遵循——他们的要求优先于你原本会采用的任何默认方案。
• 采用浅色、深色还是两者兼有，以及默认模式。

如果提供了参考图片，请明确提取其中的设计元素，并记录提取结果：以命名的十六进制值列出调色板、圆角比例、字体搭配、间距节奏，以及值得借鉴的两三个结构模式。然后说明你刻意不采用哪些元素，以及原因。参考资料能说明他们喜欢什么，但不是要求照搬的规范——参考资料面向的受众往往并非他们的受众。

2. 选择最容易干净舍弃的最小技术栈

这是一个生命周期只有几天的沟通工具。它不是应用，也绝不能在无意间变成应用。

默认选择：用目标平台自身的惯用方式，尽快搭建出经过样式设计、配置好路由且可交互的页面——通常是带有实用型 CSS 层的脚手架 Web 应用。如果无需额外成本，可以采用与最终技术栈一致的方案，但绝不要为了追求技术栈一致而拖慢原型制作。 为原生应用制作 Web 原型很常见，也完全没问题；重点是呈现屏幕界面。

不需要后端、数据库、身份验证，也不调用真实 API。 全部使用硬编码示例数据。

将原型放在单独的目录中，并明确命名为 mockup/，再用一句话说明它是临时的。

3. 先构建设计系统

设计令牌尚未创建之前，不要编写任何屏幕。规范见 references/design-system.md，简要要求如下：

• 所有值都集中在一处。 组件中绝不出现十六进制颜色值、像素值、圆角值或字体栈。整个品牌重塑只需修改一个文件。
• 从一开始就同时支持浅色和深色主题， 而不是事后补上。事后添加深色模式就意味着要重新检查每个屏幕。
• 只使用一套间距、一套字号、一套圆角比例。 圆角应经过深思熟虑，彼此协调——参见参考文档。常见问题是卡片圆角设为 28、按钮设为 6、输入框设为 12，却说不出理由。
• 颜色要具有语义，而非描述具体色彩。 使用 --surface、--ink、--accent，不要使用 --blue。语义化命名才能让更换品牌成为可能。

然后，按照 Anthropic 的 frontend-design 技能执行两轮流程：规划令牌集合（4–6 种命名颜色、展示和正文字体、布局概念，以及一个标志性元素），根据需求简介审视该方案，修改所有看起来像通用默认值的部分，之后再编写代码。

4. 构建屏幕界面

每项核心功能对应一个屏幕，另外再加上最重要的一条完整流程。 不要实现每个子功能；只需足以清晰呈现产品形态。

以下要求不可妥协，因为每一项都曾在实际评审中造成问题：

• 使用真实文案。 绝不使用 lorem ipsum。错误的措辞正是你想要尽早发现的问题之一，而占位文本会将其完全掩盖。
• 使用合理的示例数据。 名称和数字要看起来真实。“坐站力量训练 · 10 分钟 · 2 级”能暴露问题，“项目 1”则不能。
• 控件必须能显示交互反馈。 点击后毫无反应的选项标签看起来是坏掉了，而不是静态的；你会因此浪费评审时间。点击后会改变的硬编码状态就足够了。
• 绘制空状态和首次运行状态。 这两种屏幕最容易被忽略，也最容易让非技术用户觉得“这东西坏了”。
• 每个带有详细内容的列表项都必须可以打开。 无法打开的列表让人无法信任，而“点进去就能看到”正是原型要揭示的问题假设。
• 每组选项都必须提供退出选项，例如“其他”或“自定义”，除非该选项集确实是封闭的。固定选项一旦遇到真实用户，往往就不适用了。

5. 添加风格指南页面

添加一个 /styleguide 路由，将设计系统展示为一份可供客户反馈的成果：包含带名称和取值的调色板、实际使用中的字号比例、间距和圆角比例、处于各种状态的按钮和输入框、卡片，以及浅色/深色切换控件。

这能真正解决问题。客户可以针对设计令牌层面的内容进行具体审批或否决，比起逐个屏幕讨论，成本要低得多。它也能为后续开发正式产品的人记录这套系统。

6. 展示给任何人之前，先亲自检查

• 构建通过，且每个路由都能加载。
• 亲自看看。 为每个屏幕截图，并认真阅读。不要只验证 HTTP 200 就交付模型图。
• 每个屏幕的浅色和深色模式都能正常工作。
• 不显示任何带有框架品牌标识的内容——开发徽章、错误浮层、占位 favicon。非技术背景的客户看到这些，都会觉得“出问题了”。
• 质量底线：键盘焦点清晰可见、标题顺序合理、尊重减少动态效果设置、不出现水平滚动。
• Chanel 的规则：找出唯一一件可以删掉的东西。

7. 进行评审

完整方法见 references/review-method.md。核心内容如下：

把它展示给对方，然后闭嘴。 不要旁白讲解，不要解释你的推理，也不要事先为某个选择辩护。只要你开始解释某个屏幕，你衡量的就是自己的解释是否有说服力，而不是屏幕本身如何。

只提开放式问题：告诉我你会先做什么、有什么让你困惑、缺少什么、你会去哪里找 X。

如实接纳反馈，再单独分析它意味着什么。 “看起来糊成一团”虽然无法直接采取行动，但对方指着的东西确实存在。“我不知道这个显示的是什么”意味着图表没有标题。“这是可以点击的吗？”意味着某个屏幕承担了两种用途，却没有任何提示。

预期会有两轮。 当反馈从“这不对”变成“我更喜欢……”时就停止——此时你已经获得想要的理解，剩下的只是偏好，可以在构建过程中再敲定。

8. 将修正写回 CodeSpring

这一步让这项技能值得执行。 评审的产出不是 UI 待办清单，而是计划修正，它们应该写在构建时会读取的地方。

1. 把原因写进功能说明。 不要只写决定，也要写原因。“先展示锻炼内容，因为在展示任何内容之前先问两个问题，就等于在她看到任何内容之前让她做了两个决定。” 原因能防止下一个人撤销这个改动。
2. 在每个受影响的任务中加入 DESIGN REVIEW 块，这样构建该屏幕的人就能看到修正，而不必重新发现原来的错误。
3. 评审中发现的任何缺失内容都要变成新任务；如果它确实是用户要做的新事情，还要新建一个子功能。
4. 在说明中注明模型图是双方认可的 UI 参考，并说明如何运行。现在，它比对同一屏幕的任何文字描述都更有价值。

codespring mindmap note <coreFeatureId> --title "How it works — X" --text "$(cat note.txt)"
codespring task update <taskId> --description "$(cat task.txt)"
codespring task create --title "0.x.y — ..." --description "..." --feature <id> --priority high

9. 交接

→ cs-build-create-prd，现在计划反映了客户实际看过的内容。 然后运行 cs-build-create-tasks，再运行 cs-build-feature。

清楚地告诉他们交付了什么：模型图及其运行方法、样式指南、评审后计划有哪些改动，以及接下来会发生什么。

---

什么样的结果才算好

• 模型图在 PRD 之前就已存在。
• 先构建设计系统，所有值集中在一个地方，浅色和深色模式都能正常工作。
• 存在 /styleguide 路由，因此品牌讨论可以围绕设计令牌展开。
• 使用真实文案、可信的数据、会响应操作的控件，并绘制空状态。
• 每个带有详情的列表都能打开；每个枚举选项都有退出途径。
• 展示时没有旁白讲解，并提出开放式问题。
• 每项修正都变成了说明中的原因和任务块，而不是私下记下的待办清单。
• 在说明中注明模型图是双方认可的 UI 参考。
• 至少发现了一件单靠阅读计划绝对不会发现的事情。 如果什么都没发现，说明模型图太含糊，没有实际价值。