ui-design-iteration

UI 设计迭代

范围

此技能可将 UI 从初稿推进到经过评审、可供移植的页面：当尚无设计时，它会基于现有参考重建初稿，将页面保存到磁盘并实时呈现，供人工指出问题，再把反馈转化为小型补丁，并验证最终结果。

它不会凭空构想页面的外观。视觉风格必须来自已有设计：用户选定的参考（第 0 步中的模板演示或在线网站）、用户信任的设计技能或设计 Agent、用户本人，或提取初稿时所依据的运行中产品。此技能会复用或重建该设计，将其落实到页面并进行评审；它绝不会根据一句简短需求绘制页面。

交付内容：一个实时静态初稿——包含一个 HTML 入口页面及其本地 CSS/JS 的初稿目录，无需构建步骤或网络连接即可在浏览器中打开，可直接调整，并能逐个元素讨论；此外还包括一系列经过评审的补丁。

明确不在范围内的内容：

• 从零起草。 根据一句简短需求生成页面，会一次性凭空决定布局、字体和配色，之后每一轮讨论都会针对无人决定过的选择争论。请先从参考（第 0 步）或设计源着手。
• 移植。 将初稿迁移到框架、模板语言或 CMS，是由相应代码库负责人处理的独立工作。不要搭建应用结构，不要接入数据，也不要“好心”代为迁移。

互操作：如何采用设计源

• 要求提供成品，而非建议。 输入必须是一个独立完整的 HTML 页面。如果设计以文字说明的形式提供，就将其一次性落实为文件，不要重新决定其中已经确定的内容。
• 转换，不要重新设计。 将设计系统、间距比例或令牌列表机械映射到初稿的 :root 区块中。如果两个设计源存在冲突，由用户选择其一；混合两套系统是这里代价最高的错误。
• 将缺失部分交回设计源。 如果设计没有规定页面所需某个界面的样式（例如空状态、对话框或错误状态），请咨询设计源，或从产品自身的组件中复制。切勿为填补空缺而自行创造视觉设计。
• 契约优先于默认限制。 references/audit.md 中的默认限制会终止迭代；design-contract.md 中记录的决定可以覆盖这些限制，因为审计只负责报告，不负责重新设计。无障碍检查是例外：任何设计决定都不能豁免对比度不达标的问题。

Agent 自带工具的要求

用用户自己的语言与其交流；以下问题仅以英语编写，以免技能分叉。

• 具备 Node 和网络访问权限的 Shell 仅在需要渲染你复制其源代码的框架模板时才需要（步骤 0，路线 A）。如果没有，请让用户运行并发送输出，或者直接保存模板的在线演示。
• Agent 可控制的浏览器 是截取参考演示的屏幕截图并进行测量、驱动应用以捕获其状态，以及检查命中测试所必需的。如果你有浏览器工具，请使用它；通过 Shell 脚本控制的无头浏览器（使用 DevTools 协议或 Playwright）也算。如果两者都没有，请让用户打开页面并发送屏幕截图，同时列出你无法自行执行的每项检查——跳过的检查不得标记为通过。
• 长时间运行的进程 是运行 scripts/draft_server.py 所必需的；路线 A 还需要运行模板的开发服务器。使用运行时提供的任何后台进程机制启动；端口由用户或环境选择，也可以用 0 分配空闲端口。记录你启动的每个进程的 PID——占用端口的进程可能是 Shell 报告的 PID 的子进程（$! 可能指向包装进程）；完成后准确停止这些 PID，并确认它们已退出（进程不再列出，端口不再响应）。切勿按名称或模式停止进程（例如 pkill next、按命令行匹配），因为机器上可能运行着同名的其他服务。
• 选择内容会在服务器运行期间，以 selection.json 的形式出现在草稿目录中。如果你在浏览器中操作页面，window.draftKit.snapshot() 会返回同一对象，而 window.draftKit.audit() 会统计渲染后的页面。如果两者都没有，请让用户读出面板的内容；并将其视为弱于文件的参考。
• 宽度在浏览器中设置：使用浏览器工具的视口，或由用户调整其浏览器窗口大小。快照会记录审核者看到的宽度。

工作流程

步骤	目标	输出
0 从参考创建草稿	将参考的设计语言应用于用户的内容和章节	绑定了调节项的 <name>.html
1 收集素材	确定设计并绑定令牌	<name>.html、一个 :root 块、design-contract.md
2 使其运行	让草稿的行为与页面一致	草稿运行时 + 已附加的审核面板，服务器正在运行
3 迭代	将更改拆分为已处理的小项	逐元素补丁，每项都能在差异中查看
4 审核并交付	达到限制或在契约中注明豁免，端口已就绪	草稿目录、其契约、锚点映射

如果已有设计，则跳过步骤 0。不要跳过步骤 1 中的令牌绑定。这能让步骤 3 更省事：绑定令牌后，大多数“更紧凑／更浅／更圆润”的要求都只需调整一个数值，无须重写。

步骤 0 — 参考现有设计进行初稿创作

选取一个设计精良的现有页面，将其设计语言应用到你的内容中；references/drafting.md 介绍了具体流程，references/sources.md 说明如何评估参考来源，并为没有偏好的用户提供了一份入门目录。

• 先写论点，再看参考。 将页面写成一系列论点及其证据，并记录实际存在的证据、图片和技术栈：结合用户要求的内容，确定页面的各个版块，以及哪些参考页面适用。
• 优先查找用户提供的来源。 询问用户偏好的库、模板网站、图库或网站，并在查阅入门目录之前先搜索这些来源。
• 由用户选择主要参考。 筛选出两到三个选项，展示给用户并让他们选择：选择参考页面，就是选择设计。用户让你代为选择时，选出筛选最充分的那个，说明理由，记录这是应用户要求所做的选择，并请用户在查看首稿时确认。
• 先研究，再测量，然后记录设计语言。 截图呈现结构；实时演示的计算样式则提供具体数值——字号比例、间距、圆角、调色板、动画时长——这些都将成为可调参数。列出参考页面的设计特点及其所在位置，包括图片、光晕及其在页面中的节奏，并标明标志性设计元素；每个版块都要符合这些特点。
• 复制代码；只有截图时才重建。 默认采用方案 A：使用模板的源代码；如果无法获取，则保存实时演示中渲染的页面及其样式表、字体、图标和图片，保留其标记和 CSS，并将可调参数绑定到 CSS 所提供的属性上。只有在没有可复制内容时，方案 B 才会重建局部。
• 内容决定结构；参考决定外观。 根据内容规划各个版块：适用时复制参考页面的版块，也可以从其其他页面中选取版块，或用其设计元素组合一个版块，且其形式应符合参考页面的风格，并与相邻版块有所区别——不要默认采用表格。每个版块的页眉布局、边框、背景、点缀色、插画和图标样式、色带宽度，都应与参考页面一致；每个标志性设计元素都要保留位置；不要自行选择颜色、字体或边框。文本属于用户；在用户提供自己的图片之前，参考页面中的图片仅作占位；证据——客户、引言、数据——绝不照搬。
• 展示前先对比。 以相同宽度截取初稿和主要参考页面：将复制的版块与原版对比，将组合的版块与设计语言对比，并检查整页的标志性设计元素、相邻版块的形式，以及没有图片的区块是否长于参考页面。首轮评审前修正偏差。

第 1 步 — 接收

• 一个草稿目录。 一个 HTML 入口页，CSS 内联或放在同一目录的本地文件中，不需要构建步骤，也不从网络获取任何内容——草稿必须能离线打开，并能在数月后从磁盘打开。
• 真实文案。 占位文本会掩盖两个关键问题：标题放不下，以及某个版块无话可说。
• 绑定调节项。 对于以页面形式交付的设计，将 13 个调节项放在一个 :root 块中——--gap、--fs、--ratio、--measure、--radius、--hue、--ink、--surface、--line、--edge、--shadow、--room、--dur，以及一个已声明的 --ease——并让所有可调值都由它们派生。对于从运行中的产品提取或从参考代码复制的草稿，样式表才是准绳：将面板绑定到它已有的自定义属性，并记录映射关系，而不是重写其 CSS。references/tokens.md 涵盖这两种情况。
• 枚举视图可能呈现的条件性界面。 references/intake.md 是接收设计的检查清单，可避免继承其遗漏。
• 在 design-contract.md 中记录约定（复制 templates/design-contract.md）：调节项及其来源、已在其他地方决定的内容、被否决的内容，以及哪些值只是示例。

第 2 步 — 让它运行

草稿要通过实际使用来评审。链接不得跳转，拾取必须是默认关闭的显式模式，菜单和对话框必须能够打开，而页面无法触达的每种状态都要在面板上提供一个按钮。

• references/live-draft.md — 可用草稿的规则、草稿运行时、捕获条件性界面、从运行中的应用提取草稿，以及通过查看进行验证。
• references/panel.md — 附加面板（将 templates/draft-kit.js 复制到草稿目录；一个配置块、一个脚本标签）、面板配置、面板发送的快照，以及服务器。

第 3 步 — 迭代

在追求速度之前，先让每项更改都能明确定位。

• 为每个版块和组件根节点添加锚点，使用稳定属性（data-node="pricing/plan-card#1"）。没有锚点时，“卡片”指的是模型猜测的对象，而猜错就要彻底重写。
• 读取选区，不要询问。 拾取会记录元素的 CSS 选择器、所属组件、计算后的值和文本对比度；标记可包含多个元素及评审者的备注；快照还会包含已移动的滑块和视口宽度。每轮更改前都要读取，并检查 ts。
• 每轮只调整一个维度——密度、层级或色温。一次调整三个维度，就没人能判断结果由什么导致，下一轮也会因此失去依据。
• 返回补丁，绝不返回文件。 评审单位是差异。即使结果看起来正确，只要差异涉及了旁边的元素、标题或无人要求修改的段落，就不合格。
• 更改前后都截图，并隐藏工具包（H），窗口宽度设为提出请求时的宽度；如果改动涉及调节项或共享类，则需要在每个评审宽度下检查整个页面。这是视觉更改唯一的回归测试（references/iteration.md）。

references/iteration.md 介绍实际使用的载荷、模糊反馈的分类处理，以及每轮迭代的规则。

第 4 步 — 审核并交接

references/audit.md 分为三个部分。默认限制（两种圆角、两种阴影、五种字号、一种卡片网格、不使用渐变、不使用顶部带图标的功能行，……），每种状态和宽度都要结合面板审核来计数：对草稿新增的内容逐项应用这些限制——主参考中的设计元素本身是既定决定——除非契约记录了覆盖该限制的决定；在移除任何属于设计决定而非偏差的内容之前，先报告超出限制的项目。无论契约如何规定，都必须执行无障碍检查（对比度、可见焦点、键盘操作、目标尺寸）。以及需要审核的宽度。

当其他人无需沟通就能移植草稿时，草稿才算完成。交接草稿目录时，不要包含审核工具（DRAFT_KIT 块、draft-kit.js 标签和文件、data-levers 属性、selection.json），同时提供 design-contract.md，其中应包含锚点映射、运行时文件列表、明确命名的近似项、已覆盖的宽度和无障碍检查，以及一行说明有意未实现的内容（数据接线、路由、所捕获状态之外的状态）。

文件

文件	何时阅读
references/drafting.md	从无设计稿开始时：分类、筛选、研究和测量、记录设计语言；根据内容规划分区；复制、组合或重建；进行比较。
references/sources.md	不同页面该选用哪个模板目录或图库、各自可供研究的内容、可发布的代码；含日期。
references/intake.md	接收设计稿时：需要什么、应退回什么、如何将其系统映射到调节项。
references/tokens.md	绑定调节项、提取产品设计、映射外部组件，以及浅色和深色模式。
references/live-draft.md	让草稿能够交互：导航、选择规则、状态、条件界面、提取、验证。
references/panel.md	添加并配置审核面板；标记、对比度、审核；快照架构；运行服务器。
references/iteration.md	使用选择和标记、补丁规则、模糊反馈分流、工作顺序。
references/audit.md	报告完成前：默认限制、计数方法、无障碍、宽度、移除顺序。
templates/design-contract.md	所有草稿的起点；复制到草稿旁边并填写。
templates/draft-kit.js	审核面板——滑块、选择、标记、对比度、审核、实时重新加载；原样复制到草稿目录。无依赖。
templates/draft-kit.html	示例草稿：调节项块、锚点、草稿运行时、已附加的面板。
scripts/draft_server.py	提供草稿并写入 selection.json。仅使用 Python 3 标准库。