authoring-wireframes

authoring-wireframes — SKILL.md

变体： 标准 · 适用时机： 根据上游用户流程编写（或修订）结构化线框图文档，达到工程师能够据此构建屏幕结构的标准。

概述

这项技能介绍的是如何编写出色、全面的线框图文档——重点在于编写者如何判断，而非章节列表。这里的线框图是低到中保真度、以结构为主的：每个关键屏幕的布局区域（位于网格和共享应用外壳上）、内容层级、组件、可供性、内容／微文案意图、各屏幕状态，以及屏幕构成方面的无障碍设计——以文本形式呈现为结构化布局描述 + ASCII／Markdown 方框草图 + 各元素注释，而不是像素级效果图。这项技能假定有两位协作者：提供章节结构的模板工具，以及用于依据成熟 UI 模式设计每个屏幕的深度研究能力。编写者会收到上游用户流程（每个流程涉及的屏幕和状态转换），以及（如果存在）设计系统，然后为流程中提到的每个屏幕进行布局，绝不从空白页面开始。合格标准：文档要可供构建（工程师可以据此构建屏幕结构）、覆盖完整（流程中提到的每个屏幕和状态都有线框图），且构成良好（达到客观的布局质量标准）。

保真度沿三个维度变化——交互、视觉、内容（NN/g）。线框图的视觉保真度为低到中等，结构保真度为中等，交互保真度为低。最终颜色、字体和像素级细节属于下游高保真设计；令牌系统和各组件的无障碍设计规范属于设计系统——这项技能专注于结构。此方法不依赖媒介：当前产物是 Markdown；未来的设计工具后端只会改变媒介，不会改变思路或标准。

适用时机

• 根据项目构想和上游用户流程编写新的线框图文档。
• 为一组用户流程中提到的关键屏幕（及其状态）进行布局。
• 用户流程、屏幕、区域或引用的组件发生变化时，修订现有线框图文档（见步骤 8）。
• 为线框图模板填入经过研究、决策完整的结构化内容。

请勿在以下情况启用：

• 审查或评定已完成的线框图文档 → 使用 reviewing-wireframes。
• 制作高保真视觉设计／最终像素级效果／颜色与字体／动效 → 这属于下游的高保真阶段；设计系统负责视觉令牌。
• 重新决定有哪些屏幕和转场 → 这属于上游的用户流程；本技能负责布局各个屏幕。
• 编写或评定令牌系统／组件目录 → 这属于设计系统。
• 编写其他类型的文档 → 使用相应文档类型的技能。

输入

阅读计划交给你的每份文档——即你的 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：采用模板工具提供的结构——不要自行编造大纲

从你的线框模板工具（全面版）中获取章节结构。此处不要重述章节列表；本技能提供的是如何充分填充这些章节的方法。如果没有可用模板，则获取或构建全面的线框结构，然后继续。

步骤 2：根据上游用户流程推导屏幕列表

线框文档**depends_on 用户流程**。逐一检查每个流程；流程中提到的每个屏幕以及隐含的每次状态转换，都要有对应的线框图。 建立一张屏幕清单表（每个流程中提到的屏幕/状态 → 对应的线框章节及其经历的状态），以便审查覆盖情况——此表也是修改影响范围（步骤 8）。流程中提到的屏幕若没有定义内容，则属于缺口——记录下来（步骤 7），切勿默默编造内容。

如果存在 capability_record：将屏幕列表限制在该功能的 entry_points/exit_points 边界内。将 exit_points 标记为跨功能转换——不要设计之后发生的事情。系统线框文档负责定义外壳和跨功能导航。

步骤 3：通过研究为每个屏幕提供依据——不要编造模式；坚守保真度界限

通过深入研究，为每个屏幕提供成熟 UI 模式的依据（适用于其类型的常见布局——列表/详情、主从视图、仪表板、设置、向导、身份验证、搜索结果——以及标准的空状态/加载状态/错误状态处理），而不是编造结构。如果存在设计系统，请引用其中真实的组件和设计令牌——切勿自行编造。坚守保真度界限：只布局结构（区域、网格意图、组件选择、操作方式、状态），绝不指定精确的十六进制颜色值/像素值/字体——那属于过度追求高保真度。如果没有可用的研究能力，不要捏造模式或组件名称——采用常见结构，并将不确定之处标记为假设。

步骤 4：确立全局框架——网格、应用外壳、布局质量标准

在逐屏设计之前，先确定每个屏幕都要遵循的规范：

• **布局网格 + 间距节奏（结构，而非像素）：**列结构（例如 12 列）+ 8pt（或密集布局用 4pt）节奏的意图。说明间距节奏；精确像素值由设计系统规定。直接使用 13px 不符合节奏，属于过度追求高保真度。
• **应用外壳/页面框架：**统一的共享页眉/导航/容器/最大宽度，只定义一次并在每个屏幕中重复使用——不要为每个屏幕分别铺满整个页面。修改时，这个共享区域会受到连带影响。
• 客观的布局质量标准（每个屏幕都必须符合；无需主观审美判断）：主要操作位于扫描路径（F/Z）上；相关元素分组排列（格式塔接近原则）；不添加多余的区域/元素；同类屏幕保持一致。

如果 scope=system：输入内容是所有 has_ui=true 的功能记录——将所有 entry_points 接入导航，并为所有 exit→entry 接口生成转换规范。

第 5 步：应用逐屏方法

按此方法填写模板中的逐屏部分。对于每个关键屏幕：

• 用途与流程上下文 — 用一句话说明屏幕让用户做什么、服务于哪个流程步骤、有哪些入口，以及每个操作点会跳转到哪里。
• 布局区域与内容层级 — 使用第 4 步的术语命名区域，并说明它们在网格中的排列；根据主要任务的视觉优先级排列内容；将相关项目分组（格式塔原则），并将主要操作放在浏览路径上。先规划结构，再考虑视觉效果。
• 框架草图 — 使用 ASCII/Markdown 绘制默认/已填充布局的草图：标注区域、放置关键元素、定义一次图例并重复使用。确保草图与其注释保持同步。
• 组件与操作点（注释） — 针对每个值得注意的元素，说明其设计系统组件（或通用类型）、适用时的完整结构、交互行为（点击/悬停/校验/条件显示）、跳转位置以及边界情况（截断/溢出/排序/分页/下拉菜单）。注释能将静态布局转化为可构建的规格。
• 数据展示（适用于数据密集型屏幕）— 使用表格、列表还是卡片；对于表格，说明列、排序/筛选/分页/行密度/固定表头/行展开；渐进式披露（主要内容与通过折叠面板/披露控件/工具提示/显示更多延后展示的内容）；表单应包含分组字段和结构化输入（不要手动编写序列化字符串）。
• 内容与微文案（表达意图，而非最终文案） — 说明每个文本槽位的意图（标签/标题/按钮/空状态/错误/占位符）；使用用户熟悉的语言（不要将原始数据模型标识符用作标签——使用易懂的标签并附上一行说明）；占位符 ≠ 标签；术语一致性（每个概念在各屏幕中使用同一个名称）；预留 i18n 文本扩展空间，并在本地化时支持 RTL（若仅支持单一语言环境，则说明理由并排除在范围外）。
• 逐屏状态 — 空状态（原因 + 引导用户采取行动的 CTA，使用通俗语言）、加载状态（已知布局时，使用与已填充布局相对应的骨架屏，而非单独的加载指示器）、已填充/默认状态、错误状态（使用通俗语言说明原因 + 恢复方式 + 展示位置，采用行内提示还是阻断式提示，不显示原始代码）、成功/确认状态（说明发生了什么变化 + 下一步）以及流程会经过的部分状态。将这些状态追溯到流程路径实际经过的状态。只覆盖顺利路径是最常见的遗漏。
• 响应式说明（适用于设备形态会影响布局的情况）— 说明哪些内容会堆叠/折叠（导航栏 → 汉堡菜单/画布外导航）/隐藏/重新排序，以及所采用的机制；说明小屏幕上内容优先级的变化（提升/降低/隐藏，而不只是堆叠）；预留触控目标空间。
• 无障碍 — 屏幕构成 — 各区域的地标、单个 h1 的标题顺序、阅读/焦点顺序（包括条件显示内容时）、仅图标控件的无障碍名称、键盘操作能力（不得要求只能使用鼠标完成步骤）、目标尺寸预留（≥24×24 CSS px；SC 2.5.8）、焦点不被遮挡（固定区域不得遮挡焦点；SC 2.4.11）、非仅依赖颜色表达含义（SC 1.4.1）。将像素对比度和焦点外观交由设计系统处理（作为各组件的规范）；如果下游没有设计系统/高保真设计稿，则将此延期记录为假设（第 7 步），不要遗漏。

Step 6: 交付前按标准自检

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

1. 完整覆盖 — 每个流程中命名的屏幕和状态转换都有线框图（与流程相比没有遗漏或缺口）。
2. 所有适用状态 — 空状态、加载状态、已填充状态、错误状态，以及发生状态变化时的成功状态和相关的部分状态；关注的是质量，而不只是有无。
3. 布局与构图 — 区域和层级清晰明确；符合网格；位于共享应用外壳中；达到客观的布局质量标准（扫描路径、分组、避免无故添加内容、同级一致性）。
4. 组件 — 指明设计系统（DS）组件；组件一致且组合得当；不擅自发明组件。
5. 交互提示与数据展示 — 注明行为和目标位置；数据密集型屏幕需说明其表格、披露或表单结构。
6. 内容与微文案 — 说明文本槽位的用途；标签不泄露数据模型信息；标签持久显示；术语一致。
7. 响应式 — 在外形尺寸有影响时，说明重排机制和移动端优先级。
8. 屏幕构成的无障碍性 — 地标、单个 h1、阅读顺序、名称、键盘操作、预留目标尺寸、焦点不被遮挡、不能仅依赖颜色传达信息（像素对比度留待设计系统处理）。
9. 注释与交接 — 定义图例；草图与注释保持同步；元素对应到设计系统组件（交接映射）。
10. 明确指出缺口 — 未定义的屏幕或内容、缺失的组件、待后续设计系统或高保真环节处理的组件无障碍问题，均作为明确的假设或待解决问题列出。
11. 结构性，而非高保真 — 低到中等保真度；不呈现最终像素、颜色或字体。
12. 版本化（修改时） — 文档自身的版本和变更日志反映本次更改（步骤 8）。

Step 7: 明确指出缺口

流程中命名了内容尚未定义的屏幕、某个元素需要设计系统未定义的组件，或组件契约中的无障碍要求没有设计系统或高保真阶段作为后续处理——这些都应列为待解决问题或假设。逐项列出；缺失的组件应标记给设计系统负责人。绝不要用臆造的屏幕或组件来掩盖缺口。

Step 8: 修改模式 — 编辑，不要重绘（迭代时）

收到现有线框图文档和一项更改时，应将其视为范围明确、版本化的差异，绝不要重新生成：

1. 范围与连带影响 — 确定哪些屏幕、状态或区域需要更改，然后追踪连带影响：每个复用已更改共享区域（应用外壳、导航、页眉）的屏幕；每个引用已编辑或已移除屏幕的清单行或流程交接；每个使用已更改或已弃用设计系统组件的屏幕；每个因上游流程变更而新增或移除的屏幕。
2. 编辑，不要重绘 — 在原位置做最小限度的编辑；未改动的屏幕保持逐字节不变；一次性将共享区域的更改应用到所有复用该区域的屏幕（这是唯一合理的大范围连带变更），不要逐个屏幕更新导致版本不一致；保留稳定的屏幕和组件名称。
3. 版本与变更日志 — 提升文档自身的版本号：MAJOR（移除或重命名屏幕，或移除状态——会破坏构建/高保真契约）、MINOR（新增屏幕、状态、区域或组件）、PATCH（修正注释、标记法或文案意图）；按屏幕或状态的粒度添加 Keep-a-Changelog 格式的条目。
4. 移除前先弃用 — 先在 MINOR 版本中将屏幕或状态标记为已弃用（注明替代项），再在 MAJOR 版本中移除；移除时确认没有清单行或流程交接仍引用它，并清理清单。

规则

硬性规则（绝不违反）：

• 每个以流程命名的屏幕／状态对应一个线框图。 覆盖范围以上游用户流程为准；孤立的屏幕或缺失的状态都不完整。
• 涵盖所有适用状态。 空状态／加载中／已填充／错误状态，以及状态变更后的成功状态。只覆盖顺利路径不算完成。真正静态的屏幕可省略不适用的状态（保持适度）。
• 引用真实组件；绝不凭空发明。 指明设计系统中的真实组件／令牌；自定义需求应标记为缺口，不能悄然杜撰。
• 关注结构，而非高保真。 展示布局、层级和注释；不涉及最终像素、颜色或字体，这些属于高保真阶段；令牌由设计系统负责。
• 自行负责组合层面的无障碍；组件契约则交由设计系统负责。 线框图负责地标／标题／焦点顺序／名称／键盘操作／目标预留空间／焦点不被遮挡／非颜色信息；设计系统负责像素级对比度、焦点外观，以及组件自身的目标尺寸和键盘操作。不要重复评判设计系统认证的内容；若不存在设计系统，也不能忽略这些要求（应改为假设）。
• 使用用户的语言。 不要将原始数据模型标识符用作可见标签；占位符不是标签。
• 使用一个应用外壳和统一网格。 每个屏幕都应置于共享的应用外壳中，并遵循网格节奏；不要为每个屏幕重新设计一套。
• 组合，而非重复。 从模板工具获取章节结构；不要粘贴一套相互竞争的大纲。
• 布局应以给定的流程为准。 屏幕集合来自用户流程，而非凭空想象；不要重新决定导航。
• 明确指出缺口，不要凭空发明。 未定义的屏幕／内容、缺失的组件、延后的无障碍要求，都应明确记录为假设／开放问题。
• 修改，而非重新生成。 迭代时，应原地编辑并更新版本和变更日志；绝不重画未修改的屏幕。
• 必须可构建。 如果工程师无法根据交付文档构建屏幕结构，就不算完成。
• 能力边界（提供 capability_record 时）。 将文档输出限定在该记录的边界内。生成边界之外的内容（将 refs 实体视为自身负责的内容，或设计超出 exit_point 的流程）属于范围违规，相当于虚构规范中不存在的内容。

偏好（可覆盖）：

• “全面”指的是目标要求，但仍须适度——完整做出符合屏幕类型的决策，而非追求字数。简单的屏幕可省略不需要的章节。
• 每份文档只定义一次 ASCII 符号图例，并重复使用。
• 若布局已知，优先采用与已填充布局相对应的骨架，而非仅放置一个加载指示器。
• 布局质量标准应客观；不要强加主观的布局偏好。

易踩问题

• 仅覆盖顺畅路径的界面。 漏掉空白／加载中／错误／成功状态是最常见的缺漏——真正的用户体验就在这些状态中。
• 杜撰组件。 使用设计系统未定义的组件／令牌名称，会偏离系统并导致交接出问题。请引用真实组件，或标明缺口。
• 覆盖不全，未匹配流程。 流程中提到的某个界面没有线框图——清单表正是用来发现这类问题的。
• 偏向高保真设计。 精确颜色、字体和像素间距超出了结构设计的范围，也会侵入高保真设计／设计系统的范畴。请保持结构层面。
• 重复评判无障碍性。 重新规定由设计系统负责的像素对比度／焦点外观，不是严谨，而是偏离职责——请负责组合层面的无障碍性，并将组件契约留给设计系统。
• 数据模型泄漏到标签中。 将原始标识符（manifest_docs）用作可见标签，说明模式泄漏到了界面中——请改用易懂的标签和说明。
• 通用填充内容。 如果某个布局适用于任何产品，那你设计的是模板，而不是本产品的流程。请将每个界面关联到对应的流程步骤和真实内容。
• 静态布局，没有注释。 没有逐元素注释的框图只是图片，不是规范。请注释组件、操作方式和状态，并确保与框图保持同步。
• 修改时共享区域不一致。 在一个界面中编辑应用外壳，却不修改其他复用该外壳的界面，是最常见的修改回归问题——请一次性更新所有复用该外壳的界面。

反模式

• “有内容的视图就够了。” 漏掉空白／加载中／错误／成功状态——请记录所有适用状态。
• “我给这里随便编个组件。” 请引用设计系统中真实存在的组件，或标明缺口。
• “我来重新设计要有哪些界面。” 这会重新决定导航（这是用户流程的职责）——请按给定界面设计布局。
• “我自己来写大纲。” 这会重复模板工具的工作——请从该工具获取结构。
• “我来加上颜色和精确间距，让设计更具体。” 这会越界进入高保真设计——请保持结构层面。
• “我再标明精确的对比度。” 这是设计系统的组件契约——请说明非颜色相关的意图，将像素值留给设计系统。
• “这里的流程很模糊，所以我来编个合理的界面。” 请将其列为假设。
• “改动很小，我直接重新生成文档就行。” 请原地修改，更新版本和变更日志；切勿重画未修改的界面。

输出

一份全面的结构化线框图文档，达到 第 6 步的标准（全面覆盖流程；涵盖所有适用状态；网格布局和共享应用外壳具有明确的布局／层级，并达到客观的布局质量标准；组件经过识别且保持一致；操作方式和数据显示均有注释；明确内容／微文案意图；在必要处适配响应式布局；考虑界面组合层面的无障碍性；包含图例，且草图⇄注释保持同步，并提供设计到代码的映射；标明缺口；保持结构化而非高保真；修改时记录版本）。每个界面都包含结构化布局描述、ASCII／Markdown 框图，以及逐元素注释。下游高保真设计流程和 UI 工程团队（负责构建界面结构），以及审核者（负责核验是否达到相同标准），都是该文档的抽象使用方。文档的结构来自模板工具；本技能提供内容质量。

相关内容

• 线框图模板工具（例如内容／模板网关）——提供本技能要填充的每个屏幕的完整分区结构。
• 深度研究能力——为每个屏幕提供依据，参考既定的 UI 模式，以及（如有）设计系统中的实际组件。
• reviewing-wireframes——采用相同的可构建性、覆盖范围、构图和布局质量标准；作者和审阅者遵循同一标准，以免偏离。
• 上游用户流程（depends_on 文档）——列出需要线框图的屏幕和状态转换。
• 设计系统（如有）——提供可供参考的实际组件／设计令牌，并负责各组件的无障碍访问规范（对比度、焦点外观）；线框图会引用并预留这些规范，而不会重新定义。
• 下游的 高保真设计 环节——负责最终视觉效果／像素；本技能止步于结构。

渐进式披露

• references/composition-and-states.md——深入介绍网格／8pt 节奏、应用外壳、格式塔／扫描层级、数据展示（表格／披露／表单）目录，以及每个屏幕的状态质量规则。构建数据密集型屏幕时加载。
• references/a11y-and-amend.md——深入介绍屏幕构图的 WCAG 2.2（SC 2.5.8 / 2.4.11 / 2.4.3 / 4.1.2 / 1.4.1、组件规范边界）以及修改的级联影响／版本控制流程。进行无障碍检查或修改时加载。
• references/sources.md——方法和标准的研究来源（仅在审查指导来源时加载）。

正文篇幅

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