# @amsterdam/design-system-tokens 中文文档规范地址：https://npmcn.com/package/%40amsterdam/design-system-tokens/ 版本：4\.4\.0 npm 元数据更新时间：2026-10-22T13:55:31.016Z 中文译文更新时间：2026-11-06T01:39:56.190Z 软件包许可：SEE LICENSE IN LICENSE\.md 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。原始 npm 页面：https://www.npmjs.com/package/%40amsterdam/design-system-tokens 原文对照：https://npmcn.com/package/%40amsterdam/design-system-tokens/?lang=original 项目主页：https://designsystem.amsterdam/ 源码仓库：https://github.com/Amsterdam/design-system ## 关键信息（来自 npm 元数据） - 包体积（解压后）：606 kB，21 个文件 - 模块格式：ES Module - TypeScript 类型：未声明 - 运行依赖：0 个 - 首次发布：2023-02-10T13:23:11.221Z - 最新版本发布：2026-10-22T13:55:30.210Z - 近 30 天下载量：12335（2026-10-06 至 2026-11-04，npm 官方下载统计） - 已发布版本数：43（近 12 个月 12 个） ## 中文简介阿姆斯特丹设计系统的所有设计标志. 用它将其外观设计应用于您的网站或应用程序. ## 安装 ```sh npm install @amsterdam/design-system-tokens ``` 也可以使用：`pnpm add @amsterdam/design-system-tokens`、`yarn add @amsterdam/design-system-tokens`、`bun add @amsterdam/design-system-tokens` ## README # 阿姆斯特丹设计系统:托肯斯此软件包提供来自 [阿姆斯特丹设计系统](https://designsystem.amsterdam/)。。。 . 使用它将其外观设计应用到您的网站上. 令牌以多种格式被导出,包括CSS自定义属性和JSON,使其与大多数,甚至全部的技术堆栈相兼容. **说明** 这个套件中象征着的价值观实现了阿姆斯特丹市的品牌化. 如果你的项目不属于阿姆斯特丹市, 你不应该使用这个包. 如果将值更改为自己的品牌,则允许复制符号文件 . ## 导言每个设计符号都是代表单一外观设计选择的变量. 对颜色,文字的各个方面,间隔长度,边框宽度,动画的配置等等,都存在托肯斯. 每个令牌的值在CSS中有效. 所有标志一起构成了一个主题,将阿姆斯特丹市的整个品牌编码. ## 安装如果您想要或需要直接在样式表中引用符号,则自行安装此软件包. 注意我们 [CSS 组件](https://www.npmjs.com/package/@amsterdam/design-system-css) 财务报告和审定财务报表 [反应组件](https://www.npmjs.com/package/@amsterdam/design-system-react) 提供更多的功能并自动应用符号. 如果您的应用程序使用React, 或者它允许您应用 HTML 类, 您应该使用这些软件包 . ```sh npm install @amsterdam/design-system-tokens ``` ## CSS中的使用量托肯斯在CSS中通常被用作自定义属性. 他们的名字始于 `--ams-`。。。 . ### 主样式表此软件包提供了包含所有符号的主样式表. 它们被宣布为全球CSS变量 `:root` 选择器. ```ts import "@amsterdam/design-system-tokens/dist/index.css" ``` 如果这对您的项目不起作用, 请使用 `index.theme.css` 相反,它使用 `.ams-theme` 选择器. 将此类添加到您的应用程序的根元素中 . ```ts import "@amsterdam/design-system-tokens/dist/index.theme.css" ``` ```html … ``` ### 压缩覆盖我们的视觉风格相当宽敞. 这对公共网站很有效. 主样式表执行此“ 简单模式” 作为默认 . 内部网站需要高密度布局并减少白色空间和较小文本,可使用紧凑样式表. 请注意, 紧凑样式表不是独立的 – 它只包含覆盖 . 在主样式表之后导入它以获取正确结果 . ```ts import "@amsterdam/design-system-tokens/dist/index.css" import "@amsterdam/design-system-tokens/dist/compact.css" ``` 对 `compact.theme.css` 与 `index.theme.css` 如果你通过一个类而不是通过一个类来应用符号 `:root`。。。 . 在主样式表之后导入, 并添加 `ams-theme--compact` 分类到带有 `ams-theme` 课. ```ts import "@amsterdam/design-system-tokens/dist/index.theme.css" import "@amsterdam/design-system-tokens/dist/compact.theme.css" ``` ```html … ``` ### Lo-fi 覆盖一个Lo-fi样式表可以将进行中的工作作为草图而非完成页来呈现. 它使所有组件都以灰度为单位,用手写相接符来替换文本,给边框一个手绘圆形,并显示交叉的占位符框而不是图像. 版面、尺寸和间隔保持不变,因此页保持其现实结构. 此样式表仅包含覆盖 . 在主样式表后导入它, 连同我们资产包中的 Redacted 脚本字体 . ```ts import "@amsterdam/design-system-tokens/dist/index.css" import "@amsterdam/design-system-tokens/dist/lo-fi.css" import "@amsterdam/design-system-assets/font/lo-fi/index.css" ``` 对 `lo-fi.theme.css` 与 `index.theme.css` 如果你通过一个类而不是通过一个类来应用符号 `:root`。。。 . 添加数据 `ams-theme--lo-fi` 分类到带有 `ams-theme` 课. ```ts import "@amsterdam/design-system-tokens/dist/index.theme.css" import "@amsterdam/design-system-tokens/dist/lo-fi.theme.css" import "@amsterdam/design-system-assets/font/lo-fi/index.css" ``` ```html … ``` Lo-fi Mode 自由地与 Contract Mode 结合. ### 在哪里应用模式样式表要覆盖符号值,必须与其所覆盖的符号在同一元素上声明. 这个要素是 `html` 当您使用时 `index.css`,并带有 `ams-theme` 使用时的类 `index.theme.css`。。。 . 应用模式类 `ams-theme--compact` 其它任何地方,甚至对一个带有 `ams-theme` 类 – 只部分生效 . 模式样式表宣布的符号, 例如 `--ams-space-xl`中,请将新值带到那里. 提及它们的其他任何标志都保留它在所申报的元素上解决的价值. 我们的部件大多读取了这些符号,所以它们默默地保持了它们的宽敞价值. 原因是CSS解决了 `var()` 提及自定义财产中申报该财产的要件. 譬如说, `--ams-paragraph-font-size` 提及 `--ams-typography-body-text-font-size` 并在根元素上宣告,在根元素中它决定宽大的字体大小. 文档中一个更深的段落继承了已解决的值,因此更下方的打字符太迟了. 因此,不支持对页面的一部分应用一个模式:我们的组件不会遵循它. ### 三层道具分为三层:品牌,通用和组件. #### 品牌标志这些表现了阿姆斯特丹市的企业身份. 它们是我们从所有可能的颜色,文本特征,间隔长度,边框宽度等基本选择. 他们的名字从我们的前缀开始,然后是诸如 " 颜色 " 、 " 文字 " 或 " 空间 " 等设计类别. 实例: ```css :root { --ams-color-feedback-error: #ec0000; --ams-space-m: 1rem; --ams-aspect-ratio-4-3: 4 / 3; --ams-border-width-l: 0.1875rem; } ``` 寻找 [品牌标志列表](https://github.com/Amsterdam/design-system/tree/main/packages-proprietary/tokens/src/brand/ams) (原始内容存档于2018-09-29). on GitHub. ##### 删除 " 默认 " 密钥一些品牌标志包括JSON中的"默认"密钥,以允许额外的变体,例如: `ams.color.interactive.default` 财务报告和审定财务报表 `ams.color.interactive.disabled` 然而,对于平坦变量的集合,像我们的CSS自定义属性一样,不需要这个键. 因此,我们在未记名变量中去掉这个键. 比如说, `--ams-color-interactive` 财务报告和审定财务报表 `--ams-color-interactive-disabled`。。。 . #### 常见符号相關元件都具有外观设计特征. 例如,所有链接都有相同的颜色,而不同形式输入的边框同样厚. 共同的标志表达了这些关系并简化了未来的变化. 他们的名字从我们的前缀开始,然后是使用他们的团体的名称. 这个组名是复数来表示几个组件应用了这些符号. 设计系统组件尽可能使用共同的符号. 应用程序中可以创建的自定义组件也是如此. ```html … ``` ```css .my-input { color: var(--ams-links-color); text-underline-offset: var(--ams-links-text-underline-offset); } ``` 寻找 [常见符号列表](https://github.com/Amsterdam/design-system/tree/main/packages-proprietary/tokens/src/common/ams) (原始内容存档于2018-09-29). on GitHub. #### 组件符号每个设计系统组件都为每一个表达出品牌的地产定义了符号,并在其样式表中使用. 在重新创建现有组件时使用这些符号来接收当前和未来的正确值. 不要将这些符号应用到其他组件 – 组件必须是独立的. 一个组件符号的名称以使用它的CSS属性结尾,例如. `-font-size`。。。 . 我们跟着 [nL 设计系统符号命名准则](https://nldesignsystem.nl/handboek/design-tokens/#naamgeving) 在这里. ```html ``` ```css .my-button { font-family: var(--ams-button-font-family); background-color: var(--ams-button-primary-background-color); } ``` 寻找 [组件符号列表](https://github.com/Amsterdam/design-system/tree/main/packages-proprietary/tokens/src/component/ams) (原始内容存档于2018-09-29). on GitHub. #### 逻辑视图端口内置大小符一些组件符号因取景口断点而异并跟随 [CSS 逻辑属性](https://developer.mozilla.org/en-US/docs/Glossary/Logical_properties) 名称 : - `vi` 表示 _视图内行大小_。。。 . - 使用的断点特定变体 `vi-medium` 财务报告和审定财务报表 `vi-wide`,例如: - `ams.menu.vi-wide.padding-inline` - `ams.dialog.vi-medium.inline-size` - `ams.grid.vi-medium.column-count` 组件也可以使用 `narrow`, (中文(简体) ), `medium` 或者说 `wide` 没有键 `vi` 当维度是组件所固有的,而不是与活式视图断点相接时,前缀. ### 覆盖符牌这个软件包允许创建一个主题来重新利用我们的组件来换个品牌. 这是一种关键特征 [NL 设计系统](https://nldesignsystem.nl/) 我们是其中的一部分. 然而,阿姆斯特丹市的网站必须尽可能紧跟设计系统. 我们重复一遍:阿姆斯特丹市的网站必须尽可能紧跟设计系统. 与此同时,我们意识到,采用设计系统在实践中可能构成挑战. 如果有很好的理由(暂时)调整一个组件,则通过在单独的样式表上压倒其相应符号的值来这样做. 注意重新定义一个符号的值是一种比重新声明样式,添加类名甚至入行样式更好的方法. ## 折耗令牌被贬损的代币一直工作到被移除为止,所以它必须始终具有真正的价值. 我们通过DTCG提供理由和迁移途径 `$deprecated` 字段. 当有直接替换时,以 ``Use `` instead.`` 以删除日期结束每封信件 : `Will be removed on or after YYYY-MM-DD.` ### 重新命名一个符号在贬值窗口中保持旧名完好无损,同时为同值添加新名. 通过 a 连接重命名 `var()` 后退,所以下游覆盖旧名继续工作. 1. 标出已贬值的令牌 `$value` 在替换时,它决定了相同的值: ```jsonc "medium": { "padding-inline": { "$deprecated": "Use `ams.grid.vi-medium.padding-inline` instead. Will be removed on or after 2026-10-20.", "$value": "{ams.grid.vi-medium.padding-inline}" } } ``` 2. 在组件CSS中,首先引用已贬值的代号,以替换为倒置: 在组件样式表中也标出折旧; 不需要从符号文件中复制细节 . ```css padding-inline: var(--ams-grid-medium-padding-inline /* @deprecated */, var(--ams-grid-vi-medium-padding-inline)); ``` 3. 如果一个主题超过替换(例如 Contracting Mode), 超过替换符号就足够了, 因为已贬值的符号引用它 . 只有在主题符号文件中重现已贬值的符号时,才能为遗留的消费者重覆已贬值的符号本身. ### 删除一个符号移除将永远是突破性的改变,因此它必须是重大释放的一部分. 尽早计划贬值,因为它必须至少停留六个月. 由于我们认为下游用户的视觉后果是突破性的改变,因此在贬值窗口中,信使的值不能改变. ```jsonc "row-gap": { "$deprecated": "Whitespace is now applied through the `ams.description-list.*.margin-block-end` tokens. Will be removed on or after 2026-10-20.", "$value": "(unchanged value)" } ``` 在样式表上也显示去向. ```css row-gap: var(--ams-description-list-row-gap); /* @deprecated Will be removed on or after 2026-10-20. */ ``` ## 托肯类型托肯可能使用 DTCG 定义其类型 `$type`,或者,在没有适用标准DTCG类型时,使用我们阿姆斯特丹特有的 `$extensions.nl.amsterdam.type`。。。 . 参考书目继承了他们提到的符号类型. 我们还使用集团级的继承,其中一个集团中的所有符都具有相同的DTCG类型. A 类 `$type` 设定在一个群体上,适用于其所有后人,因此单个的符号不需要重复. ### DTCG 标准类型以下类型来自 [设计托肯斯社区小组规格](https://www.designtokens.org/tr/2025.10/format/)数字 : | 类型 | 说明 | | --- | --- | | `color` | 任何颜色值 | | `dimension` | 任何带有单位的维 | | `duration` | 时间长度 | | `fontFamily` | 字体家族定义(字符串数组) | | `fontWeight` | 字体重量值 | | `number` | 无单位数字值 | | `shadow` | 框式阴影定义 | ### 自定义扩展名 #### 类型我们在下面添加自定义类型 `$extensions.nl.amsterdam.type` 用于: 1. 指向另一个符号的符号 2. dTCG 规格未覆盖的属性 3. 不符合标准类型的值我们使用这些类型来帮助决定在每个组件的文档页面 Design Tokens 表中提供哪个预览 . | 类型 | 说明 | | --- | --- | | `aspectRatio` | 光谱比值 | | `backgroundImage` | 背景图像值( 如 SVGs) | | `backgroundPosition` | 背景位置值 | | `border` | 边框快取值 | | `borderRadius` | 边框半径值 | | `borderStyle` | 边框样式值 | | `borderWidth` | 边框厚度值 | | `cursor` | 光标值 | | `dimension` | 反应维度 | | `fontSize` | 字体大小值 | | `gridTemplateColumns` | 网格轨道定义 | | `hyphenateLimitChars` | 连字符限制值 | | `listStyleType` | 列表标记样式 | | `opacity` | 不透明值 | | `textDecorationLine` | 文本装饰行值 | | `textWrap` | 文本包装值 | | `transitionTimingFunction` | 过渡时间函数值 | 请注意: `dimension` 两者均作为标准 `$type` 作为自定义扩展类型. 标准类型用于符合 DTCG 维度格式的值(一个带有 `value` 财务报告和审定财务报表 `unit`) (中文(简体) ). 扩展类型用于响应维度使用 `clamp()` 表达式,这些表达式不是有效的 DTCG 维度. #### 子类型我们为某些类型添加一个子类型,以进一步说明其目的和预览. | 子类型 | 类型 | 说明 | | --- | --- | --- | | `lineHeight` | `number` | 线高乘数 | | `space` | `dimension` | 边距、垫地和缺口 | #### 提示一个 `$extensions.nl.amsterdam.hint` 表示内部使用的特殊处理. ### 具有单一值的指针作为符号键入 `dimension` 必须决心达到一个准确的值,无论两种拼写给出了哪一种. 一个维度读取 `calc()`, (中文(简体) ), `clamp()`, (中文(简体) ), `max()` 或者说 `min()`,或指定给诸如 `padding-inline-start`,这些都不需要两种价值. 第二,申报在计算价值时无效,财产又回落到初始价值而不是象征物上,因此贴花消失而不是有辱人格. 建筑执行这一点: `pnpm build` 失败, 并点出解决一个以上值的每个符号 . 一个被贬值的代币被留下,因为它的价值在等待被移除时不能改变. 如果想要每方一个值,则将符号一分为二并设置长手: ```jsonc "padding-block-start": { "$value": "{ams.space.l}", "$extensions": { "nl.amsterdam.subtype": "space", "nl.amsterdam.type": "dimension" } }, "padding-block-end": { "$value": "0", "$type": "dimension", "$extensions": { "nl.amsterdam.subtype": "space" } } ``` 这个 `ams/require-single-value-token` Stylelint规则在读取符号的样式表中执行相同的约束. ### 说明品牌和普通标志使用 DTCG `$description` 属性,用于在名称单词不够时解释一个符号或组合的目的. 添加一个 `$description` 当一个符号有一个非明显的值(例如. `currentColor`),当类似标志需要区分(例如. `background.body` 对 `background.default`),或当值编码设计原理值得保留时(例如,响应的等效像素等同物) `clamp()` 页:1. ## 在萨斯的使用信使也可以作为 Sass 变量导入. 由于它们已经是前缀, Sass 指定的命名空间是不必要的 . ```sass @use "@amsterdam/design-system-tokens/dist/index.scss" as *; ``` 需要时导入紧凑符号 . 请注意, Sass 不允许与默认设置一起导入它们, 因为命名冲突 . 通过 `compact` 命名空间,不要使用它们取代的宽度符号. ```sass @use "@amsterdam/design-system-tokens/dist/compact.scss"; .class { padding-block: compact.$ams-space-m; } ``` ## JavaScript 用法导入 JSON 文件使用 TypeScript 或 JavaScript 中的符号 . 在这里,符号以前缀开头 `ams.`。。。 . 使用“ 标记” 或方括号访问符号. ```tsx import tokens from "@amsterdam/design-system-tokens/dist/index.json" const buttonBackgroundColor = tokens.ams.color.interactive.default const rowGap = tokens.ams.space.m ``` 需要时导入并合并紧凑符号 . 然后可以在脚本或cs-in-js库中使用符号. ```tsx import compactTokens from "@amsterdam/design-system-tokens/dist/compact.json" import spaciousTokens from "@amsterdam/design-system-tokens/dist/index.json" const tokens = { ...spaciousTokens, ...compactTokens } ``` ## 用法图代币在我们这里使用 [Figma 图书馆](https://www.figma.com/community/file/1530535540611888495/amsterdam-design-system-community-edition) 还有. ## 更新我们遵循语义版本并发布一个 [更改日志](https://github.com/Amsterdam/design-system/blob/main/packages-proprietary/tokens/CHANGELOG.md) 引导您通过更新. 道具是设计系统的公用API. 注意, 检测更改或删除的令牌仍然是一个手工的过程 . ## 支助如果你有问题,找到问题,或者想做贡献,请联系我们. 想办法联系我们 [设计系统.amsterdam](https://designsystem.amsterdam/?path=/docs/docs-introduction--docs#send-a-message)。。。 . ## 常见问题 ### @amsterdam/design-system-tokens 是什么？阿姆斯特丹设计系统的所有设计标志\. 用它将其外观设计应用于您的网站或应用程序\. ### 如何安装 @amsterdam/design-system-tokens？在项目目录运行 npm install @amsterdam/design-system-tokens，或使用 pnpm add / yarn add / bun add。 ### @amsterdam/design-system-tokens 支持 TypeScript 吗？该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/amsterdam\_\_design-system-tokens 是否存在。 ### @amsterdam/design-system-tokens 支持 ESM 还是 CommonJS？以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require 不含顶层 await 的 ES Module，更早的版本需要改用动态 import。 ### @amsterdam/design-system-tokens 可以商用吗？ @amsterdam/design-system-tokens 使用 SEE LICENSE IN LICENSE\.md 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。 ### @amsterdam/design-system-tokens 的下载量有多少？根据 npm 官方下载统计，@amsterdam/design-system-tokens 在 2026/10/06 – 2026/11/04 这 30 天内被下载 12,335 次，日均约 411 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @amsterdam/design-system-tokens 还在维护吗？最新版本 4\.4\.0 发布于 2026/10/22（16 天前）；至今共发布 43 个版本，其中过去 12 个月发布了 12 个；首次发布于 2023/02/10。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。