UI 视觉设计 / 系统课时

按用途组织 Group 与文件目录

按用途组织 Group 与文件目录

同一套颜色 Token 如果只按页面堆在一个文件里,修改品牌色时很难判断会影响哪些组件。本篇以按钮为例,把基础色、语义色、组件色分别放进 DTCG 文件,并确保拆分后仍能沿完整路径解析引用。

学习目标

  • 区分 Group 的层级路径与物理文件目录。
  • 制定可长期使用的 Token 命名与三层拆分规则。
  • 编写三份 DTCG JSON,并验证跨文件别名链。

按职责确定命名和边界

DTCG 2025.10 中,没有 $value 的对象是 Group;含 $value 的对象是 Token。Group 可以嵌套,也能通过 $type 为后代设置默认类型,但规范不会根据 color、button 这类名字自动判断含义。

采用小写英文、短横线和固定层级,避免跨平台导出时重命名。此项目规定 primitive、semantic、component 三个顶层 Group:

层级 负责什么 完整 Token 路径
primitive 不带用途的原始色阶 primitive.color.brand.600
semantic 跨组件共享的用途与状态 semantic.color.action.primary
component 具体组件的插槽与变体 component.button.primary.background

DTCG 禁止 Group 与 Token 的名称以 $ 开头,也禁止名称中包含 .、{、}。例如不要创建单个键 brand.600,应拆为 brand Group 和 600 Token。命名虽区分大小写,团队仍应禁止仅大小写不同的重名项。

让文件与 Group 各司其职

建立以下三个文件。目录负责代码仓库中的归属和评审;文件内容的 Group 才决定 DTCG 引用路径。

文件路径 文件中的顶层 Group 变更归属
tokens/primitives/color.tokens.json primitive 品牌色与中性色
tokens/semantic/color.tokens.json semantic 交互、文字等语义
tokens/components/button.tokens.json component 按钮专属映射

三个 Token 文件及其 Group 和别名依赖关系

.tokens.json 是规范推荐的文件扩展名。拆成多个文件不代表引用会自动跨文件生效:发布管线应先加载三份文件,合成统一 Token 树,再解析别名;不同工具如何组合文件需要单独配置。

编写三份可合并的 JSON

先在 tokens/primitives/color.tokens.json 定义原始颜色。color Group 的 $type 会传给子 Token;DTCG 2025.10 的颜色值使用 colorSpace 与 components,这里的 sRGB 分量取值为 0~1。

json
{
  "primitive": {
    "color": {
      "$type": "color",
      "brand": {
        "600": {
          "$value": {
            "colorSpace": "srgb",
            "components": [0, 0.4, 0.8],
            "hex": "#0066cc"
          }
        }
      },
      "neutral": {
        "0": {
          "$value": {
            "colorSpace": "srgb",
            "components": [1, 1, 1],
            "hex": "#ffffff"
          }
        }
      }
    }
  }
}

在 tokens/semantic/color.tokens.json 只表达用途,不再复制十六进制色值。{primitive.color.brand.600} 指向合并后根节点下的完整 Token 路径。

json
{
  "semantic": {
    "color": {
      "$type": "color",
      "action": {
        "primary": {
          "$value": "{primitive.color.brand.600}"
        }
      },
      "text": {
        "on-primary": {
          "$value": "{primitive.color.neutral.0}"
        }
      }
    }
  }
}

最后在 tokens/components/button.tokens.json 把语义色映射到按钮的背景与文字。组件不直接依赖 primitive,以后调整主题只需要修改语义映射。

json
{
  "component": {
    "button": {
      "primary": {
        "background": {
          "$value": "{semantic.color.action.primary}"
        },
        "text": {
          "$value": "{semantic.color.text.on-primary}"
        }
      }
    }
  }
}

这些是三份完整 JSON 文件,不是把三个顶层对象原样拼接成一个文本文件。别名 Token 的类型可以从目标 Token 解析得到;但解析器必须能访问引用的目标文件。

合并并检查引用链

在项目根目录创建 scripts/check-tokens.mjs。下面的 Node.js 20+ 示例只使用内置模块:合并不同顶层 Group,并检查此案例中的引用缺失和循环;它不是完整的 DTCG 规范校验器。

js
import { readFileSync } from "node:fs";

const files = [
  "tokens/primitives/color.tokens.json",
  "tokens/semantic/color.tokens.json",
  "tokens/components/button.tokens.json"
];
const root = {};

// 文件名不参与 Token 路径;同名顶层 Group 不能被静默覆盖
for (const file of files) {
  const data = JSON.parse(readFileSync(file, "utf8"));
  for (const [name, group] of Object.entries(data)) {
    if (Object.hasOwn(root, name)) throw new Error(`重复根 Group:${name}`);
    root[name] = group;
  }
}

function resolve(path, seen = new Set()) {
  if (seen.has(path)) throw new Error(`循环引用:${path}`);
  const token = path.split(".").reduce((node, key) => node?.[key], root);
  if (!token || !Object.hasOwn(token, "$value")) {
    throw new Error(`引用缺失:${path}`);
  }
  const value = token.$value;
  // 本例只解析引用整个 Token 的大括号别名
  if (typeof value === "string" && value.startsWith("{") && value.endsWith("}")) {
    return resolve(value.slice(1, -1), new Set([...seen, path]));
  }
  return value;
}

for (const path of [
  "component.button.primary.background",
  "component.button.primary.text"
]) {
  console.log(`${path} = ${resolve(path).hex}`);
}

保存三个文件与脚本后,在项目根目录执行:

bash
node scripts/check-tokens.mjs

预期输出:

text
component.button.primary.background = #0066cc
component.button.primary.text = #ffffff

若把语义文件的 brand.600 错写成 brand.500,脚本应抛出 引用缺失:primitive.color.brand.500,而不是悄悄用空值发布。正式构建还应增加 DTCG 类型、颜色分量和命名合法性校验。

用失败案例审核拆分质量

  • 目录名冒充 Group:文件放在 semantic/ 中,却只写顶层 color,引用就不是 semantic.color...。修复方法是在 JSON 内显式保留 semantic。
  • 组件绕过语义层:按钮背景直接引用 {primitive.color.brand.600} 虽然可能合法,却会让品牌调整波及组件文件。改为引用 {semantic.color.action.primary}。
  • Token 与 Group 混为一体:一个对象已经含 $value,就不能再往其中加入 hover、pressed 子 Token。把它们改为同一 Group 下的兄弟 Token。
  • 随意改路径:把 action.primary 改成 interactive.default 属于破坏性重命名;先全仓查找旧引用,完成迁移后再删除旧路径。

验收时应同时满足三件事:每个 Token 的完整路径唯一,组件引用只穿过约定的语义层,合并后全部别名可解析。规范原文可对照 DTCG Format 2025.10;文件拆分策略属于本项目约定,不是 DTCG 强制规定的目录结构。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

按用途组织 Group 与文件目录

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通