authoring-design-system

authoring-design-system — SKILL.md

变体： standard · 适用场景： 根据产品方向编写（或修订）设计系统文档，达到设计师／工程师能够据此构建一致、无障碍 UI 的质量标准。

概述

这项技能介绍了如何编写实用、一致且无障碍的设计系统文档——即产品 UI 所依托的可复用视觉与交互语言（包括原则、设计令牌、组件目录、模式、布局与国际化约定、无障碍标准、语气以及生命周期／治理）。它提供的是编写者的判断力，而非章节清单。它假定有两位协作者：一个提供章节结构的设计系统模板工具，以及一种用于以成熟实践为令牌和组件提供依据的深度研究能力。编写者会收到产品方向（以及任何用户流程），必须据此进行详细阐述，绝不能输出泛泛的套话。要达到的标准是：设计师能据此构建一致的 UI，工程师能据此实现 UI，目录涵盖产品屏幕所需的所有组件，并且系统具备无障碍性。文档是后续线框图和高保真设计所依据的词汇表，应先于它们完成。

交付物是文本形式的 Markdown——令牌以值的形式呈现，并使用 DTCG 格式的表格（hex/HSL/Oklch），以及类型比例和组件规格表。它不是渲染好的 Figma 文件，也不是编译好的令牌包。这套方法不依赖具体媒介；当前交付物是文本。

何时启用

• 根据产品方向／PRD 编写新的设计系统文档。
• 将精简的令牌集或组件列表扩展为完整的设计系统（基础、目录、模式、无障碍、语气和治理）。
• 修订现有设计系统以适应变更（新增／变更令牌或组件）——以范围明确、带版本的增量形式进行（参见步骤 7）。
• 为设计系统模板填入经过研究、决策完备的内容。

不要在以下情况下启用：

• 审查或评估已完成的设计系统 → 使用 reviewing-design-system（该技能评估的正是本技能所要达到的标准）。
• 定义各屏幕的布局／组件放置位置 → 这属于 authoring-wireframes，它会引用本技能产出的设计系统。
• 制作高保真编码原型 → 这属于下游使用者 authoring-hi-fi。
• 发布编码实现的组件库（CSS/React） → 本技能产出的是文档（令牌、规格和规则），不是实现。
• 编写其他类型的文档 → 使用对应类型的技能。

输入

阅读计划交给你的每一份文档——也就是你的 depends_on 集合（上游文档；探索阶段确定这些文档会为本文档提供依据）——并确保本文档的内容可追溯至这些文档。能产出生产级设计系统的推荐输入集包括：产品方向／PRD（用户画像、目标、覆盖范围），以及在有条件时提供的用户流程（它们能表明有哪些屏幕，进而有哪些组件）。在修订时，你还会收到现有设计系统文档和范围明确的变更。此推荐输入集是指导建议，而非硬性前提——应做到自成一体：根据实际收到的上下文进行产出；预期的依据文档缺失时，应基于现有信息继续，并将缺口明确列为假设，绝不可捏造。在具备研究能力时，应使用研究能力（深度研究），让文档内容全面，而不只是填充模板。

工作流

第 1 步：采用模板工具中的结构——不要自行编造大纲

从设计系统模板工具（综合版）中获取章节结构。不要在此处重述或重新推导章节列表；本技能提供的是填充这些章节的方法。如果没有可用模板，请获取一份综合结构（请求生成或自行构建，或退而采用规范结构：原则 → 令牌 → 组件目录 → 模式 → 布局与 i18n 约定 → 无障碍 → 语气 → 生命周期／治理），然后继续。

第 2 步：了解产品方向与覆盖范围，识别产品原型

阅读产品方向文档／PRD 以及任何用户流程。识别产品原型（轻量 CLI／实用工具、内容应用或完整的交互式 UI 产品）——这决定整个系统的规模，包括适用哪些可选方面（i18n、多品牌、治理）。如果品牌／视觉方向不够明确，请明确作出选择（注明为假设或待解决问题），切勿默默采用通用方案。目标受众由产品负责人决定——将目标用户和领域知识水平记录为一项决策；如果受众是假设的，请将其列为待解决问题，切勿默默将其作为既定事实。

第 3 步：开展调研，为令牌、组件、无障碍和约定提供依据

开展深入调研，以成熟实践为依据确定令牌、组件集、模式、无障碍目标、令牌格式以及 i18n／治理约定，而不是自行编造。如果没有可用的调研能力，切勿捏造——应明确将所选约定标注为假设，并以规范默认值为参照。

步骤 4：按各部分的方法填写

按照以下方法填写模板各部分（各部分的深度要求见 references/）：

• 原则 — 列出 3–6 条有明确立场且可执行的信念，评审者可以据此解决分歧，并且每条都要说明其权衡取舍。避免空洞的套话。
• 设计令牌 — 将每项设计决策命名为令牌，分为三个层级：基础／参考（原始值）→ 语义／系统（按意图命名，引用基础令牌）→ 组件（引用语义令牌）。按意图而非外观命名（color.action.primary，而不是 color.blue.500）——组件引用语义层，正是这一层让系统保持一致且支持主题化。令牌必须采用 W3C DTCG 格式（带类型的 $value、别名）——任何规模的系统都必须遵循，不只是大型系统（references/tokens-dtcg.md）。涵盖：
  • 颜色 — 基础色阶 + 语义角色令牌（文本／操作／反馈／表面／边框／焦点）；记录每种文本与 UI 配对的对比度（与无障碍要求相关）。在产品适用时使用现代颜色空间（Oklch／Display-P3，并提供 sRGB 回退方案）；默认使用 sRGB 也完全合适。
  • 排版 — 按角色 × 字号定义字体阶梯（展示／标题／题目／正文／标签），以表格列出字号／行高／字重，并说明采用的比例。正文字号行高约为 1.4–1.6。
  • 间距与密度 — 以 4／8px 网格为基础单位，并使用乘法比例；说明数据密集型界面的密度取舍。
  • 层级 — 定义一组精简且有名称的层级（静置 → 抬升 → 覆盖层），每级都对应阴影／表面，并映射到相应角色。
  • 动效 — 定义时长与缓动令牌，并组合成命名过渡；说明对减少动态效果的处理方式。
  • 图标 — 说明图标网格／关键线、描边粗细、尺寸集合及统一风格；即使图标资源来自外部，也要记录规则。
  • 主题化 — 浅色／深色主题，以及产品需要时的多品牌支持，应通过重新指向语义别名来实现：在固定的语义／组件层之上，为每个主题／品牌配置各自的基础令牌；绝不能为此复制组件。
• 组件目录 — 组件规模要求见步骤 5；每个组件都要按照相同的六部分编写规范：用途、结构（组成部分及其使用的令牌）、状态（按适用情况列出默认／悬停／激活／焦点／禁用／加载中／错误）、变体（类型 + 尺寸）、使用时应做／不应做的事项、无障碍（角色、键盘、焦点、对比度、状态传达方式）。整个目录保持统一的 API 词汇（同一变化维度在各处使用同一名称——使用 variant／size／state，不要一处用 type、另一处用 mode；共享值按维度组合）。
• 模式 — 为流程中反复出现的多组件场景命名（表单验证、空状态、破坏性操作确认等），并列出其组合使用的组件／令牌及规则。
• 布局与国际化约定 — 说明断点 + 网格（列数／槽间距／边距）+ 最小点击目标 + 焦点顺序；对于已本地化或计划本地化的产品，还要说明国际化／RTL：文本扩展预留空间（灵活容器）、逻辑 CSS 属性、RTL／双向文本镜像、地区字体栈、地区格式化。若工具明确仅面向单一地区，可明确说明不纳入国际化范围。
• 无障碍标准 — 采用可量化且可核查的标准，符合 WCAG 2.2 AA（见步骤 6）。
• 语气与内容 — 说明语气 + 语气范围（正式↔活泼），并明确高风险场景的规则（错误／破坏性操作场景中，清晰度优先于品牌语气）；统一术语（每个概念使用一个术语）；明确组件文案规则（按钮 = 动词开头；错误 = 原因 + 解决办法；空状态 = 引导用户采取行动）。
• 生命周期与治理 — 对于仅有一位维护者和一位使用者，且没有外部版本化系统的情况，可省略；超过这一范围时则必须提供，并记录：版本管理（semver）+ 变更日志、弃用 + 迁移策略、贡献模式、所有权、采用／入门指南，以及记录的受众群体（references/governance.md）。

Step 5：确定组件目录规模 — 硬性底线加标准集合

目录必须同时涵盖两部分：（a）界面覆盖面的硬性底线 — 产品流程／屏幕实际使用的每个组件，都必须完整编写规范（不可妥协）；以及**（b）根据产品原型确定规模的常见标准集合**（轻量工具：少量组件；完整 UI 产品：广泛覆盖）。如果无法根据现有指引为所需组件编写完整规范，就将其列为待解决问题 — 不要臆造其行为。

Step 6：将无障碍要求量化（WCAG 2.2 AA）

将 WCAG 2.2 AA 作为目标，并将每个阈值标明为数值（references/accessibility-wcag22.md）：文本对比度 ≥ 4.5:1（大号文本／UI ≥ 3:1）；焦点指示器必须可见（SC 2.4.7，AA），并且聚焦时不被遮挡（SC 2.4.11，AA）；采用更严格的 AAA 焦点外观（SC 2.4.13）作为内部规范 — ≥ 2px + 与未聚焦状态及相邻内容的对比度 ≥ 3:1；目标尺寸 24×24（+ 间距例外）；完整支持键盘操作；支持减少动态效果；不能只靠颜色传达含义；逐个组件传达角色／名称／状态。将无障碍要求纳入令牌规范（对比度、焦点）和每个组件的无障碍部分 — 不要留到后续阶段处理。

Step 7：修订模式 — 以带版本的增量修改现有系统

收到现有设计系统和范围明确的变更要求时，应修订，而非重新生成（references/amend.md）。将变更范围限定在受影响的令牌／组件及其连带影响（每个引用了变更令牌的组件；每个使用了重命名组件的对象；受影响的每个主题别名）。进行最小限度的原位修改 — 未触及的令牌／组件必须逐字节保持不变。为增量修改标注版本：提升系统的语义化版本号（MAJOR 代表破坏性变更 — 重命名／移除／更改类型；MINOR 代表新增；PATCH 代表修复）+ 添加 Keep-a-Changelog 条目（Added/Changed/Deprecated/Removed/Fixed）。对于破坏性变更，采用先弃用再迁移的方式（在 minor 版本中弃用 → 添加迁移说明 → 在 major 版本中移除），绝不能静默移除。别名层是你的好帮手 — 重新指向语义别名，而非修改每个组件，以缩小影响范围。

Step 8：交付前对照标准进行自检

确认以下各项均符合要求（与 reviewing-design-system 采用相同的标准）：已说明设计原则；已定义令牌 + 符合 DTCG + 使用意图命名 + 组件引用语义令牌（绝不使用原始值）；原型所需的基础规范涵盖网格／密度／图标设计／现代色彩；每个组件均有完整规范（六个部分）+ 使用一套 API 术语；目录涵盖硬性底线 + 原型的标准集合；包含设计模式；已处理布局 + i18n（或明确说明 i18n 不在范围内）；无障碍要求已按 WCAG 2.2 AA 量化；包含语气 + 文案规则；包含生命周期／治理（或在低于阈值时有合理理由省略）；内容基于实际情况，而非套话；修订时，增量修改的范围已明确 + 已标注版本 + 弃用流程安全。指引不足时的门槛：如果无法大致推断界面覆盖面，就提出阻塞项，不要臆造组件目录。

规则

硬性规则（绝不违反）：

• 组合，不复制。 采用模板工具提供的章节结构；本技能提供填充这些章节的方法。
• 按意图命名令牌；使用 DTCG 表达。 使用语义化令牌名称表达含义（color.feedback.danger），组件只引用语义化令牌，绝不引用原始值；无论规模大小，令牌都必须采用 W3C DTCG 格式（带类型且使用别名）——不允许例外地使用值表。
• 主题切换依靠别名替换。 浅色／深色主题和多品牌主题应基于一个固定层级重新指向语义别名，绝不为组件创建分支。
• 每个组件都要有完整规格，并统一 API 词汇。 包含结构、状态、变体、用法和无障碍要求；整个组件目录中，同一变化轴使用相同名称。
• 达到覆盖范围下限。 真实屏幕用到的每个组件都必须纳入目录，并提供完整规格。
• 无障碍要求需量化，符合 WCAG 2.2 AA。 对比度；焦点——可见且不被遮挡（AA），并采用 AAA 焦点外观 ≥2px／3:1 作为内部规则；目标尺寸为 24px；键盘操作；减少动态效果；不能只依赖颜色。“无障碍”若没有具体数值，就不算标准。
• 国际化：明确处理或明确排除范围。 对于本地化产品，需覆盖文本扩展、逻辑属性和 RTL；单一语言区域的工具必须明确说明不涵盖这些内容——绝不能默默省略。
• 治理：未达到门槛可省略，达到门槛则必须包含。 单一维护者、单一使用者且无版本控制的外部依赖，可省略生命周期／治理章节；否则该章节必不可少。
• 修改 = 编辑而非重绘，并记录带版本号的差异。 发生更改时，进行范围最小的编辑，并为其指定版本（semver + 变更日志）；对破坏性更改先弃用再迁移；绝不重新生成或翻新未改动的部分。
• 绝不捏造。 不要为了显得有依据而编造调色板、对比度数值或约定。未知内容 → 明确标注为假设。
• 文本媒介。 使用数值和规格表（Markdown），而非渲染后的设计文件。
• 能构建才算完成。 不要交付设计师或工程师无法据此构建一致且无障碍 UI 的系统。

偏好（可覆盖）：

• “全面”决定目标；同时保持适度——完整的是决策，而非行数。对于精简产品，可合并章节、缩减标准组件集，并明确排除国际化／多品牌支持，也可省略治理（但硬性下限、DTCG 和量化的无障碍要求仍须满足）。
• 原则保持在 3–6 条简洁要点；优先采用常见的令牌层级／字号比例角色。
• 若能保持兼容性，优先重新指向语义别名，而非进行破坏性的令牌更改。

易犯问题

• 令牌名称描述具体值，或令牌不符合 DTCG 格式。 按钮引用的 color.blue.500，或不含 DTCG 结构的扁平十六进制颜色列表，都会破坏主题能力和互操作性——即便是小型系统，也应使用语义化命名并以 DTCG 表达。
• 组件规格不完整。 有变体却没有状态（或没有无障碍要求），看似完整，实际无法一致地构建——每个组件的六个部分都必须齐备。
• API 漂移。 不同组件中使用 type、variant 和 mode 等不同名称，会削弱系统——统一词汇。
• 目录仅取自标准组件集。 漏掉真实屏幕用到的组件，就会留下覆盖缺口——先梳理流程。
• 把无障碍要求停留在愿景层面。 没有 WCAG 2.2 目标或具体数值，就不算标准。
• 把国际化当作事后补充。 固定宽度文本和物理 CSS 属性会破坏翻译——应在基础规范中纳入灵活容器和逻辑属性。
• 更改时重新生成。 为了更改一个令牌而重写整个系统（而非进行范围明确、带版本号的差异更新），是修改流程的反面模式——应编辑而非重绘。
• 泛化填充。 适用于任何产品的令牌／组件，说明你扩充的是模板，而非产品。

反模式

• “大纲我自己来写。” 这会与模板工具重复——沿用其结构，补充方法和质量标准。
• “DTCG 只适用于大型系统。” 任何规模都必须遵循——小型系统也需要类型化/带别名的令牌。
• “无障碍稍后再处理。” 对比度、焦点和键盘操作都属于令牌和组件规范的一部分——一开始就纳入设计，以符合 WCAG 2.2。
• “标准集就是完整目录。” 它只占一半——另一半是产品屏幕使用的所有组件。
• “这是个小改动，我重新生成整个系统就行。” 应作为有明确范围的版本化增量进行修改；绝不重做未受影响的部分。
• “方向描述很简略，那我就自行编一套完整目录。” 应将缺失的范围作为阻塞项/待解决问题明确提出。

输出

一份符合 第 8 步标准的设计系统文档（包含设计原则；一致应用意图命名的 DTCG 令牌；完整的基础规范，包括图标、网格、密度和现代色彩；完整规格定义的每个组件，以及统一的 API 术语；涵盖基础要求和标准集的目录；模式；布局和国际化；WCAG 2.2 AA 数值化无障碍要求；语气和文案规则；必要时包含生命周期/治理；内容切合实际而非套话；修改时提供有明确范围的版本化增量）。其抽象使用者包括下游线框图和高保真设计（引用其中的组件/令牌）、UI 工程（据此构建）以及审查者（依据相同标准进行评估）。以文本（markdown）形式表达；并且在单向流程中先于线框图/高保真设计。

相关内容

• 设计系统模板工具（内容/模板入口）——提供此技能要填充的章节结构。
• 深度研究能力——为令牌、组件、模式、无障碍目标、DTCG 格式以及国际化/治理惯例提供依据。
• reviewing-design-system——依据相同标准进行评估；作者和审查者共用同一标准，避免标准偏离。
• authoring-wireframes + authoring-hi-fi——下游使用者：屏幕布局使用本文档中的组件并引用其中的令牌。
• 上游的产品方向/PRD（以及可选的用户流程）——此技能细化的输入；绝不是一张白纸。

渐进式披露

• references/tokens-dtcg.md——DTCG 令牌格式（层级、类型化 $value、别名、主题/多品牌、现代色彩空间）。
• references/accessibility-wcag22.md——WCAG 2.2 AA 数值阈值和各组件的无障碍要求。
• references/i18n-rtl.md——国际化/RTL 惯例（文本扩展、逻辑属性、本地化排版）。
• references/governance.md——生命周期和治理政策（版本控制、弃用/迁移、贡献、所有权、采用、受众）以及低于阈值时的省略规则。
• references/amend.md——修改模式（限定影响范围、修改而非重绘、版本化增量、先弃用后迁移）。
• references/sources.md——方法、令牌/组件惯例和无障碍阈值的研究来源。

正文限制

• description ≤ 1,024 个字符（agentskills.io 上限）。
• 正文 ≤ 约 500 行 / 5,000 个令牌。
• 大量内容放在 references/ 中，按需加载。