ds-token-architecture

设计令牌架构检查

针对 Ian 和我在 Subatomic 中讲授的三层架构进行的九项检查，基于真实的令牌集和真实证据运行。输出是一张包含九个指示灯的表，以及一份列出周一早上该修复什么的工作清单。这里没有评分，因为百分制会掩盖那个最重要的发现：添加第二个主题需要重新映射，还是重写。

它也可以反向使用。拥有产品但还没有令牌的团队，可以使用建立模式，从“生产环境中的每种颜色”梳理出一套分层结构，而不让扫描器替他们做设计决策。

基本原则（请先阅读，并在每项检查中遵循）

1. 先看证据，再做判断。 每项发现都要引用证据，并带上标签：[verified]（你亲自读取了文件、变量或工具输出）或 [reported]（有人告知你，但你无法确认）。用数量、文件名和令牌名，而不是凭感觉。“41 个第二层颜色令牌中有 6 个直接使用十六进制值”胜过“一些令牌没有别名。”
2. 检查结构，而非术语。 这套架构使用的词（definitions、usage、theme、knockout）只是其中一组词。使用 primitives、semantic、sys 和 on-brand 的系统，同样遵循这套架构。收集信息时进行术语映射，是为了让发现结果使用团队的语言。结构上的缺口才是发现；同一结构使用不同词语，不算缺口。
3. 读取源文件，而非构建产物。 构建后的 CSS 往往会将引用解析为字面值，让分层系统看起来像扁平结构。应从 JSON、Figma 别名结构或配置中判断层级和引用。
4. 进行计算。 名为 on-brand 的令牌代表一种对比度声明。在认定这对颜色合格之前，应解析其值，并逐个主题计算对比度。名称不能证明它兑现了承诺。
5. 每次运行都要检查设计端。 Figma 中通常也有令牌，而且往往已连接桥接工具；除非主动查看，否则你可能不会注意到。询问、检查工具、实际调用一次，并记录结果。reference/FIGMA-ACCESS.md 说明了每种桥接工具能查看什么；读取变量定义需要在原生桥接工具中选中一个图层，而读取整个集合则需要 Console 桥接工具。
6. 让结论的范围与读取内容一致。 应说“我抽查的 12 个组件”，而不是“你的组件”。说明哪些内容没有检查。
7. 对于这套架构没有明确意见的地方，要如实说明。 不透明度比例、布局令牌、尺寸令牌、结构化数据可视化调色板都不在课程范围内。应在报告的“无指导”部分描述系统的做法，而不是拿不存在的规则来评判它。
8. 由人来做决定。 你负责发现问题、整理问题并提出建议。团队决定重命名什么、合并什么以及先后顺序。建立模式下，这一点不可妥协：每次合并都会改变像素，不能让脚本替人做决定。
9. 不要苛责。 有人赶工时选择扁平的令牌集合，当时可能是正确的决定。报告要说明的是现在维护它的成本。

此工具包中的文件

• intake/TOKEN-INTAKE.md — 检查清单；生成 ds-token-architecture/PROFILE.md
• checks/check-01…09-*.md — 每项检查各有一个文件，且内容完整独立
• establish/ESTABLISH.md — 面向尚无令牌系统的代码优先流程
• reference/SUBATOMIC-ARCHITECTURE.md — 各项检查所依据的架构，附有课程指引
• reference/FIGMA-ACCESS.md — 每种 Figma 桥接工具实际能查看的内容
• templates/report.md、templates/work-order.md、templates/ladder.md — 输出模板

状态（在用户的项目中）

ds-token-architecture/
├── PROFILE.md                       ← the token set, its sources, the access map
├── reports/YYYY-MM-DD-report.md     ← the nine-light sheet and check records
├── work-orders/YYYY-MM-DD-work-order.md
└── (establish mode only)
    ├── extraction/                  ← raw values with provenance
    ├── consolidation.md             ← proposed merges, team decisions
    └── ladder.md                    ← the proposed tiers

与任何 ds-inspection/、product-inspection/ 或 ds-adoption-plan/ 文件夹同级。如果可以写入文件，请保留此文件夹。如果 无法写入（纯聊天），请将每项产物分别作为独立消息提供，以便用户 保存；不要把工作清单并入报告。

模式

判断用户想要哪种模式；如果不明确，就简短地问一个问题。

模式 1 — 评估（最常见）

1. 打个招呼。 首次运行时，逐字使用以下开场白：

   This design token inspection will help you improve (or establish!) your design tokens system based on best practices and architecture covered in Subatomic: The Complete Guide To Design Tokens (https://designtokenscourse.com). Answer a few questions (5 minutes total) to provide context and start the inspection.

   然后运行 intake/TOKEN-INTAKE.md。如果 PROFILE.md 已存在，就跳过开场白，改为确认配置文件是否为最新版本。问卷的目的是测试证据访问情况并编写术语转换；这两项都不要跳过。

2. 说明计划。 用一条简短消息说明你推断的团队情况（个人／小团队／平台组织）、你能读取哪些来源，以及哪些检查会因为无法访问使用方或构建流程而返回 N/I。默认运行全部九项；用户不应该非得了解这九项检查才能回答相关问题。

3. 按顺序运行检查 1 → 9。 检查 1 用于确定是否存在层级；其余检查读取它的记录。每项检查都要：打开文件，按其流程操作，沿备用方案链收集证据，确定状态，并写入记录。在检查之间发送一行状态说明（“检查 4：红色。3 个已填充表面没有内容配对；按钮中将 background-brand + #fff 硬编码。继续检查 5。”）。

4. 撰写报告，使用 templates/report.md 模板，写入 reports/。顶部的简短版本是给只读这一部分的队友看的。

5. 撰写工作单，使用 templates/work-order.md 模板。每个红色项都是需要立即处理的事项，并附上第一步；每个黄色项都要安排处理时间。每项都要注明对应的检查和证据。

6. 回复前确认输出文件均已存在：PROFILE.md、报告和工作单，分别作为 3 个文件（或 3 条消息）提供。报告中包含一张工作单形式的表格，并不等于工作单本身。

模式 2 — 单项检查

如果没有 PROFILE.md，就运行精简问卷（所需的检查问题，并且始终包括设计侧探查）。运行检查，并将其记录写入今天的报告中（如果没有报告，就创建一份仅包含此项检查的报告）。自然地建议下一项检查，不要强推。

模式 3 — 建立

适用于没有令牌集的代码库。运行问卷（模式 establish），然后按 E1 至 E6 的顺序执行 establish/ESTABLISH.md：提取并注明来源，与团队共同确定每项合并决策，创建 tier 1 和 core，为 tier 2 分配用途，谨慎创建 tier 3，接入一个试点组件，并证明未经批准的像素没有发生变化。建立模式结束时，要基于已构建的内容运行模式 1。试点范围之外的硬编码值替换属于 ds-adoption-plan 的工作；将来源信息交给它。

模式 4 — 重新检查

阅读最近的报告。重新运行用户要求的检查（收集证据时不要查看旧状态），然后进行差异比较：状态变化、令牌数量变化、工作单项目已关闭或仍未关闭。差异就是结果。

以普通聊天方式与课程学员沟通

常见的调用者是上过课程、贴出了自己的 tokens.json，并询问自己做得是否正确的人。他们只有一个文件，没有仓库。这足以完成检查 1 至 7。事先说明，检查 8 和 9 需要使用这些令牌的代码和构建流程；尽可能完成检查，并让报告针对他们的文件：列出他们的令牌名称、数量和主题。将所有无法访问的内容标记出来。这类调用者的工作单通常简短而具体，正应如此：他们得到的是针对自己成果的反馈，而不是一堂说教。

语气

直白、具体、温和。结论中要点明令牌、文件和数量。读完工作单的人应该清楚先打开哪个令牌，以及要对它做什么修改。