# @csstools/postcss-design-tokens 中文文档 规范地址：https://npmcn.com/package/%40csstools/postcss-design-tokens/ 版本：5\.0\.2 npm 元数据更新时间：2026-10-01T06:14:39.957Z 中文译文更新时间：2026-11-11T03:33:25.154Z 软件包许可：MIT-0 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40csstools/postcss-design-tokens 原文对照：https://npmcn.com/package/%40csstools/postcss-design-tokens/?lang=original 项目主页：https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-design-tokens#readme 源码仓库：https://github.com/csstools/postcss-plugins ## 关键信息（来自 npm 元数据） - 包体积（解压后）：23.5 kB，6 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - Node.js 要求：\>=20\.19\.0 - 运行依赖：3 个 - peer 依赖：postcss ^8\.4 - 首次发布：2022-05-23T05:37:48.480Z - 最新版本发布：2026-10-01T06:14:39.661Z - 近 30 天下载量：9789（2026-10-11 至 2026-11-09，npm 官方下载统计） - 已发布版本数：30（近 12 个月 3 个） ## 中文简介 在您的 CSS 中使用设计符号 ## 安装 ```sh npm install @csstools/postcss-design-tokens ``` 也可以使用：`pnpm add @csstools/postcss-design-tokens`、`yarn add @csstools/postcss-design-tokens`、`bun add @csstools/postcss-design-tokens` ## README # PostCSS 设计托肯斯 [![PostCSS Logo](https://postcss.github.io/postcss/logo.svg)](https://github.com/postcss/postcss) `npm install @csstools/postcss-design-tokens --save-dev` [PostCSS 设计托肯斯](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-design-tokens) 让您在 CSS 源文件中使用设计符号 . ```json { "color": { "background": { "primary": { "value": "#fff" } } }, "size": { "spacing": { "small": { "value": "16px" }, "medium": { "value": "18px" }, "medium-alias": { "value": "{size.spacing.medium}" } } }, "viewport": { "medium": { "value": "35rem" } } } ``` ```css @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 设计托肯斯](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-design-tokens) 对您的项目: ```bash npm install postcss @csstools/postcss-design-tokens --save-dev ``` 当作一个 [邮政](https://github.com/postcss/postcss) 插件 : ```js const postcss = require('postcss'); const postcssDesignTokens = require('@csstools/postcss-design-tokens'); postcss([ postcssDesignTokens(/* pluginOptions */) ]).process(YOUR_CSS /*, processOptions */); ``` ## 格式 目前,设计标志没有标准格式. 尽管正在努力建立这一机制,但我们认为通过这一机制还为时过早. 目前我们只支持 [样式词典](https://amzn.github.io/style-dictionary/#/)。 。 。 . 使用 `style-dictionary3` 内 `@design-tokens` 规则选择此格式. ## 选项 ### 实值 这个 `is` 选项决定使用哪种设计符号. 它允许您生成多个主题样式表 以不同的配置运行 PostCSS 多次. 只默认 `@design-tokens` 没有 `when('foo')` 使用条件. _此插件本身不产生多出输出,只提供API来改变输出._ #### 示例用途 **对于这两个符号文件:** ```json { "color": { "background": { "primary": { "value": "#0ff" } } } } ``` ```json { "color": { "background": { "primary": { "value": "#f0f" } } } } ``` **而这个CSS:** ```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` 选项. ```js postcssDesignTokens() ``` ```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'); } /* becomes */ .foo { color: #0ff; } ``` ##### `is` 选项设置为“ brand-2”. ```js postcssDesignTokens({ is: ['brand-2'] }) ``` ```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'); } /* becomes */ .foo { color: #f0f; } ``` ### 单位和值 这个 `unitsAndValues` 选项允许您控制设计值转换为 CSS 的某些方面. `rem` < - > (中文(简体) ) `px` 例如,只有在我们知道根字体大小时才能计算. #### root 关闭大小 默认为 `16` ```js postcssDesignTokens({ unitsAndValues: { rootFontSize: 20, }, }) ``` ```css @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`。 。 。 . ```js postcssDesignTokens({ importAtRuleName: 'tokens' }) ``` ```css @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`。 。 。 . ```js postcssDesignTokens({ valueFunctionName: 'token' }) ``` ```css @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 设计托肯斯](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-design-tokens) 非标准,不属于任何官方CSS规格. ### 编辑器支持 这都是非常新的,我们希望有一天,设计符号将成为编辑和其他工具的一等公民. 在此之前,我们将尽最大努力提供延期. 这些边会很粗糙,但如果我们想去的话,应该说明一下. | 编辑器 | 插件 | | --- | --- | | 虚拟系统 | [CSS 工具设计](https://marketplace.visualstudio.com/items?itemName=RomainMenke.csstools-design-tokens) | ### `@design-tokens` 规则 这个 `@design-tokens` 规则用于从 JSON 文件导入设计符号到您的 CSS . ```css @design-tokens url('./tokens.json') format('style-dictionary3'); ``` ```css @design-tokens url('./tokens.json') format('style-dictionary3'); @design-tokens url('./tokens-dark-mode.json') format('style-dictionary3') when('dark'); ``` 您也可以从一个 `npm` 软件包 : ```css @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 [ | ] [ when(*) ]? format(); = = [ 'style-dictionary3' ] ``` 全体 `@design-tokens` 文件中的规则按出场顺序加以评价. 如果一个同道同名的标志已经存在,它将被推翻. 全体 `@design-tokens` 规则在任何 `design-token()` 函数. `@design-tokens` 规则可以通过 `when` 条件。 可在 `when`。 。 。 . 多重条件总是 `AND` 关系. > ```css > /* 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` 或其他有条件的规则. > ```css > @media (min-width: 500px) { > @design-tokens url('./tokens.json') format('style-dictionary3'); /* always evaluated */ > } > ``` 任何形式的筑巢都毫无意义, `@design-tokens` 将永远被评价为最高层申报. ### `design-token()` 函数 这个 `design-token()` 函数取一个符号路径并返回符号值. ```css .foo { color: design-token('color.background.primary'); } ``` ``` design-token() = design-token( [ to ]? ) = = [ px | rem | ... ] ``` 插件可以转换 `px` 改为 `rem` 财务报告和审定财务报表 `rem` 改为 `px` 通过 [`unitsandvalues`](https://npmcn.com/package/%40csstools/postcss-design-tokens/#readme-unitsandvalues) 插件选项 . 当设计符号为无单位时 `unit` 可指定为 `to`。 。 。 . #### [样式林](https://stylelint.io/user-guide/rules/declaration-property-value-no-unknown/#propertiessyntax--property-syntax-) Stylelint 能够检查未知的属性值 . 设置此规则的正确配置可以检查甚至非标准的语法. ```js // Disallow unknown values for properties within declarations. 'declaration-property-value-no-unknown': [ true, { propertiesSyntax: { color: '| ', // ... more properties ... }, typesSyntax: { '': 'design-token( [ to ]? )', }, }, ], ``` ## 进一步阅读 - [为什么我们觉得需要PostCSS设计托肯斯](https://github.com/csstools/postcss-plugins/wiki/Why-we-think-PostCSS-Design-Tokens-is-needed) - [关于设计托肯斯( Adobe spectrum)](https://spectrum.adobe.com/page/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 和提交记录判断。