@csstools/postcss-design-tokens

中文文档

5.0.2发布于 2026/10/01MIT-0TypeScriptES Module近 30 天下载 9789

在您的 CSS 中使用设计符号

文档目录11 节

使用量
格式
选项
实值
单位和值
自定义函数和规则名称
语法
编辑器支持
@design-tokens 规则
design-token() 函数
进一步阅读

PostCSS 设计托肯斯

npm install @csstools/postcss-design-tokens --save-dev

PostCSS 设计托肯斯让您在 CSS 源文件中使用设计符号 .

{
    "color": {
        "background": {
            "primary": { "value": "#fff" }
        }
    },
    "size": {
        "spacing": {
            "small": { "value": "16px" },
            "medium": { "value": "18px" },
            "medium-alias": { "value": "{size.spacing.medium}" }
        }
    },
    "viewport": {
        "medium": { "value": "35rem" }
    }
}

@design-tokens url('./tokens.json') format('style-dictionary3');

.foo {
    color: design-token('color.background.primary');
    padding-top: design-token('size.spacing.small');
    padding-left: design-token('size.spacing.small' to px);
    padding-bottom: design-token('size.spacing.small' to rem);
}

@media (min-width: design-token('viewport.medium')) {
    .foo {
        padding-bottom: design-token('size.spacing.medium-alias' to rem);
    }
}

/* becomes */

.foo {
    color: #fff;
    padding-top: 16px;
    padding-left: 16px;
    padding-bottom: 1rem;
}

@media (min-width: 35rem) {
    .foo {
        padding-bottom: 1.125rem;
    }
}

使用量

添加 PostCSS 设计托肯斯对您的项目:

npm install postcss @csstools/postcss-design-tokens --save-dev

当作一个邮政插件 :

const postcss = require('postcss');
const postcssDesignTokens = require('@csstools/postcss-design-tokens');

postcss([
    postcssDesignTokens(/* pluginOptions */)
]).process(YOUR_CSS /*, processOptions */);

格式

目前,设计标志没有标准格式. 尽管正在努力建立这一机制,但我们认为通过这一机制还为时过早.

目前我们只支持样式词典。。。 . 使用 style-dictionary3 内 @design-tokens 规则选择此格式.

选项

实值

这个 is 选项决定使用哪种设计符号.
它允许您生成多个主题样式表
以不同的配置运行 PostCSS 多次.

只默认 @design-tokens 没有 when('foo') 使用条件.

此插件本身不产生多出输出,只提供API来改变输出.

示例用途

对于这两个符号文件:

{
    "color": {
        "background": {
            "primary": { "value": "#0ff" }
        }
    }
}

{
    "color": {
        "background": {
            "primary": { "value": "#f0f" }
        }
    }
}

而这个CSS:

@design-tokens url('./tokens-brand-1.json') format('style-dictionary3');
@design-tokens url('./tokens-brand-2.json') when('brand-2') format('style-dictionary3');

.foo {
    color: design-token('color.background.primary');
}

您可以配置 :

没有 `is` 选项.

postcssDesignTokens()

@design-tokens url('./tokens-brand-1.json') format('style-dictionary3');
@design-tokens url('./tokens-brand-2.json') when('brand-2') format('style-dictionary3');

.foo {
    color: design-token('color.background.primary');
}

/* becomes */

.foo {
    color: #0ff;
}

`is` 选项设置为“ brand-2”.

postcssDesignTokens({ is: ['brand-2'] })

@design-tokens url('./tokens-brand-1.json') format('style-dictionary3');
@design-tokens url('./tokens-brand-2.json') when('brand-2') format('style-dictionary3');

.foo {
    color: design-token('color.background.primary');
}

/* becomes */

.foo {
    color: #f0f;
}

单位和值

这个 unitsAndValues 选项允许您控制设计值转换为 CSS 的某些方面. rem < - > (中文(简体) ) px 例如,只有在我们知道根字体大小时才能计算.

root 关闭大小

默认为 16

postcssDesignTokens({
    unitsAndValues: {
        rootFontSize: 20,
    },
})

@design-tokens url('./tokens.json') format('style-dictionary3');

.foo {
    color: design-token('color.background.primary');
    padding-top: design-token('size.spacing.small');
    padding-left: design-token('size.spacing.small' to px);
    padding-bottom: design-token('size.spacing.small' to rem);
}

@media (min-width: design-token('viewport.medium')) {
    .foo {
        padding-bottom: design-token('size.spacing.medium-alias' to rem);
    }
}

/* becomes */

.foo {
    color: #fff;
    padding-top: 16px;
    padding-left: 16px;
    padding-bottom: 0.8rem;
}

@media (min-width: 35rem) {
    .foo {
        padding-bottom: 0.9rem;
    }
}

自定义函数和规则名称

导入规则Name

这个 importAtRuleName 选项允许您为 @design-tokens。。。 .

postcssDesignTokens({ importAtRuleName: 'tokens' })

@tokens url('./tokens.json') format('style-dictionary3');

.foo {
    color: design-token('color.background.primary');
    padding-top: design-token('size.spacing.small');
    padding-left: design-token('size.spacing.small' to px);
    padding-bottom: design-token('size.spacing.small' to rem);
}

/* becomes */

.foo {
    color: #fff;
    padding-top: 16px;
    padding-left: 16px;
    padding-bottom: 1rem;
}

函数Name

这个 valueFunctionName 选项允许您为 design-token。。。 .

postcssDesignTokens({ valueFunctionName: 'token' })

@design-tokens url('./tokens.json') format('style-dictionary3');

.foo {
    color: token('color.background.primary');
    padding-top: token('size.spacing.small');
    padding-left: token('size.spacing.small' to px);
    padding-bottom: token('size.spacing.small' to rem);
}

/* becomes */

.foo {
    color: #fff;
    padding-top: 16px;
    padding-left: 16px;
    padding-bottom: 1rem;
}

语法

PostCSS 设计托肯斯非标准,不属于任何官方CSS规格.

编辑器支持

这都是非常新的,我们希望有一天,设计符号将成为编辑和其他工具的一等公民. 在此之前,我们将尽最大努力提供延期. 这些边会很粗糙,但如果我们想去的话,应该说明一下.

编辑器	插件
虚拟系统	CSS 工具设计

`@design-tokens` 规则

这个 @design-tokens 规则用于从 JSON 文件导入设计符号到您的 CSS .

@design-tokens url('./tokens.json') format('style-dictionary3');

@design-tokens url('./tokens.json') format('style-dictionary3');
@design-tokens url('./tokens-dark-mode.json') format('style-dictionary3') when('dark');

您也可以从一个 npm 软件包 :

@design-tokens url('node_modules:my-npm-package/tokens.json') format('style-dictionary3');
@design-tokens url('node_modules:my-npm-package/tokens-dark-mode.json') format('style-dictionary3') when('dark');

@design-tokens [ <url> | <string> ]
               [ when(<theme-condition>*) ]?
               format(<format-name>);

<theme-condition> = <string>

<format-name> = [ 'style-dictionary3' ]

全体 @design-tokens 文件中的规则按出场顺序加以评价. 如果一个同道同名的标志已经存在,它将被推翻.

全体 @design-tokens 规则在任何 design-token() 函数.

@design-tokens 规则可以通过 when 条件。可在 when。。。 .
多重条件总是 AND 关系.

/* only evaluated when tooling receives 'blue' and 'muted' as arguments */
@design-tokens url('./tokens.json') format('style-dictionary3') when('blue' 'muted');

@design-tokens 规则永远不能通过 @supports, (中文(简体) ), @media 或其他有条件的规则.

@media (min-width: 500px) {
  @design-tokens url('./tokens.json') format('style-dictionary3'); /* always evaluated */
}

任何形式的筑巢都毫无意义, @design-tokens 将永远被评价为最高层申报.

`design-token()` 函数

这个 design-token() 函数取一个符号路径并返回符号值.

.foo {
    color: design-token('color.background.primary');
}

design-token() = design-token( <token-path> [ to <unit> ]? )

<token-path> = <string>
<unit> = [ px | rem | ... ]

插件可以转换 px 改为 rem 财务报告和审定财务报表 rem 改为 px 通过 unitsandvalues 插件选项 . 当设计符号为无单位时 unit 可指定为 to。。。 .

样式林

Stylelint 能够检查未知的属性值 . 设置此规则的正确配置可以检查甚至非标准的语法.

    // Disallow unknown values for properties within declarations.
    'declaration-property-value-no-unknown': [
        true,
        {
            propertiesSyntax: {
                color: '| <design-token()>',
                // ... more properties ...
            },
            typesSyntax: {
                '<design-token()>': 'design-token( <string> [ to <ident> ]? )',
            },
        },
    ],

进一步阅读

版本与发布记录

@csstools/postcss-design-tokens 共发布 30 个版本，首次发布于 2022/05/23；过去 12 个月发布了 3 个版本。

版本	发布日期	距今
`5.0.2`latest	2026/10/01	1 个月前
`5.0.1`	2026/09/25	1 个月前
`5.0.0`	2026/01/14	9 个月前
`4.0.5`	2025/05/27	1.5 年前
`4.0.4`	2024/11/02	2 年前
`4.0.3`	2024/10/24	2 年前

关于 @csstools/postcss-design-tokens 的常见问题

@csstools/postcss-design-tokens 是什么？

在您的 CSS 中使用设计符号

如何安装 @csstools/postcss-design-tokens？

在项目目录运行 npm install @csstools/postcss-design-tokens，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：postcss（^8.4）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

@csstools/postcss-design-tokens 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

@csstools/postcss-design-tokens 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module，更早的版本需要改用动态 import()。

@csstools/postcss-design-tokens 需要什么版本的 Node.js？

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

@csstools/postcss-design-tokens 可以商用吗？

@csstools/postcss-design-tokens 使用 MIT-0 许可。声明的许可为 MIT-0，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

@csstools/postcss-design-tokens 的下载量有多少？

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

@csstools/postcss-design-tokens 还在维护吗？

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

npm install @csstools/postcss-design-tokens

pnpmpnpm add @csstools/postcss-design-tokens
yarnyarn add @csstools/postcss-design-tokens
bunbun add @csstools/postcss-design-tokens

peer 依赖postcss ^8.4

npm 7+ 与 pnpm 8+ 会自动安装必需的 peer 依赖，Yarn 需手动安装。

在你的项目目录中运行此命令。

近 30 天下载

9,789

约 9789 次日均 326 次

统计周期 2026/10/11 – 2026/11/09
数据来自 npm 官方下载统计，今天更新

最新版本5.0.2发布于 1 个月前

开源许可MIT-0其他许可

包体积23.5 kB6 个文件 · 解压后

运行依赖3 个另有 1 个 peer 依赖

模块格式ES Module

TypeScript自带类型

Node.js>=20.19.0

发布版本30 个近 12 个月 3 个

首次发布2022/05/234 年前

元数据更新2026/10/01

每一个软件包背后，
都有分享与创造的人。