# @candide/design-tokens 中文文档

规范地址：https://npmcn.com/package/%40candide/design-tokens/

版本：0\.8\.0
npm 元数据更新时间：2026-10-30T07:58:57.816Z
中文译文更新时间：2026-11-09T16:09:31.312Z
软件包许可：UNLICENSED

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40candide/design-tokens
原文对照：https://npmcn.com/package/%40candide/design-tokens/?lang=original
项目主页：https://github.com/candide-com/x-design-tokens#readme
源码仓库：https://github.com/candide-com/x-design-tokens

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：84.3 kB，5 个文件
- TypeScript 类型：未声明
- Node.js 要求：\>=20
- 运行依赖：0 个
- 首次发布：2026-09-22T07:08:15.919Z
- 最新版本发布：2026-10-30T07:58:57.544Z
- 近 30 天下载量：2250（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 14 个）

## 中文简介

巴比伦斯托伦和纽特的设计标志 DTCG来源,提供了CSS输出.

## 安装

```sh
npm install @candide/design-tokens
```

也可以使用：`pnpm add @candide/design-tokens`、`yarn add @candide/design-tokens`、`bun add @candide/design-tokens`

## README

# x- 设计指针

巴比伦斯多伦的设计标志(`bt`)和"纽特"(The Newt)`tn`) (中文(简体) ). **法相为出自真言.** 设计师从Tokens Studio发布,这个寄存器使CSS. 人工智能特工: 读取 `AGENTS.md` 先说.

Candide ATMOS的一部分,史诗 [EP-1300号](https://candide.atlassian.net/browse/EP-1300)此寄存器为 [EP-1360 (英语)](https://candide.atlassian.net/browse/EP-1360)设计在 [拼接规格](https://candide.slite.com/app/docs/SULRkstniipUpk)页:1.

## 这能产生什么

每个建筑每个品牌都用相同的数值制作出两个CSS文件. 包装是他们之间唯一的区别,它决定了哪一个在页面上获胜.

| 文件 | 包装 | 船舶 | 阅读者 |
| --- | --- | --- | --- |
| `dist/<brand>/tokens.css` | `@layer x-tokens { ... }` | npm 软件包 | 作为烤制默认的商店建筑 |
| `dist/<brand>/runtime.css` | 赤线 `:root { ... }` | gCS水桶 | 商店服务器,贴入每个页面 |

未层次的 CSS 击败每个 `@layer`无论顺序和具体程度 这是平台 保证运行时间 覆盖在。 价值的改变是在没有部署商店的情况下达到生产的。 更改为符号 **名称** 是一个代码更改,因为 Tailwind 和 Angular material 是从构建时的名称生成的.

## 版式

```
tokens/$metadata.json   the set order Tokens Studio applies
tokens/$themes.json     two themes, one per brand, in one group
tokens/core/tier1.json  brand agnostic ramps: neutrals, utility colours, spacing, borders,
                        letter spacing, font weights, icon and control sizes
tokens/brands/bt/       tier1.json  the brand's own ramps, type scale, radii, shadows
                        tier2.json  the semantic layer
                        tier3.json  the control layer: buttons, forms, links
tokens/brands/tn/       the same three files
contract.json           the legal --x-* names and their types, core tier 1 plus tier 2 and 3
terrazzo.config.ts      one build per BRAND and MODE, reading .tokens-dtcg/
scripts/                normalise, build, emit, and the four checks
.tokens-dtcg/           gitignored, written by every build, never edited by hand
```

每一集都直接来自一个相克变量集. 这里没有手写的.

**品牌一级是私人品牌.** 巴比伦斯托伦有一条蓝色坡道和纽特河(Helvetica Neue);纽特河有奶油和绿色坡道和Avenir Next. 命名其中之一给你的东西 在一个品牌而不是另一个,所以 `brands/<brand>/tier1` 合同里没有.

**核心一级是.** 两块牌子都装上相同的 `core/tier1` 文件,所以其间隔尺度、边框、字母间隔、字体权重、大小、中和工具颜色带有相同名称 _财务报告和审定财务报表_ 同样的价值 通过建筑。 它持有84个令牌,品牌间零相差. 把它们排除在外将使间隔表无法命名,这不是安全财产,只是错误.

这么说合同是 **`core/tier1` 加号 `tier2` 财务报告和审定财务报表 `tier3`**, 345个名字.

## 调试格式

两个工具读取了这些文件,他们对于一个值是如何被写入的有分歧.

**Tokens Studio 写字符串 .** 这是源的形式 `tokens/`,因为设计者拥有这些文件,而Figma插件就是编辑它们.

```json
{ "$type": "fontSizes", "$value": "14px" }
{ "$type": "color", "$value": "#202e68" }
```

**Terrazzo 2.7.1需要DTCG 2025.10对象形式.** 它拒绝字符串形式,退出 1.

```json
{ "$type": "dimension", "$value": { "value": 14, "unit": "px" } }
{ "$type": "color", "$value": { "colorSpace": "srgb", "components": [0.1255, 0.1804, 0.4078] } }
```

Tokens Studio 无法读取对象表 。 它的插件打印 `[object Object]` 每个值,设计者都会看到一个空的符号集.

`scripts/normalise-tokens.mjs` 解决了这一点。 它将源转换成对象形式 `.tokens-dtcg/`,每个建筑和检查 它先运行。 转换只有一条路 没有回信 `tokens/`,所以插件保留源代码的单编辑器.

### 正常人会做什么

| 步骤 | 为什么 |
| --- | --- |
| DTCG 对象的字符串值 | 拒绝字符串 |
| Tokens 工作室类型改为 DTCG 类型 | 见下文 |
| 字体家族获得倒数堆栈 | 法格玛藏着一个赤裸的姓,所以 `Helvetica Neue` 以 `helvetica-neue-lt-pro, "Helvetica Neue", sans-serif`,首先使用 Adobe 字体工具包名称 |
| `-mobile` 样式折叠入底部,每个模式 | 查看视图端口 |
| 不同等级的同名别名崩溃 | 参见水平 |
| 非法取名和拼接别名 | 参见源缺陷 |

### 类型

Tokens Studio 按插件的符号列表分组 **拥有** 类型词汇表,比 DTCG 更细,并显示 **无尺寸部分**键入符号 `dimension` 因此,插件中无一出现,无论它生产的CSS是否正确.

一个图像导入类型几乎全部 `dimension`,所以源带更精细的类型 和建筑地图下来.

| 来源 `$type` | 插件区 | 建为 |
| --- | --- | --- |
| `spacing` | 间距 | `dimension` |
| `sizing` | 大小 | `dimension` |
| `borderRadius` | 边框半径 | `dimension` |
| `borderWidth` | 边框宽度 | `dimension` |
| `fontSizes` | 字体大小 | `dimension` |
| `lineHeights` | 线高 | `dimension` |
| `letterSpacing` | 字母间距 | `dimension` |
| `fontWeights` | 字体重量 | `fontWeight` |
| `fontFamilies` | 字体家族 | `fontFamily` |
| `textCase` | 文本大小写 | `string` |
| `color` | 颜色 | `color` |

阴影部件已输入 `sizing`. Figma 模拟一个阴影作为五个独立的变量而不是一个复合变量,而Tokens Studio对阴影部分没有类型,所以 `sizing` 是最近的水桶,可以让他们看见.

`npm run check:source` 输入到任何符号时失败 `dimension` 或者说 `text`,因为两者都是无形的:插件没有列出 `dimension`,而Terrazzo默默无声地表达什么 `text`重新从Figma进口 两者都重新引入, 所以支票是什么阻止了 一半的图书馆悄悄地消失.

`contract.json` 记录已建类型,而不是来源类型,因为合同是商店所反对的.

**字母间隔是% 没有标志.** 图像变量无法持有 `%`然后Tokens工作室悄悄跳过 `"10%"` 在推力上的价值,这就是如何 `button-lg` 在Figma失去了字母间隔。 因此,字母间隔被写成一个微小的百分比, `"10"` 10%,这也是Figma文本样式设定的。 正常人读出一个赤裸裸的 `letterSpacing` 数字为百分比和构建 `0.1em`。带有单位的值,如 `"1px"`独自一人.

**字体重量是一个单位陷阱.** Figma 作为 FLOAT 存储重量, 将相距转换为尺寸的导入选项也会将重量 400 转换为 `400px`。这是无效的 CSS , 一个浏览器会丢弃声明 。 源类型加权为 `fontWeights`,正常人会剥去一条线索 `px` 任何重量,所以再进口不能带回来.

### 视图端口

Figma将取景口烤成符号名. 未后缀样式是 **桌面**,以及 `-mobile` 是变体。 这个寄存器则相反,将每个模式构建出一个通量并分解为媒体查询.

常相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相 每个在移动建筑上 `x-mobile` 覆盖值 `x`; 在桌面上构建 `-mobile` 符号只是丢掉。 不管是哪一种方式 CSS每个地产都有一个名字 所以一个消费者写道 `--x-typography-body-default-font-size` 从不考虑观光港.

A 类 `-mobile` 表示其自己的桌面双胞胎的别名是无操作并被跳过。 如果它别名 **不同财产** 那对双胞胎,这是费格玛错误的线条 源码检查失败了.

### 等级

在Figma中,第二级是单独的收藏,因此第二级可以持有 `border.width.sm` 第1级参考文献 `border.width.sm`。将集合放入一个命名空间 将它变成一个指向自己的符号.

常态器会崩溃这些:当一个更上一层的指使用更下一层的同名指使一个同名指使时,会去掉更上一层的指使,更下一层的指使值会站起. 这就是法格玛提到的意思.

### 源缺陷

法格玛是真理的来源,因此缺陷在法格玛被固定,从未在这里被补上. `npm run check:source` 指定每个名称并失败.

两种也从建筑中掉出,因此一个坏变量不能把整个品牌的样式表取下来:

-   **一个非法的名字.** 一个名为 Figma 的变量 `disabled 2` 将发出 `--x-...-disabled 2`,这不是法定的风俗财产,并打破了CSS围绕它的规则.
-   **被打的别名.** 提及该品牌未定义的可变因素没有正确的价值,因此,运输无所事事胜于运输错误的可变因素.

## Tokens 工作室设置

在 Sets, Sync, GitHub 下指向此寄存器 .

| 外地 | 数值 |
| --- | --- |
| 仓库 | `candide-com/x-design-tokens` |
| 处 | (单位:千美元) `tokens/<name>` 树枝,所以 `preview` 推倒工作流程起火 |
| 文件路径 | `tokens` |
| 调试格式 | W3C DTCG 数据交换小组 |

这个 `tokens` 文件路径和 `tokens/` 分支前缀无关. 一个是一个文件夹,另一个是一个分支名称.

### 主题

`$themes.json` 拥有巴比伦斯托伦和纽特两个主题 组成一个团体 `Brand`组合是独家的,所以设计者选择一个,插件关闭另一个。 没有组合,主题就是独立的开关,两个品牌可以同时开机,这决定了后期的哪个 `tokenSetOrder`。 。 。 .

Viewport不是一个主题,因为Figma用符号名而不是单独的收藏来携带.

`selectedTokenSets` 列表 **只有已启用的集**。Tokens Studio省略了其余内容,并将缺席视为残疾。 写出它们明确意味着插件的复制件和文件都说出同样的话来,但并不匹配,所以它提供在每次有人打开它,永远地推出一个配置变化.

`npm run check:sets` 当一个主题没有组, 当主题跨越一个以上的组, 当一个主题将一组列表为 `"disabled"`,或者当一个主题的启用集与构建编译的集不同时.

两者 `$themes.json` 财务报告和审定财务报表 `$metadata.json` 由插件编写。 不要手动编辑他们 超出检查要求.

## 图标

```bash
npm run validate        # check the sets, the source, the schema, build, check the contract
npm run build           # four Terrazzo builds, then emit the two CSS shapes
npm run check:sets      # sets are wired, present, ordered, and covered by the themes
npm run check:source    # names and aliases in the Figma source are sound
npm run check           # DTCG schema and lint, for all four brand and mode combinations
npm run check:contract  # every contract name is present in every build, with a valid value
```

重新生成 `contract.json` 在设计添加或删除一个符号后 :

```bash
node scripts/check-contract.mjs --write
```

## 中情局

| 工作流程 | 运行在 | 对 |
| --- | --- | --- |
| `validate` | 每一次拉动请求,每次推向 `main` | `npm run validate`。没有发布. |
| `preview` | 向着一个 `tokens/**` 分支 | 覆盖 `<brand>/preview.css`,15秒缓存,然后发布或更新对拉取请求的状态注释。 商店服务器读取文件的地方 `DESIGN_TOKENS_URL` 指点它. |
| `preview reset` | (单位:千美元) `tokens/**` 拉请求合并或关闭 | 重建 `<brand>/preview.css` 从 `main`,但只有在预览中仍然显示拉出请求的承诺. |
| `release` | 每一次推动 `main`,则a `v*` 标签 | 打开 `main`: 制作出下一个版本,承诺,标记,然后出版. 在标签上:公布该标签。 出版是npm,然后是不可更改的版本副本,然后 `<brand>/production.css`60秒缓存. |
| `rollback` | 手动发送 | 恢复 `production.css` 从不可改变的副本. |

合并为 `main` 是生产释放. `scripts/next-version.mjs` 正在建设 `main` 并将其与最后发布的 npm 包相比较 :

| 自上次发布以来的变化 | 释放 |
| --- | --- |
| 无 | 无 |
| a 数值 | 补丁 |
| 新名称 | 小声 |
| 已删除或重排的名称 | 没有, 工作失败, 直到有人将主要版本设置在 `package.json` |

一个人设定的版本 `package.json` 在拉力请求中胜过计算出的,只要它高于上次发布。 若为 `main` 在任务运行时移动, 版本的推力失败, 没有发布 。 下一次合并会释放两个变化.

预览携带 `--x-tokens-version: "0.0.0-preview.<short sha>"`,所以一个页面名称它正在运行中的承诺。 重置后, sha就是那个 `main` 承诺.

两个预览工作流程共享一个货币组, `preview-channel`所以他们从不写 `preview.css` 同时.

桶的工作流程读取这些寄存器变量和一个秘密. 在设置、 秘密和变量、 动作下设置 .

| 名称 | 仁爱 | 示例 |
| --- | --- | --- |
| `BUCKET` | 变量 | `gs://some-bucket` |
| `PREFIX` | 变量 | `design-tokens` |
| `PREVIEW_SHOP_URL_BT` | 变量, 可选 | 读取预览的巴比伦斯托伦商店,在状态注释中链接 |
| `PREVIEW_SHOP_URL_TN` | 变量, 可选 | 纽特也一样 |
| `GCP_SA_KEY` | 隐藏 | 服务账户 JSON |

桶要能公开读取. 商店服务器在没有证书的平地HTTPS之上取取取CSS,因此在生产过程中,每一份CI工作仍然通过时,一桶私人会打破运行时间路径.

## 已知差距

1.  **没有商店环境读取 `preview.css` 还没有.** 商店服务器只向桶 CSS 注入 `DESIGN_TOKENS_URL` 还没有设定审查、阶段或生产环境。 检查本地商店的预览 `DESIGN_TOKENS_URL` 指着品牌 `preview.css`。 。 。 .
2.  **预览共享 .** 有一个 `preview.css` 每个品牌,所以两个开放的标志分会互相覆盖,最后的推力取胜. 每一次拉动请求的状态评论都写着 哪些承诺被公布 `preview reset` 永远不要擦掉另一个树枝上的新推力.
3.  **字体来自Adobe字体套件,这些套件以自己的名字发布:** `helvetica-neue-lt-pro` (基特语) `ban3byn`, (中文(简体) ), `adobe-caslon-pro` 财务报告和审定财务报表 `avenir-next-lt-pro` (基特语) `pah0waz`) (中文(简体) ). 费格玛必须保留真实的姓氏,所以平生将包名放在首位,而费格玛的名字放在后方作为倒置. 商店会装入包;这个包只取出家庭的名字.

## 常见问题

### @candide/design-tokens 是什么？

巴比伦斯托伦和纽特的设计标志 DTCG来源,提供了CSS输出\.

### 如何安装 @candide/design-tokens？

在项目目录运行 npm install @candide/design-tokens，或使用 pnpm add / yarn add / bun add。

### @candide/design-tokens 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/candide\_\_design-tokens 是否存在。

### @candide/design-tokens 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @candide/design-tokens 可以商用吗？

@candide/design-tokens 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### @candide/design-tokens 的下载量有多少？

根据 npm 官方下载统计，@candide/design-tokens 在 2026/10/09 – 2026/11/07 这 30 天内被下载 2,250 次，日均约 75 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @candide/design-tokens 还在维护吗？

最新版本 0\.8\.0 发布于 2026/10/30（10 天前）；至今共发布 14 个版本，其中过去 12 个月发布了 14 个；首次发布于 2026/09/22。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。