阿姆斯特丹设计系统:托肯斯

此软件包提供来自 阿姆斯特丹设计系统。 。 。 . 使用它将其外观设计应用到您的网站上. 令牌以多种格式被导出,包括CSS自定义属性和JSON,使其与大多数,甚至全部的技术堆栈相兼容.

说明 这个套件中象征着的价值观 实现了阿姆斯特丹市的品牌化. 如果你的项目不属于阿姆斯特丹市, 你不应该使用这个包. 如果将值更改为自己的品牌,则允许复制符号文件 .

导言

每个设计符号都是代表单一外观设计选择的变量. 对颜色,文字的各个方面,间隔长度,边框宽度,动画的配置等等,都存在托肯斯. 每个令牌的值在CSS中有效. 所有标志一起构成了一个主题,将阿姆斯特丹市的整个品牌编码.

安装

如果您想要或需要直接在样式表中引用符号,则自行安装此软件包.

注意我们 CSS 组件 财务报告和审定财务报表 反应组件 提供更多的功能并自动应用符号. 如果您的应用程序使用React, 或者它允许您应用 HTML 类, 您应该使用这些软件包 .

npm install @amsterdam/design-system-tokens

CSS中的使用量

托肯斯在CSS中通常被用作自定义属性. 他们的名字始于 --ams-。 。 。 .

主样式表

此软件包提供了包含所有符号的主样式表. 它们被宣布为全球CSS变量 :root 选择器.

import "@amsterdam/design-system-tokens/dist/index.css"

如果这对您的项目不起作用, 请使用 index.theme.css 相反,它使用 .ams-theme 选择器. 将此类添加到您的应用程序的根元素中 .

import "@amsterdam/design-system-tokens/dist/index.theme.css"

<body class="ams-theme">
  …
</body>

压缩覆盖

我们的视觉风格相当宽敞. 这对公共网站很有效. 主样式表执行此“ 简单模式” 作为默认 . 内部网站需要高密度布局并减少白色空间和较小文本,可使用紧凑样式表.

请注意, 紧凑样式表不是独立的 – 它只包含覆盖 . 在主样式表之后导入它以获取正确结果 .

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 课.

import "@amsterdam/design-system-tokens/dist/index.theme.css"
import "@amsterdam/design-system-tokens/dist/compact.theme.css"

<body class="ams-theme ams-theme--compact">
  …
</body>

Lo-fi 覆盖

一个Lo-fi样式表可以将进行中的工作作为草图而非完成页来呈现. 它使所有组件都以灰度为单位,用手写相接符来替换文本,给边框一个手绘圆形,并显示交叉的占位符框而不是图像. 版面、尺寸和间隔保持不变,因此页保持其现实结构.

此样式表仅包含覆盖 . 在主样式表后导入它, 连同我们资产包中的 Redacted 脚本字体 .

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 课.

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"

<body class="ams-theme ams-theme--lo-fi">
  …
</body>

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 并在根元素上宣告,在根元素中它决定宽大的字体大小. 文档中一个更深的段落继承了已解决的值,因此更下方的打字符太迟了.

因此,不支持对页面的一部分应用一个模式:我们的组件不会遵循它.

三层

道具分为三层:品牌,通用和组件.

品牌标志

这些表现了阿姆斯特丹市的企业身份. 它们是我们从所有可能的颜色,文本特征,间隔长度,边框宽度等基本选择. 他们的名字从我们的前缀开始,然后是诸如 " 颜色 " 、 " 文字 " 或 " 空间 " 等设计类别.

实例:

:root {
  --ams-color-feedback-error: #ec0000;
  --ams-space-m: 1rem;
  --ams-aspect-ratio-4-3: 4 / 3;
  --ams-border-width-l: 0.1875rem;
}

寻找 品牌标志列表 (原始内容存档于2018-09-29). on GitHub.

删除 " 默认 " 密钥

一些品牌标志包括JSON中的"默认"密钥,以允许额外的变体,例如: ams.color.interactive.default 财务报告和审定财务报表 ams.color.interactive.disabled 然而,对于平坦变量的集合,像我们的CSS自定义属性一样,不需要这个键. 因此,我们在未记名变量中去掉这个键. 比如说, --ams-color-interactive 财务报告和审定财务报表 --ams-color-interactive-disabled。 。 。 .

常见符号

相關元件都具有外观设计特征. 例如,所有链接都有相同的颜色,而不同形式输入的边框同样厚. 共同的标志表达了这些关系并简化了未来的变化. 他们的名字从我们的前缀开始,然后是使用他们的团体的名称. 这个组名是复数来表示几个组件应用了这些符号.

设计系统组件尽可能使用共同的符号. 应用程序中可以创建的自定义组件也是如此.

<a class="my-link" href="#">…</a>

.my-input {
  color: var(--ams-links-color);
  text-underline-offset: var(--ams-links-text-underline-offset);
}

寻找 常见符号列表 (原始内容存档于2018-09-29). on GitHub.

组件符号

每个设计系统组件都为每一个表达出品牌的地产定义了符号,并在其样式表中使用.

在重新创建现有组件时使用这些符号来接收当前和未来的正确值. 不要将这些符号应用到其他组件 – 组件必须是独立的.

一个组件符号的名称以使用它的CSS属性结尾,例如. -font-size。 。 。 . 我们跟着 nL 设计系统符号命名准则 在这里.

<button class="my-button" type="button">Button label</button>

.my-button {
  font-family: var(--ams-button-font-family);
  background-color: var(--ams-button-primary-background-color);
}

寻找 组件符号列表 (原始内容存档于2018-09-29). on GitHub.

逻辑视图端口内置大小符

一些组件符号因取景口断点而异并跟随 CSS 逻辑属性 名称 :

• 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 设计系统 我们是其中的一部分.

然而,阿姆斯特丹市的网站必须尽可能紧跟设计系统. 我们重复一遍:阿姆斯特丹市的网站必须尽可能紧跟设计系统.

与此同时,我们意识到,采用设计系统在实践中可能构成挑战. 如果有很好的理由(暂时)调整一个组件,则通过在单独的样式表上压倒其相应符号的值来这样做. 注意重新定义一个符号的值是一种比重新声明样式,添加类名甚至入行样式更好的方法.

折耗令牌

被贬损的代币一直工作到被移除为止,所以它必须始终具有真正的价值.

我们通过DTCG提供理由和迁移途径 $deprecated 字段. 当有直接替换时,以 Use `<replacement-token>` instead. 以删除日期结束每封信件 : Will be removed on or after YYYY-MM-DD.

重新命名一个符号

在贬值窗口中保持旧名完好无损,同时为同值添加新名. 通过 a 连接重命名 var() 后退,所以下游 覆盖旧名继续工作.

1. 标出已贬值的令牌 $value 在替换时,它决定了相同的值:

"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中,首先引用已贬值的代号,以替换为倒置: 在组件样式表中也标出折旧; 不需要从符号文件中复制细节 .

padding-inline: var(--ams-grid-medium-padding-inline /* @deprecated */, var(--ams-grid-vi-medium-padding-inline));

3. 如果一个主题超过替换(例如 Contracting Mode), 超过替换符号就足够了, 因为已贬值的符号引用它 . 只有在主题符号文件中重现已贬值的符号时,才能为遗留的消费者重覆已贬值的符号本身.

删除一个符号

移除将永远是突破性的改变,因此它必须是重大释放的一部分. 尽早计划贬值,因为它必须至少停留六个月. 由于我们认为下游用户的视觉后果是突破性的改变,因此在贬值窗口中,信使的值不能改变.

"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)"
}

在样式表上也显示去向.

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 标准类型

以下类型来自 设计托肯斯社区小组规格数字 :

自定义扩展名

类型

我们在下面添加自定义类型 $extensions.nl.amsterdam.type 用于:

1. 指向另一个符号的符号
2. dTCG 规格未覆盖的属性
3. 不符合标准类型的值

我们使用这些类型来帮助决定在每个组件的文档页面 Design Tokens 表中提供哪个预览 .

请注意: dimension 两者均作为标准 $type 作为自定义扩展类型. 标准类型用于符合 DTCG 维度格式的值(一个带有 value 财务报告和审定财务报表 unit) (中文(简体) ). 扩展类型用于响应维度使用 clamp() 表达式,这些表达式不是有效的 DTCG 维度.

子类型

我们为某些类型添加一个子类型,以进一步说明其目的和预览.

提示

一个 $extensions.nl.amsterdam.hint 表示内部使用的特殊处理.

具有单一值的指针

作为符号键入 dimension 必须决心达到一个准确的值,无论两种拼写给出了哪一种.

一个维度读取 calc(), (中文(简体) ), clamp(), (中文(简体) ), max() 或者说 min(),或指定给诸如 padding-inline-start,这些都不需要两种价值. 第二,申报在计算价值时无效,财产又回落到初始价值而不是象征物上,因此贴花消失而不是有辱人格.

建筑执行这一点: pnpm build 失败, 并点出解决一个以上值的每个符号 . 一个被贬值的代币被留下,因为它的价值在等待被移除时不能改变.

如果想要每方一个值,则将符号一分为二并设置长手:

"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 指定的命名空间是不必要的 .

@use "@amsterdam/design-system-tokens/dist/index.scss" as *;

需要时导入紧凑符号 . 请注意, Sass 不允许与默认设置一起导入它们, 因为命名冲突 . 通过 compact 命名空间,不要使用它们取代的宽度符号.

@use "@amsterdam/design-system-tokens/dist/compact.scss";

.class {
  padding-block: compact.$ams-space-m;
}

JavaScript 用法

导入 JSON 文件使用 TypeScript 或 JavaScript 中的符号 . 在这里,符号以前缀开头 ams.。 。 。 . 使用“ 标记” 或方括号访问符号.

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库中使用符号.

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 图书馆 还有.

更新

我们遵循语义 版本并发布一个 更改日志 引导您通过更新. 道具是设计系统的公用API. 注意, 检测更改或删除的令牌仍然是一个手工的过程 .

支助

如果你有问题,找到问题,或者想做贡献,请联系我们. 想办法联系我们 设计系统.amsterdam。 。 。 .