09 第三篇 · 日常：每个变更任务

有 UI 的项目：先建 design token

这一章只对带前端 UI 的项目有用。纯后端、CLI、库或数据项目没有视觉决策要固定，可以整章跳过。

带 UI 的项目在初始化立好 steering 和 constitution 之后，还差一类真相源没定：颜色、字体、间距、尺寸这些视觉决策。它们和产品规则一样需要一处集中的权威定义，否则会散进每个 feature、各写各的，越往后越难统一。这一章讲在分解 feature 之前，先把视觉决策固化成一套 design token。

9.1 视觉决策不集中会出的两种事

视觉决策没有固定的产出位置，会散也会漂。主色用哪个橙、正文多大、卡片内边距多少，这些决定如果写进每个 feature 的 spec，就会在不同 feature 里各写一份，时间一长彼此对不上；想换一次主色，得翻遍所有 feature。该集中拍定的决策散在下游，是前面讲项目初始化时就反复出现的同一个问题。

AI 生成 UI 还会多一种翻车。让它”按设计系统写”，它照样会写出看着合理、其实不存在的值：一个前缀对、名字像模像样、库里却没有的间距 token，或者干脆把一个目测的色值硬编进去。这跟开篇讲的翻车同根：拿通用写法去填项目的具体情况，它把”用合适的值”补成了”一个看上去合适的值”。

design token 把视觉决策从”每处自己判断”换成”引用一处定好的事实”。值存不存在、叫什么名字，变成一个能查的确定答案，猜的空间就没了。这对人和对 AI 一样有效。

9.2 token 放在哪、写成什么格式

在项目里建一层 docs/design-tokens/，作为视觉决策的单一真相源。里面放两样东西：一个 README.md 写清每个 token 为什么是这个值、该用在什么场景，一个真相源文件放 token 的实际定义。README 写的是理由，不只是值，这样人和 AI 都读得懂该怎么用。

本手册配套 /td-design-tokens 来播种这一层：它先问清主观参数，必要时先做视觉 spike，再写出 docs/design-tokens/。

真相源文件的格式按项目规模分两种。单人、单站、只做 web 的项目，直接写一份 CSS 变量文件当真相源就够了，CSS 变量本身就能被样式直接用，没有中间转换。需要接 Figma、用 Style Dictionary、一份定义同时产出多端代码或多品牌换肤的项目，才用 W3C 的 Design Tokens 标准格式（DTCG，一种 JSON），它被各种设计工具通吃，代价是 JSON 要经一道构建才能变成样式能用的 CSS。DTCG 的价值在跨工具互通，单人单站用不上这个价值，多出来的那层 JSON 和转换反而是负担；需要跨工具时再上。

docs/design-tokens/ 是项目产物，token 的值高度依赖具体项目，不随方法骨架分发。

9.3 主观参数用尺度压，拿不准先 spike

视觉里真正要人拍板的参数很少。字号、间距这些看着要逐处定的值，用一个数学尺度一次定好比例，就能从”每处目测一个数”压成两三个参数。字号用模块化尺度：定一个基准字号（正文通常 16px）和一个比例（比如 1.25），逐级相乘生成整梯子，每级都是上一级的固定倍数。间距定一个网格单位（常见 4px 或 8px），所有间距取它的倍数。这样整套视觉只剩主色、基准字号、比例、网格单位几个要人定。

其中拿不准的那几个，比如主色到底用哪个橙、某个比例顺不顺眼，别硬写一个貌似合理的值。按 constitution 里”需实验才能定的先 spike”那条，先做一个定时盒的视觉 spike：把两三个候选渲染出来摆着看，选定了再 token 化。在视觉上硬猜一个值，正是 token 要消除的那种貌似合理、其实没依据的决策。

9.4 后续 feature 怎么引用

token 建好之后，它对下游立一条用法：UI feature 的 spec 和实现只引用 token 名，不写具体色值或尺寸。要一个还没有的视觉值，先在真相源里加一个 token 再引用它，而不是在 feature 里就地硬编。

这条用法本身是项目的规格纪律，写在哪、怎么对 AI 生效，是 constitution 和 steering 的事，后面讲 spec-kit 流程时再说。这里只交代 token 建好之后，下游该守的这条契约长什么样。

9.5 token 管得到和管不到的

design token 管的是”用了不存在或不一致的值”。它管不到布局合不合理、可访问性达不达标、交互对不对，一个真实存在的间距 token，照样可能用在一个错的布局里。这些仍要靠人验和专门的检查，token 替代不了。

“只引用 token 名”也只是一条约束文本，靠 AI 遵守和人把关生效。要把它变成机器强制，得靠项目已有的 lint，把”禁止硬编视觉值”并进已有的 lint 规则里，而不是单为它上一套门禁。后面讲从规则到机器检查时，会讲这类约束怎么落到 lint。小项目不必做这一层。

本章小结

带 UI 的项目在分解 feature 之前，先把颜色、字体、间距、尺寸固化成一套 design token，放在 docs/design-tokens/ 当单一真相源。格式按规模挑：单人单站用 CSS 变量，要跨工具再用 DTCG 的 JSON。主观参数用数学尺度压成几个，拿不准的先 spike。token 建好后 feature 只引用 token 名。它管值的存在和一致，管不了布局和可访问性，那些仍要人验。

参考与出处