UI 视觉设计 / 系统课时
初始化 Token 仓库与构建环境
初始化 Token 仓库与构建环境
将颜色和间距等设计变量存入独立 Git 仓库,再交给 Node.js 构建脚本生成 CSS,便于设计侧修改与前端消费分开管理。完成后,你会拥有可复现的 npm 构建命令、最小 Token 示例和可以逐项核对的产物文件。
学习目标
- 检查 Node.js、npm、Git 工具链,并初始化独立仓库。
- 使用带类型的 JSON 保存颜色与间距 Token,配置 npm 构建入口。
- 运行构建并检查 CSS 与 Git 状态,定位常见初始化错误。
检查本地工具链
推荐安装 Node.js 24 LTS,示例同样适用于 22 LTS;Git 需要 2.28 或更新版本,以支持 git init -b main。以下命令适用于 macOS、Linux 终端或 Windows Git Bash,Windows PowerShell 的目录命令写法可能不同。
node --version
npm --version
git --version预期输出形态:
v<NODE_VERSION>
<NPM_VERSION>
git version <GIT_VERSION>尖括号中的版本号取决于实际安装值。若出现 command not found,先安装对应工具并重新打开终端;若 Node.js 版本过旧,先切换到受支持的 LTS 版本,不要直接在旧版本上排查构建脚本。
初始化仓库与目录
Token 工程不应依赖某个页面项目的运行入口。这里用 tokens/ 放设计变量,scripts/ 放转换逻辑,dist/ 只放生成物;后续即使前端框架改变,源码与构建命令仍可单独运行。
mkdir design-tokens
cd design-tokens
git init -b main
npm init -y
npm pkg set type=module 'scripts.build=node scripts/build.mjs'
npm pkg set private=true --json
mkdir -p tokens scripts预期结果:根目录出现 .git/、package.json、tokens/ 和 scripts/。package.json 中 scripts.build 为 node scripts/build.mjs,private 是布尔值 true,用于防止初始化阶段误发布到 npm。当前只使用 Node.js 内置模块,无需安装第三方依赖。
在根目录新建 .gitignore,写入:
node_modules/
dist/这样源码和构建脚本可以提交给 Git,而安装依赖与生成文件不会被新加入版本控制。不要忽略 tokens/,否则设计变量变更无法追溯。
写入最小 Token 源文件
新建 tokens/base.tokens.json。示例采用 DTCG 2025.10 格式 的 $type 和 $value:颜色使用 sRGB 分量和十六进制回退值,间距使用数值及单位对象。
{
"color": {
"brand": {
"primary": {
"$type": "color",
"$value": {
"colorSpace": "srgb",
"components": [0.2, 0.4, 0.8],
"hex": "#3366CC"
}
}
}
},
"spacing": {
"sm": {
"$type": "dimension",
"$value": { "value": 8, "unit": "px" }
}
}
}颜色分量按 0~1 表示,分别对应 51、102、204,因而回退色是 #3366CC。spacing.sm 表示 8px;不要将 DTCG 的 dimension 值简写成字符串 "8px"。源文件始终保留结构化数值,CSS 字符串由构建脚本产生。
实现构建入口
新建 scripts/build.mjs,用 Node.js 的文件系统 API 读取 JSON、检查脚本实际消费的字段,然后生成 dist/tokens.css。相对路径以脚本文件为基准,不受执行命令时当前目录的影响。
import { readFile, mkdir, writeFile } from 'node:fs/promises';
// 以脚本自身的位置解析输入与输出路径。
const inputUrl = new URL('../tokens/base.tokens.json', import.meta.url);
const outputUrl = new URL('../dist/tokens.css', import.meta.url);
const data = JSON.parse(await readFile(inputUrl, 'utf8'));
const color = data.color?.brand?.primary;
const space = data.spacing?.sm;
// 只校验本示例要消费的类型与字段,并非完整 DTCG 校验器。
if (
color?.$type !== 'color' ||
color.$value?.colorSpace !== 'srgb' ||
!/^#[0-9a-f]{6}$/i.test(color.$value?.hex ?? '') ||
space?.$type !== 'dimension' ||
typeof space.$value?.value !== 'number' ||
!['px', 'rem'].includes(space.$value?.unit)
) {
throw new Error('Token 源数据缺失或类型错误');
}
const css = `:root {
--color-brand-primary: ${color.$value.hex};
--spacing-sm: ${space.$value.value}${space.$value.unit};
}
`;
await mkdir(new URL('../dist/', import.meta.url), { recursive: true });
await writeFile(outputUrl, css, 'utf8');
console.log('构建成功:dist/tokens.css');readFile 和 JSON.parse 证明本地工具链能真实读取设计变量;mkdir 的 recursive: true 允许首次构建时自动创建 dist/。脚本故意只支持这两个 Token,未实现别名解析、颜色空间转换或全量规范校验。
构建、验收与排错
在仓库根目录执行 npm 脚本并查看文件内容:
npm run build
cat dist/tokens.css预期输出的关键内容如下(npm 还会显示脚本启动信息):
> design-tokens@1.0.0 build
> node scripts/build.mjs
构建成功:dist/tokens.css
:root {
--color-brand-primary: #3366CC;
--spacing-sm: 8px;
}再检查需要纳入版本控制的文件:
git add .gitignore package.json tokens scripts
git status --short预期输出:
A .gitignore
A package.json
A scripts/build.mjs
A tokens/base.tokens.jsondist/ 不应出现在暂存清单。若构建提示 ENOENT,先核对 tokens/base.tokens.json 的路径、文件名和大小写;若出现 SyntaxError,检查 JSON 是否有注释、单引号或尾随逗号;若 npm 报 Missing script: "build",用 npm pkg get scripts.build 核对配置。
最后把 spacing.sm.$value.value 从 8 改为 12,再次执行 npm run build,确认 CSS 变成 --spacing-sm: 12px;。能够由源码变更稳定地重建产物,才算完成本地 Token 工程初始化。