authoring-hi-fi

authoring-hi-fi — SKILL.md

**变体：**标准 · **适用场景：**将上游线框图和设计系统转化为可运行、可渲染的高保真 UI 设计代码（或修改现有设计）——为工程师提供可扩展到生产环境的构建种子，并以人工视觉检查作为门槛。

概述

此技能介绍如何制作出色、全面的高保真 UI 设计代码——重点在于创作者应如何判断，而非章节列表。产物是可渲染为像素的代码：默认使用独立 HTML+Tailwind；当构建技术栈为 React 时，使用 React+shadcn（这样种子代码更贴近构建目标，并尽量减少偏差）。它要求具备模板工具（用于章节结构）、无头浏览器（agent-browser/Playwright，用于渲染和截图）、产品的设计系统 + shadcn（作为令牌和组件的权威来源），以及研究能力。创作者会获得上游线框图（屏幕、状态和结构）与设计系统（令牌和组件约定），并据此实现线框图中指定的每个屏幕——绝不从空白页面起步，也绝不重新决定结构。

其标志性机制是一个循环，而非一次性编写：生成 → 无头渲染 → 截图（按视口 × 状态）→ 根据设计系统、线框图和质量标准进行视觉自审 → 改进 → 重复，直到达到标准 → 人工视觉验收。此流程需要具备视觉能力的运行环境；纯文本运行相当于盲目生成代码（效果会降级——应明确说明，绝不可假装渲染过）。

两条边界可确保工作不偏离范围：高保真阶段负责将最终视觉效果实现为像素 + 数值化的像素级 WCAG 判断（线框图仅为这些内容预留了位置）；它使用设计系统中的令牌（绝不自行编造或评判令牌）；它渲染给定的线框图结构（绝不重新决定布局、屏幕或导航）；并且它是一个构建种子——有意保持精简（无需测试、可用模拟数据、可使用 CDN、可采用单文件）——而非最终生产代码（构建阶段会重建数据层、路由、状态、测试和性能）。

何时启用

• 根据上游线框图和设计系统，将新的高保真设计编写为代码。
• 将线框图文档指定的关键屏幕（及其状态）实现为渲染后的像素。
• 当令牌、屏幕、共享布局或引用的组件发生变化时，修改现有高保真设计（见步骤 8）。
• 使用研究成果填充高保真模板，并交付已渲染、决策完备的屏幕。

不要在以下情况启用：

• 审查或评估已完成的高保真设计 → 使用 reviewing-hi-fi。
• 设计屏幕的结构（布局区域、组件选择、作为结构的状态）→ 这属于上游的线框图。
• 编写或评估令牌系统 / 组件目录 → 这属于设计系统；在此处使用它即可。
• 重新决定有哪些屏幕或转场 → 这属于用户流程。
• 编写最终的生产代码（测试、真实后端、路由）→ 这属于构建阶段；此处产出的是种子。

输入

阅读计划交给你的每份文档——即你的 depends_on 集合（典型上游包括：负责命名和构建屏幕结构的线框图，以及提供令牌和组件契约的设计系统）。指定的上游文档仅供参考，并非前置条件：务必做到自包含——根据你收到的内容进行产出；如果缺少预期的上游文档，就基于现有内容继续，并将缺口作为假设注明（步骤 7），切勿凭空捏造。确认运行环境能够渲染，并且你能查看渲染结果（具备视觉能力的运行环境 + 无头浏览器）；如果无法做到，请如实说明，并将本次运行视为降级处理——不要将未经验证的渲染结果说成已审查。

**能力上下文（如有提供）：**如果调用方注入了 capability_record（来自 capability-map.yaml product_capabilities 的记录），请在步骤 1 前阅读。它定义了你的范围边界：owns = 你负责的实体；refs = 你会引用但不负责的实体；publishes/consumes = 你呈现的事件；entry_points/exit_points = 用户进入和离开的方式；has_ui/has_api/has_persistence = 适用的界面。如果存在，请将其视为硬性约束，不得超出其定义的边界。

工作流

步骤 1：从模板工具获取结构——不要自行编造大纲

从高保真模板工具获取章节结构（全面版）。此处不要重复列出章节；本技能提供的是一种能出色填充这些章节的方法。如果没有可用模板，请获取或构建一套全面的高保真结构，然后继续。

如果存在 capability_record：仅将设计系统令牌应用于各能力对应的线框图——不要重新设计外壳或其他能力。如果 scope=system：仅将令牌应用于系统线框图（外壳）。遵守你正在润色的线框图文档所定义的相同边界。

步骤 2：从上游线框图推导屏幕集合

高保真设计依赖于 depends_on 中的线框图。**线框图中命名的每个屏幕，以及流程或线框图涉及的每种状态，都必须有对应的高保真渲染屏幕。**构建屏幕清单（每个屏幕及其状态、目标视口 → 对应章节），使覆盖范围可审计——这也是修订影响范围（步骤 8）。线框图中命名但未定义内容的屏幕属于缺口——请记录下来（步骤 7），切勿自行编造。按给定结构进行渲染；不要添加线框图未指定的屏幕、区域或导航（这属于越界）。

步骤 3：建立令牌 → 代码映射（使用设计系统；切勿自行编造）

将设计系统 / DTCG 令牌一次性映射到代码的主题层，然后将所有内容绑定到该主题层：语义化 CSS 自定义属性（--background、--primary 等，并通过 .dark 覆盖），由 Tailwind 实用类使用（在配置中使用 hsl(var(--token))，或使用 v4 的 @theme 代码块）；在 React 技术栈中，则使用 shadcn CSS 变量主题。每个视觉值都必须由令牌提供——不得使用绕过令牌的原始 #hex / 12px / bg-blue-500。设计系统中缺失的令牌或组件属于已发现的缺口（→ 修订设计系统），切勿直接内联。（详见：references/render-loop-and-tokens.md。）

第 4 步：实现视觉语言，并精修到像素级

将线框的结构和 DS 令牌转化为精致、真实的屏幕：

• 视觉呈现——使用令牌支持的颜色、真实的排版（字号比例／字重／行高／行宽）、落实 8pt 间距节奏、层级／阴影、圆角、真实图标集，以及安全的占位图像；将线框的结构层级通过真实的对比度／尺寸／字重／颜色／位置表现出来。
• 客观精修（可检查）——与网格对齐，间距尺度一致，视觉平衡，元素没有裁切／重叠／孤立，使用令牌中的数值，并在同类屏幕间保持一致的处理方式。
• 五项具名美学启发式（项目的精修标准——需要评估，但每项都必须有名称并且能够清晰阐述；不要求主观且超出集合范围的审美偏好）：平衡（视觉重量的分布）、留白与克制（有意留出负空间；不拥挤、不作过度装饰）、间距节奏（一致、悦目的节奏）、焦点清晰度（眼睛能落在一个明确的重点上）、美学统一性（具有“经过设计”的用心感，而不是零件拼凑的感觉）。（各项启发式的深入说明及“优质效果示例”：references/visual-a11y-and-amend.md。）

第 5 步：渲染真实内容与所有状态，然后运行“渲染→视觉审查→优化”循环

• 真实内容（不用 lorem）+ 真实情境 + 边界数据（长字符串、溢出、空状态、复数形式、本地化长度）——lorem 会掩盖布局／溢出／语气／无障碍方面的问题。
• 将流程经过的每种状态渲染为实际像素：空状态（说明原因 + 指引用户采取行动）、加载中 = 与已填充布局相呼应的骨架屏（而不是光秃秃的旋转指示器）、已填充、错误（通俗易懂的原因 + 恢复方法）、成功（说明发生了什么变化 + 后续步骤）、部分完成。
• 运行循环：生成代码 → 无头渲染（agent-browser）→ 按视口 × 状态截取屏幕截图 → 根据 DS + 线框 + 第 6 步标准进行视觉审查 → 优化 → 重复。循环次数有上限（§9）：限制迭代次数；如果某个屏幕仍达不到标准（例如，缺少 DS 令牌导致对比度受限），停止并将阻碍因素作为假设／缺口明确提出——不要无限循环。展示优化后的屏幕及其截图，绝不要展示首次生成的代码。

步骤 6：交付前对照标准进行自检

确认以下各项均满足（这是 reviewing-hi-fi 所要求的标准——同一份清单，且每项要求都与屏幕的类型相称）：

1. 完整覆盖 — 所有在线框图中命名的屏幕和状态均已渲染（与线框图相比没有遗漏）。
2. 保真度与范围 — 使用高保真视觉效果（而非线框图灰色样式），不虚构结构、导航或设计令牌；这是一个 seed（不是过度构建，也不声称已可投入生产）。
3. 视觉呈现与层级 — 实现设计系统的视觉语言；主要元素在视觉上占主导地位；层级清晰易辨。
4. 精修 — 满足客观要求子集和五项指定启发式原则；不强加范围外的主观审美偏好。
5. 由令牌支撑 — 每个值都有令牌支撑（Tailwind/CSS-var/shadcn）；不使用原始的非令牌值；映射忠实于设计系统。
6. 已渲染并完成自审 — 每个屏幕均可正常渲染且无损坏，并已通过迭代循环，结合线框图和设计系统进行视觉审查。
7. 内容真实 — 使用真实内容，不用 lorem；已测试边界数据。
8. 已渲染状态 — 渲染流程中访问的每种状态；使用骨架屏而非加载旋转图标；错误信息包含原因和恢复方法。
9. 响应式 — 已在目标视口中渲染并验证；在设备形态有影响时，优先呈现移动端内容并采用自适应导航。
10. 渲染结果符合 WCAG 2.2 AA 数值要求 — 对比度为 4.5/3:1（SC 1.4.3/1.4.11）；焦点可见且不被遮挡（2.4.7/2.4.11），并且焦点外观 ≥2px/3:1（2.4.13，内部规则）；目标尺寸 ≥24px（2.5.8）；支持键盘操作和减少动态效果；axe-core 检查通过，且未禁用任何规则。
11. 符合设计系统规范 — 无偏离或覆盖；缺失的令牌/组件已明确提出，未以内联方式实现。
12. 明确列出缺口 — 未定义的屏幕/内容、缺失的设计系统元素、降级（不渲染）运行均有明确的假设说明。
13. 版本化（修订时） — 文档自身的版本和变更日志均反映此次变更（步骤 8）。
14. 能力边界（没有 capability_record 时不适用） — 全程使用设计系统令牌；不创建设计系统之外的新组件；渲染范围与线框图范围一致（针对单项能力记录时仅限内部内容；针对系统范围时仅限外壳）——内容不得超出 refs 实体或 exit_point。

步骤 7：明确列出缺口

线框图中命名的屏幕内容未定义、某个元素需要设计系统中缺失的令牌/组件、令牌无法满足对比度/目标尺寸要求，或运行降级（仅文本、无渲染）→ 待解决问题或假设。请列出这些情况，并将缺失的令牌/组件标记给设计系统负责人。切勿用虚构的令牌/组件或伪造的截图来掩盖缺口（§7）。

步骤 8：修订模式 — 编辑并重新渲染差异，而不是重绘（迭代时）

收到现有高保真稿及修改要求时，应将其视为范围明确、带版本的差异，绝不能重新生成：

1. 确定范围 + 追踪影响 — 找出涉及的屏幕/状态，然后追踪影响范围：通过令牌→代码映射，找出所有使用已更改设计系统令牌的屏幕（高保真稿中特征明显的大范围影响）；找出所有复用已更改共享布局/组件的屏幕；找出上游线框图变更所新增/移除的所有屏幕；找出所有引用了已更改/弃用设计系统组件的屏幕。
2. 编辑 + 重新渲染差异 — 在原处进行最小限度的编辑；未改动屏幕的代码保持逐字节稳定，且不重新截取其屏幕截图（不进行字节差异比较——无头渲染每次运行都无法保证逐字节一致）；仅重新渲染并重新进行视觉审查差异部分；令牌变更在映射中只应用一次，然后一次性重新渲染所有使用该令牌的屏幕（这是唯一合理的大范围影响），绝不逐屏手动编辑。
3. 版本 + 更新日志 — 提升文档自身的版本号：MAJOR（移除/重命名屏幕，或移除/重命名单屏幕状态——这会破坏构建种子契约）、MINOR（新增屏幕/状态/组件）、PATCH（润色/文案/令牌值微调）；按屏幕/状态粒度添加 Keep-a-Changelog 条目。
4. 先弃用，再移除 — 在 MINOR 版本中将屏幕/状态标记为弃用（注明替代项），然后再于 MAJOR 版本中移除；移除时确认不再有链接/索引/同级引用，并清理相关内容。

规则

硬性规则（绝不违反）：

• 每个线框图命名的屏幕/状态对应一个已渲染屏幕。 覆盖范围以线框图为准；已命名但未渲染的屏幕即为不完整。
• 使用设计系统，不要自行发明。 只能使用由令牌支持的值——不使用原始十六进制颜色值/px；缺失的令牌/组件应标记为缺口，而不是临时内联处理。
• 按给定结构渲染。 布局线框图中的屏幕；不得重新决定结构或导航。
• 执行循环，但设定上限。 交付前完成生成→渲染→截图→视觉审查→优化；限制迭代次数，并显式指出阻碍因素，而不是无限循环（§9）。
• 这是种子，不是生产版本。 无需测试/真实后端；绝不声称已达到生产就绪状态；构建阶段会进一步完善。
• 使用真实内容，不要用占位文本。 使用真实数据和边缘数据；高保真稿中出现占位文本即为缺陷。
• 对渲染结果进行数值化无障碍检查，绝不禁用规则。 在令牌层修复对比度/焦点/目标尺寸问题；被抑制的 axe 规则即为一项发现。
• 需要具备视觉能力的运行时，否则如实说明。 仅文本运行属于降级运行；应明确指出，不要伪造屏幕截图。
• 组合使用，不要重复创建。 从模板工具获取区块结构。
• 明确指出缺口，不要自行发明。 未定义的屏幕/内容、缺失的令牌/组件、降级运行，都应明确说明是假设。
• 修订，不要重新生成。 编辑并重新渲染差异，更新版本和更新日志；绝不重新渲染未改动的屏幕。
• 能力边界（提供 capability_record 时）。 将文档输出限定在该记录的边界内。在边界外生成内容（将 refs 实体当作自身所有内容，或设计超出 exit_point 的流程）属于范围违规——相当于发明规范中不存在的内容。

偏好（可覆盖）：

• 默认使用独立 HTML+Tailwind；构建技术栈为 React 时，改用 React+shadcn。
• “全面”设定的是目标力度，但仍应适度——简单的静态屏幕应减少状态，且无需处理响应式/交互工作。
• 布局已知时，优先使用与布局相仿的骨架屏，而不是空白加载指示器。
• 五项美学启发式会纳入评判，但名称明确且可描述——不要强加个人对色调/布局的偏好。

易踩问题

• 盲目生成代码。 不经渲染和查看就生成代码，是最主要的失败原因——循环迭代（步骤 5）才是价值所在；纯文本运行效果会打折，需明确说明这一点。
• 脱离令牌的原始值。 绕过令牌映射使用 #3b82f6 / 13px 就会导致偏移——所有内容都应绑定到 DS 令牌（步骤 3）。
• Lorem ipsum。 占位文本会掩盖溢出、语气和无障碍问题，也会显得设计尚未完成——请渲染真实内容。
• 把种子当作生产成品。 添加测试／真实后端（过度构建）或声称已可用于生产（过度承诺）都不妥——它只是种子；构建阶段会将其打磨完善。
• 为通过检查而禁用 axe 规则。 排除 color-contrast 会掩盖真实缺陷——修复令牌，并记录确有必要的例外。
• 凭空发明缺失的组件。 DS 中缺少的组件意味着 DS 所有者需要补足缺口，而不是在代码中临时拼凑。
• 重新决定结构。 添加线框未标明的屏幕／区域／导航，就是越界进入线框的职责范围。
• 修改令牌时产生偏移。 每个屏幕单独手动修改令牌值，而不是只在映射中修改一次，这是最常见的修订回归问题——只改一次，再重新渲染所有使用该令牌的内容。

反模式

• “代码看起来没问题，直接发布吧。” UI 渲染并查看之前都不算完成——请执行迭代流程。
• “我在这里用个好看的蓝色。” 这会脱离令牌——请绑定到 DS 令牌，或标记该缺口。
• “现在用 Lorem ipsum 没关系。” 它会掩盖真实布局问题——请使用真实内容和边界内容。
• “我来接好后端，再加上测试。” 这会过度构建种子——保持精简；构建阶段会将其打磨完善。
• “axe 提示对比度有问题；我排除这条规则就行。” 请修复令牌；绝不要禁用真实规则。
• “线框太模糊了，我来加个屏幕。” 应将其列为一项假设，而不是擅自添加。
• “只是微调一个令牌，我重新生成全部内容吧。” 修订时只修改一次令牌，只重新渲染使用该令牌的内容，并更新版本和变更日志。

输出

一份全面渲染的高保真代码化 UI 设计，达到步骤 6 的标准（完整覆盖线框；高保真且符合种子范围；视觉呈现和层级清晰易读；经过客观评估和具名启发式检查的润色；由令牌驱动且无偏移；已渲染并经视觉审查；使用真实内容；包含已渲染的各种状态；支持响应式布局；渲染结果符合 WCAG 2.2 AA 数值标准；符合 DS 规范；明确标出缺口；修订时做好版本管理）。每个屏幕都是可运行代码，以及每种视口 × 状态下渲染出的截图。抽象使用者包括作为视觉把关者的人类、将种子扩展为生产版本的构建阶段，以及依据同一标准进行评审的审核者。文档的结构由模板工具提供；此技能负责提供内容质量。

示例演练（单屏迭代流程）。 交接内容：一张“Projects — list”线框（状态：有内容、空、加载中、出错）和一个设计系统，其中包含 --primary、--muted、Card、Button、Table。方法：将令牌映射到 Tailwind/CSS-var 主题（步骤 3）；使用包含代表性项目的真实 Table 构建有内容的屏幕（使用真实名称／日期，并添加一行名称较长的记录来检查溢出）；构建空状态（“No projects yet” + 一个使用 --primary 的“New project” Button）、复刻表格结构的加载骨架，以及错误卡片（“Couldn't load projects — Retry”）；在 360/768/1024/1280 下渲染并为每种状态截图；经视觉审查后发现，空状态 CTA 在白色背景上的 --muted 对比度仅为 2.9:1 → 改为绑定到 --primary（使用令牌，而非一次性值）→ 重新渲染 → 对比度达到 4.8:1；axe 检查通过。结果：四种已渲染状态，由令牌驱动且符合 WCAG 标准——构建阶段可以在此种子基础上继续扩展。（循环流程捕获了对比度不足的问题，并在令牌层修复，而不是给某个按钮改成脱离令牌的颜色。）

相关

• 高保真模板工具（内容／模板网关）——提供全面的逐屏幕分区结构，供此技能填充。
• agent-browser（+ playwright-best-practices）——负责渲染代码并截图，以支持循环；此技能会驱动它，而不是重新讲解它。
• shadcn + ui-ux-pro-max / ckm-*——提供 React 组件主题和视觉执行指导；与它们组合使用，而不是重新讲解它们。
• 深度研究能力——为视觉和交互决策提供依据。
• reviewing-hi-fi——设定相同的标准（重新渲染并进行视觉审查）；作者和审查者遵循相同标准，避免产生偏差。
• 上游线框图（depends_on 文档）——需要实现的屏幕结构。
• 设计系统（depends_on 文档）——需要使用的令牌和组件约定；它负责定义每个组件的无障碍访问约定，此技能负责验证渲染结果是否符合要求。

渐进式披露

• references/render-loop-and-tokens.md——渲染→视觉审查→优化循环流程 + 截图捕获协议（视口 × 状态）+ DS/DTCG→Tailwind/CSS-var/shadcn 令牌映射方法 + 代码栈选择。在设置循环或令牌映射时加载。
• references/visual-a11y-and-amend.md——五项审美启发式（分别说明“什么样才算好”）+ 视觉执行深度 + WCAG 2.2 SC 数值 + axe 设置 + 修改令牌涟漪／版本控制流程。在进行润色／无障碍检查或修改时加载。
• references/sources.md——方法和标准的研究来源（仅在审查指导的来源时加载）。

正文篇幅限制

• description ≤ 1,024 个字符（agentskills.io 上限）。
• 正文约 500 行 / 5,000 个令牌（软性目标——优先保证质量；若持续超过 700 行 / 7,000 个令牌，请标记）。
• 大量内容放在 references/ 中，按需加载。