@design-token-kit/cli (英语)

设计Token Kit的CLI软件包提供 dtokens 命令用于 从终端检查、转换和预览设计符号.

GitHub 仓库 : https://github.com/design-token-kit/design-token-kit (英语)

网站: https://design-token-kit.github.io/ 互联网档案馆的存檔,存档日期2013-12-22

打破 v3. 0.0 中的变化 : 读取当前迁移指南 升级前的版本 : 1.x至 3.0 (单位:千美元), (中文(简体) ), 1.x至2.0 (韩语),或 2.0至 3.0 键。 。 。 .

特征

• DTCG 2025.10 检查 - 计划、模型正确性,以及涂料 检查 DTCG JSON 令牌文件
• 模式检查 - 未解决的参考资料、通知参考资料、小组 引用、 类型错配和已贬值的符号使用
• 林特检查 - 跨层参考、原始价值定位、空组, 缺少符号描述规则
• 设计审计 - WCAG文本对文本和背景颜色的对比, 可读字体大小和正文行高,得分0-100
• HRDT YAML 支持 - 紧凑、人能读取的替代品 给DTCG JSON的
• DESIGN.md 支持 - 说吧 使用 YAML 格式读取并写入设计符号 前题
• 调试格式转换 - 读写DTCG JSON、HRDT YAML和 设计
• CSS 生成 - 根据 CSS 定制提供的基础和主题符号集 属性, SCSS 变量, 或 Tailwind CSS v4 @theme 变量
• SwiftUI 生成 - 使用Swift源 名称空格 enum API 或 a Theme 结构层
• 机器人生成 - 代币套件作为 res/values 资源 XML 按符号组或资源类型拆分,并带有主题资源目录
• 静态展示 - HTML 显示来自符号源或已存在的生成 CSS, 有颜色格式选择和复制控制
• 调试数据 - 文本和 HTML 报告,附有符号计数和分解
• 源抽象 - 本地文件、 stdin、 URL 和原始符号内容 字符串

需要20.19.0或更新的节点.

安装

全球安装 :

npm install -g @design-token-kit/cli
dtokens check tokens.json

本地安装 :

npm install @design-token-kit/cli

快速启动

运行基本流量 npx数字 :

npx @design-token-kit/cli check tokens.json
npx @design-token-kit/cli audit tokens.json
npx @design-token-kit/cli convert tokens.json --out ./tokens.css
npx @design-token-kit/cli showcase tokens.json --out ./showcase.html --open

其他投入和产出格式见下文各节.

输入格式

DTCG 贾森

使用 DTCG JSON 令牌文档作为目录源格式 验证,转换,CSS生成,并展示生成.

HRDT 也门

使用HRDT YAML作为紧凑,人可读取的DTCG JSON替代品.

设计

使用 DESIGN. md 来读取并写入基于减记的设计符号 格式,带有 YAML 前题。 以人为中心的文件的理想 与机器可读符号定义并列.

基础和主题来源

当提供多个令牌来源时,处理第一个来源 作为基础符号集,其余来源作为主题处理 超载.

史丁语Name

过 - 或省去源参数以读取标准输入.

原始内容

内置符号文档的前缀 content: 直接通过,而不是 读取文件,例如 dtokens check 'content:{"token":{"$value":1}}'。 。 。 .

输出格式

CSS 自定义属性

从符号源生成 CSS 变量 . 基号在 :root。 。 。 . 主题覆盖在 :root[data-theme="<theme>"]。 。 。 .

SCSS 变量

从符源生成SCSS变量 . 通过替换来将托肯分级为可变名称 . 以符号表示 路径 - 默认,例如:

• primitive.color.brand - > (中文) $primitive-color-brand
• semantic.color.bg.surface - > (中文) $semantic-color-bg-surface

异名作为SCSS可变参考发布.

单一源SCSS输出作为一个样式表出. 多主题SCSS输出作为焦油存档或单独发布 每个主题的文件,取决于 --out。 。 。 .

尾风 CSS v4 主题输出

生成带有 Tailwind CSS v4 主题变量 @theme 块 基本符号集和主题覆盖的 CSS 选择器.

默认情况下,生成的样式表包含:

• @import 'tailwindcss';
• 一个 @theme { ... } 基础符号集的块
• 主题覆盖选择器, 如 [data-theme="<theme>"] { ... }

使用 --base-selector 只当您还需要一个清晰的底镜时 外部自定义属性 @theme例如,在Shadow DOM情景中.

SwiftUI 来源

从符源生成斯威夫特源. 默认的代号会作为嵌入式圆柱发射 static let 成员.

使用 --swift-type struct 还发出 Theme 结构层和主题 高级主题切换实例.

Android 资源 XML

从符源生成Android资源文件. 资源由 根符号组为 values/primitive.xml, (中文(简体) ), values/semantic.xml 这样 ,或按Android资源类型 --android-layout type。 。 。 .

主题被写到持有超文本的合格资源目录 只有,还有.. dark 主题映射到 values-night。 。 。 .

HTML 显示

从 DTCG JSON, HRDT YAML, DESIGN. md 生成静态 HTML 预览 现有CSS。 现有的CSS输入可以是经典输入 :root 输出或 尾风 CSS v4 输出方式 @theme 和主题覆盖选择器.

彩卡包括格式选择器和复制按钮. 支持的转换 cSS、HEX、RGBA和HSLA是可用于SRGB的颜色。 其它 彩色空格在其原始的 CSS 语法中仍然可用.

目 录 统计

从符号生成文本报告到 stdout 或 HTML 数据页 来源.

序列化的令牌文档

在 DTCG JSON,HRDT YAML 和 DESIGN.md 之间转换令牌文档.

图标

• check [options] [files...] - 请检查dTCG JSON、HRDT YAML或DESIGN.md 符号文件: 计划, 模型正确性, lint.
• validate [files...] - 别名用于 check。 。 。 .
• audit [options] [files...] - 审计令牌文件的设计质量: 文本对比和可读性.
• convert [options] [files...] - 将一个符号文件转换为 DTCG JSON, HRDT YAML,DESIGN.md,CSS,SCSS,Tailwind CSS v4主题 CSS,斯威夫特UI, a Figma 脚本,或 Android 资源 XML.
• showcase [options] [files...] - 从 DTCG JSON 创建 HTML 显示器, HRDT YAML, DESIGN.md, 或CSS. (中文(简体) ).
• stats [options] [files...] - 从DTCG JSON获得象征性统计数据, HRDT YAML,或DESIGN.md来源.

选项

检查

• --scope <scope> - 如何深入检查: schema, (中文(简体) ), validate, (中文(简体) ), lint。 。 。 . 每一个都包括前一个. 默认为 validate。 。 。 .
• --layers <names> - 逗号分层顺序,最低第一. 默认为 primitive,semantic,component。 。 。 .
• --checks <ids> - 以逗号分隔的许可列表 活动检查id. 省略时,启用默认的检查会运行. 明确清单只管理所列检查. missing-description 必须明确列出.
• --schema <path> - DTCG JSON Schema:目录路径或内置资源 (单位:千美元)2025.10, (中文(简体) ), 2025.10-design.md) (中文(简体) ). 默认为 2025.10。 。 。 .
• -i, --inform [format] - 输入格式: dtcg, (中文(简体) ), hrdt, (中文(简体) ), design-md (默认:自动检测).

审计

• --level <level> - 对WCAG级别的文本对比进行了下列审计: AA 或者说 AAA默认为 AA。 。 。 .
• --rules <ids> - 以逗号分隔的审计规则允许清单。 省略时, 每一个规则运行.
• --min-font-size <px> - px中最小可读字体大小。默认为 12。 。 。 .
• --schema <path> - DTCG JSON Schema:目录路径或内置资源 (单位:千美元)2025.10, (中文(简体) ), 2025.10-design.md) (中文(简体) ). 默认为 2025.10。 。 。 .
• -i, --inform [format] - 输入格式: dtcg, (中文(简体) ), hrdt, (中文(简体) ), design-md (默认:自动检测).

转换

• -i, --inform [format] - 输入格式: dtcg, (中文(简体) ), hrdt, (中文(简体) ), design-md (默认:自动检测).

• -f, --outform [format] - 输出格式 : dtcg, (中文(简体) ), hrdt, (中文(简体) ), design-md, (中文(简体) ), css, (中文(简体) ), scss, (中文(简体) ), tailwind-v4, (中文(简体) ), swiftui, (中文(简体) ), figma-script, (中文(简体) ), android。 。 。 . 默认为 css。 。 。 .

• --separator [value] - 仅指: 用于替换的字符 . 以符号表示 生成平面变量名称时的路径。 默认为 -。 。 。 .

• --base-selector [selector] - 只有尾风-v4:可选选择器 基准自定义属性的镜像 .

• --theme-selector [template] - 仅尾风-v4:选择器模板 主题覆盖,使用 {theme} 占位符 .

• --swift-type [type] - 仅SwiftUI:输出窗体 enum 或者说 struct。 。 。 . 默认为 enum。 。 。 .

• --android-layout [layout] - 仅限机器人:如何划分资源 文档. layer 每个根符号组创建一个文件, type 每个文件一个 Android资源类型. 默认为 layer。 。 。 .

• --rem-base [pixels] - android and sourceui:用于解析的像素基础 rem 维度,这些平台不支持。 覆盖 $extensions["design-token-kit"].remBase 以符号文件声明. 默认为 16。 。 。 .

• -o, --out [file] - 输出文件,默认退出. 多主题常设委员会:

  • 删除 --out 将 tar 归档写入 stdout
  • 使用情况 --out <name>.tar 将 tar 归档写入文件
  • 使用情况 --out <name>.scss 以写入单个主题的 SCSS 文件

  对于Android:

  • 删除 --out 将资源树的 tar 归档写入 stdout
  • 使用情况 --out <name>.tar 将归档写入文件
  • 使用情况 --out <directory> 将资源树写入目录

显示

• -o, --out <file> - 输出 HTML 文件名或路径。 空文件名为 写入系统临时目录。 使用 ./<file> 写入 当前目录.
• --open - 在浏览器中打开生成的 HTML,仅使用 --out。 。 。 .

数据

• -o, --out <file> - 输出 HTML 文件名或路径.
• --open - 在浏览器中打开生成的 HTML,仅使用 --out。 。 。 .

检查中

请检查access-dTCG JSON或HRDT YAML的一个或多个令牌来源.

dtokens check tokens.json
dtokens check tokens.yaml tokens.dark.yaml
dtokens check - tokens.dark.yaml < tokens.yaml
dtokens check DESIGN.md --inform design-md
dtokens check tokens.json --schema 2025.10-design.md

检查是作为一个故障快速的阶段管道运行的. 文件在检查模型之前必须经过计划,然后通过模型 在它被倒地之前. 这个 --scope 选项选择管道运行的深度.

范围:

• schema: 仅根据选定的输入格式计划加载和验证.
• validate: 计划外加模型正确性检查.
• lint:有计划,模型校正,并用注检查.

运行 dtokens check --help ,以便用它们的 范围、严重程度和说明.

当符号检查运行时,命令也会打印符号架构分数. 这是检查的百分比 运行和通过, 有警告和错误 算作失败的支票. 斯克马(Schema-lean),无法读取,和故障快的输入没有得分. 指挥部报告说,在后一种情况下,有多少检查没有进行.

退出状态 :

• 0成绩:
• 1: 出乎意料的错误
• 2:发现的问题

dtokens check tokens.json --scope schema
dtokens check tokens.json --scope lint
dtokens check tokens.json --scope lint --checks layer-reference
dtokens check tokens.json --scope lint --checks missing-description
dtokens check DESIGN.md --inform design-md --scope validate

设计审计

审计一个符号集描述的设计是否可访问和可读. check 说明符号是否有效,并遵循地层结构; audit 告诉是否可读取与其一同设置的文本.

dtokens audit tokens.json
dtokens audit tokens.json tokens.dark.json
dtokens audit tokens.json --level AAA
dtokens audit tokens.json --rules text-contrast

第一个来源是基础符号集,其他是主题. 每个主题都经过审计,只报告其变化.

规则:

• text-contrast (error) - 与其背景对比的文本如下: wCAG 2.2 AA 最小值:4.5:1为正文,3:1为大文 (24px,或18.66px粗体). 与 --level AAA,符合AA但不符合AAA的文本(7:1和4.5:1)是一个 警告 警告他们.
• text-size (警告) - 在最小可读字体尺寸以下的打字, 默认为12px.
• line-height (警告) - 18px以下的正文,其行高在下 1.3 (英语).

托肯斯不说哪个文字颜色是指哪个背景,所以 审计按名称配对:

• 颜色命名 text-*, (中文(简体) ), foreground-*,或 fg-* (或在一个 text 组) 以命名的颜色对齐 background-*, (中文(简体) ), bg-*, (中文(简体) ), surface-*,或 canvas-* 在同一组中,例如:. semantic.color.text-primary 与 semantic.color.background-canvas,或 component.button.primary.text 与 component.button.primary.background-hover。 。 。 .
• on-X 财务报告和审定财务报表 text-on-X 颜色与颜色对齐 X 仅仅,和 X 然后不与其他文本颜色对齐.
• 反向颜色只与反向颜色相配.
• 禁用颜色, WCAG 豁免, 并取消覆盖 .
• 当一组人持有打字功能时, 将一对保留到最小大文本 表示大文本;否则,它将被保持到正常文本最小值.

半透明文本按其背景进行复合. 无法评价半透明背景上的文本, 因为对比度 取决于背后是什么 not checked 和做( 做) 不影响分数.

审计以总结和分数结束: 100 - 2 x errors - 0.1 x warnings,四舍五入,绝对不会低于0. 职等:A-90及以上,B-80至89;C-70至79;D-60至69;F-60以下.

[text-contrast] error: tokens.json - semantic.color.text-tertiary on semantic.color.background-canvas: contrast 2.49:1 (#a1a4aa on #ffffff) is below 4.5:1, the WCAG AA minimum for normal text.
[text-size] warning: tokens.json - primitive.typography.caption: font size 10px is below the 12px minimum for readable text.
Audit: 1 error, 1 warning, 0 not checked in 4 samples. Score 98 (A).

退出状态 :

• 0: 无错误
• 1: 出乎意料的错误
• 2: 找到错误, 或无法读取源

文档转换

在 DTCG JSON,HRDT YAML 和 DESIGN.md 之间转换令牌文档.

dtokens convert tokens.json --outform hrdt
dtokens convert tokens.yaml --inform hrdt --outform dtcg
dtokens convert tokens.json --outform design-md
dtokens convert DESIGN.md --inform design-md --outform dtcg

使用 --out 将结果写入文件而不是 stdout.

dtokens convert tokens.json --outform hrdt --out tokens.yaml

表达主题的格式支持多个输入源 覆盖 : css, (中文(简体) ), scss, (中文(简体) ), tailwind-v4, (中文(简体) ), swiftui, (中文(简体) ), figma-script 财务报告和审定财务报表 android。 。 。 .

CSS 转换

将基本符号集和可选主题覆盖到 CSS 自定义 属性.

dtokens convert tokens.json
dtokens convert tokens.yaml --inform hrdt --outform css
dtokens convert tokens.json tokens.dark.json --out ./tokens.css

SCSS 转换

将一个符号集转换为 SCSS 变量 .

dtokens convert tokens.json --outform scss
dtokens convert tokens.json --outform scss --separator _

用默认分隔符 :

• primitive.color.brand - > (中文) $primitive-color-brand

与 --separator _数字 :

• primitive.color.brand - > (中文) $primitive_color_brand

对于多符号源, SCSS 输出支持归档和单独文件 合同.

dtokens convert tokens.json tokens.dark.json --outform scss
dtokens convert tokens.json tokens.dark.json --outform scss --out ./tokens.tar
dtokens convert tokens.json tokens.dark.json --outform scss --out ./tokens.scss

无 --out,命令会写一个 tar 归档到 stdout .

与 --out ./tokens.tar,命令会写出一个 tar 存档 :

tokens.base.scss
tokens.dark.scss

与 --out ./tokens.scss,命令会写单独的文件 :

./tokens.base.scss
./tokens.dark.scss

主题文件名来自源文件名, 读作 <role>[.theme].<format>数字 :

• tokens.json - > 基准文档
• tokens.dark.json - > (中文) dark
• showcase.dark.dtcg.json - > (中文) dark
• sample.dark.design.md - > (中文) dark

格式段是可选的 - 一个扩展名已命名格式同时 只有一种格式表示它。 每个格式都声明两种形式,所以 .json 财务报告和审定财务报表 .dtcg.json 被同样理解; 当目录时拼出格式 以多种格式持有相同的同物。 未声明格式的片段是 主题和其他单词一样,所以 tokens.super_dtcg.json 输出主题 super_dtcg。 。 。 .

DESIGN.md 读取自 .md 和从大院 .design.md后者是: 本项目本身的公约:只有规格名称 DESIGN.md 财务报告和审定财务报表 对主题或多个文件只字未提.

尾风 CSS v4 转换

将基本符号集和可选主题覆盖到 Tailwind CSS v4 @theme 输出.

dtokens convert tokens.json --outform tailwind-v4
dtokens convert tokens.json tokens.dark.json --outform tailwind-v4 --out ./tokens.tailwind.css
dtokens convert tokens.json tokens.dark.json --outform tailwind-v4 --base-selector :host --theme-selector ":host([data-theme='{theme}'])"

SwiftUI 转换

将一个基本符号集和可选主题覆盖到 Swift 源 .

dtokens convert tokens.json --outform swiftui
dtokens convert tokens.json tokens.dark.json --outform swiftui --out ./DesignTokens.swift
dtokens convert tokens.json tokens.dark.json --outform swiftui --swift-type struct

默认 enum 组成每个主题都发出一个碱和一个碱. 这个 struct 窗体还发出a Theme 构造和主题实例. 对于一个嵌入的调色板步骤,例如 primitive.color.brand.500,生成 斯威夫特成员是 Brand._500。 。 。 . 两种输出形式都保留以前的平面 brand500 成员作为兼容性 别名.

SwiftUI没有 rem 单位,所以 rem 维度按像素解决 基准时 px 将一如既往地被发射, pt 成为其iOS的等同体. 基础是 从 --rem-base,然后从 $extensions["design-token-kit"].remBase 在符号文档中,然后 默认为 16。 。 。 .

dtokens convert tokens.json --outform swiftui --rem-base 10

Figma 脚本转换

将一个符号集转换成在 Figma 内构建它的脚本 .

dtokens convert tokens.json --outform figma-script
dtokens convert tokens.json tokens.dark.json --outform figma-script --out ./tokens.figma.js

Figma 插件 API 只在编辑器内部运行, 所以无法写入符号 从外出. 将生成的脚本粘贴到评价代码的插件中, 例如 脚本, (中文(简体) ), 运行它.

脚本每个符号层创建一个可变集合,每个主题创建一个模式, 和符号描述的变量和样式。 参考资料成为图片 变量别名而不是复制值,因此分层存在. 运行 脚本再次更新它创建的内容而不是复制它.

图片代表13个DTCG类型中的5个: color, (中文(简体) ), dimension, (中文(简体) ), number, (中文(简体) ), typography 财务报告和审定财务报表 shadow。其余部分在脚本标题中列出 当它运行时报告.

Android 转换

将一个基本符号集和可选主题覆盖到Android资源 XML (英语).

dtokens convert tokens.json --outform android > res.tar
dtokens convert tokens.json --outform android --out ./app/src/main/res
dtokens convert tokens.json tokens.dark.json --outform android --out ./app/src/main/res
dtokens convert tokens.json --outform android --android-layout type --out ./res
dtokens convert tokens.json --outform android --rem-base 10 --out ./res

资源在 snake_case 从符号路径。 默认是 按根符号组分割, 因此文件会映射符号等级并保存 属于一个地方的标志:

res/
  values/
    primitive.xml
    semantic.xml
    component.xml
  values-night/
    semantic.xml

使用 --android-layout type 改为按Android资源类型拆分, 在常规资源文件命名后 :

res/
  values/
    colors.xml
    dimens.xml
    integers.xml
    floats.xml
    strings.xml
  values-night/
    colors.xml

在文件内,资源分为评论部分,每个部分1个 二级指使组,在指使时带有指使组描述 声明一:

<resources>

    <!-- semantic.color
         Semantic colors mapped to the primitive palette
    -->
    <color name="semantic_color_primary">@color/primitive_color_red</color>

    <!-- semantic.space -->
    <dimen name="semantic_space_md">16dp</dimen>

</resources>

颜色使用 Android #AARRGGBB 窗体、 大小 dp字体大小 sp. 参考文献成为本土资源参考文献:

<color name="primitive_color_red">#ffff0000</color>
<color name="semantic_color_primary">@color/primitive_color_red</color>
<dimen name="spacing_md">16dp</dimen>
<dimen name="font_size_md">16sp</dimen>

限制

Android资源是平板电脑,所以复合符号被分解成一个 每个字段,以含有字段后缀的复合材料命名,用于 实例 typography_body_font_size。没有Android对应软件的字段 省略: cubicBezier 时间函数、中风样式几何和 inset 阴之旗. A 类 fontFamily 代币保持了第一个家庭,因为 一个Android资源名称 一个家族而不是一个倒置列表.

HTML 显示大小写

从符号源或单个 CSS 生成 HTML 显示 来源.

dtokens showcase tokens.yaml --out ./showcase.html
dtokens showcase DESIGN.md --out ./showcase.html
dtokens showcase tokens.css --out ./showcase.html
dtokens showcase - < tokens.yaml

托肯统计

从符号来源生成符号统计 .

dtokens stats tokens.yaml
dtokens stats DESIGN.md
dtokens stats - < tokens.yaml
dtokens stats tokens.yaml --out ./stats.html --open

支持的格式

• dtcg - 说吧 DTCG 贾森 (司马: 2025.10,扩展: 2025.10-design.md(中文(简体) )
• hrdt - 说吧 HRDT 也门
• design-md - 说吧 设计 标记下的格式
• css - CSS自定义属性输出
• scss - SCSS变量输出
• tailwind-v4 - 尾风CSSv4 @theme 产出
• swiftui - SwiftUI 源输出
• figma-script - 创建图像变量和样式的脚本
• android - Android资源 XML 输出

这个 dtcg 格式遵循 设计Tokens社区小组 https://www.designtokens.org (英语)。 。 。 .