@amsterdam/design-system-tokens 3.4.0 → 4.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +71 -0
- package/CHANGELOG.md +57 -3
- package/CONTRIBUTING.md +18 -0
- package/README.md +131 -22
- package/build.js +11 -1
- package/dist/compact.css +10 -3
- package/dist/compact.d.ts +23 -6
- package/dist/compact.json +34 -17
- package/dist/compact.mjs +23 -13
- package/dist/compact.scss +10 -3
- package/dist/compact.theme.css +10 -3
- package/dist/index.css +108 -110
- package/dist/index.d.ts +112 -110
- package/dist/index.json +218 -216
- package/dist/index.mjs +218 -208
- package/dist/index.scss +108 -110
- package/dist/index.theme.css +108 -110
- package/package.json +2 -2
- package/src/brand/ams/aspect-ratio.tokens.json +24 -6
- package/src/brand/ams/border.tokens.json +5 -0
- package/src/brand/ams/color.compact.tokens.json +15 -0
- package/src/brand/ams/color.tokens.json +37 -54
- package/src/brand/ams/cursor.tokens.json +9 -2
- package/src/brand/ams/focus.tokens.json +1 -0
- package/src/brand/ams/space.compact.tokens.json +16 -4
- package/src/brand/ams/space.tokens.json +31 -6
- package/src/brand/ams/typography.compact.tokens.json +36 -45
- package/src/brand/ams/typography.tokens.json +59 -63
- package/src/common/ams/inputs.tokens.json +41 -19
- package/src/common/ams/links.tokens.json +35 -10
- package/src/components/ams/accordion.tokens.json +17 -48
- package/src/components/ams/action-group.tokens.json +2 -2
- package/src/components/ams/alert.tokens.json +38 -20
- package/src/components/ams/avatar.tokens.json +79 -29
- package/src/components/ams/badge.tokens.json +60 -23
- package/src/components/ams/blockquote.tokens.json +14 -5
- package/src/components/ams/body.compact.tokens.json +12 -0
- package/src/components/ams/body.tokens.json +12 -0
- package/src/components/ams/breadcrumb.tokens.json +36 -15
- package/src/components/ams/button.tokens.json +74 -33
- package/src/components/ams/call-to-action-link.tokens.json +29 -16
- package/src/components/ams/card.tokens.json +30 -17
- package/src/components/ams/character-count.tokens.json +14 -5
- package/src/components/ams/checkbox.tokens.json +101 -74
- package/src/components/ams/column.tokens.json +10 -10
- package/src/components/ams/date-input.tokens.json +55 -50
- package/src/components/ams/description-list.tokens.json +85 -24
- package/src/components/ams/dialog.tokens.json +104 -28
- package/src/components/ams/error-message.tokens.json +13 -6
- package/src/components/ams/field-set.tokens.json +35 -20
- package/src/components/ams/field.tokens.json +13 -10
- package/src/components/ams/figure.tokens.json +16 -7
- package/src/components/ams/file-input.tokens.json +69 -31
- package/src/components/ams/file-list.tokens.json +20 -11
- package/src/components/ams/grid.compact.tokens.json +43 -3
- package/src/components/ams/grid.tokens.json +77 -24
- package/src/components/ams/heading.tokens.json +38 -36
- package/src/components/ams/hint.tokens.json +6 -2
- package/src/components/ams/icon-button.tokens.json +46 -16
- package/src/components/ams/icon.tokens.json +19 -39
- package/src/components/ams/image-slider.tokens.json +28 -16
- package/src/components/ams/image.tokens.json +4 -1
- package/src/components/ams/invalid-form-alert.tokens.json +2 -2
- package/src/components/ams/label.tokens.json +18 -6
- package/src/components/ams/link-list.tokens.json +50 -22
- package/src/components/ams/link.tokens.json +38 -25
- package/src/components/ams/logo.tokens.json +6 -2
- package/src/components/ams/mark.tokens.json +3 -1
- package/src/components/ams/menu.tokens.json +80 -55
- package/src/components/ams/ordered-list.tokens.json +39 -25
- package/src/components/ams/page-footer.tokens.json +70 -26
- package/src/components/ams/page-header.compact.tokens.json +2 -1
- package/src/components/ams/page-header.tokens.json +128 -59
- package/src/components/ams/page.compact.tokens.json +12 -0
- package/src/components/ams/page.tokens.json +5 -3
- package/src/components/ams/pagination.tokens.json +37 -17
- package/src/components/ams/paragraph.tokens.json +22 -8
- package/src/components/ams/password-input.tokens.json +47 -21
- package/src/components/ams/progress-list.tokens.json +152 -61
- package/src/components/ams/radio.tokens.json +97 -36
- package/src/components/ams/row.tokens.json +10 -10
- package/src/components/ams/search-field.tokens.json +57 -24
- package/src/components/ams/select.tokens.json +63 -25
- package/src/components/ams/skip-link.tokens.json +23 -12
- package/src/components/ams/spotlight.tokens.json +21 -7
- package/src/components/ams/standalone-link.tokens.json +42 -46
- package/src/components/ams/switch.tokens.json +23 -9
- package/src/components/ams/tab-navigation.tokens.json +205 -0
- package/src/components/ams/table-of-contents.tokens.json +38 -41
- package/src/components/ams/table.tokens.json +29 -10
- package/src/components/ams/tabs.tokens.json +36 -17
- package/src/components/ams/text-area.tokens.json +49 -23
- package/src/components/ams/text-input.tokens.json +47 -21
- package/src/components/ams/time-input.tokens.json +55 -50
- package/src/components/ams/unordered-list.tokens.json +37 -25
- package/style-dictionary/transforms/dtcg-font-family.js +32 -0
- package/src/components/ams/page-heading.tokens.json +0 -46
package/AGENTS.md
ADDED
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
<!-- @license CC0-1.0 -->
|
|
2
|
+
|
|
3
|
+
# Tokens Package — Agent Instructions
|
|
4
|
+
|
|
5
|
+
These instructions are additive to the root [AGENTS.md](../../AGENTS.md). Read that first.
|
|
6
|
+
|
|
7
|
+
See [README.md](README.md) for full token usage and design guidance; this file focuses on agent-specific rules for editing token source files.
|
|
8
|
+
|
|
9
|
+
## Overview
|
|
10
|
+
|
|
11
|
+
This package defines design tokens using the [Design Tokens Community Group (DTCG)](https://tr.designtokens.org/format/) format and builds them into CSS custom properties, JSON, and Sass variables via [Style Dictionary](https://styledictionary.com/).
|
|
12
|
+
|
|
13
|
+
## Token structure
|
|
14
|
+
|
|
15
|
+
Tokens are organized into three layers:
|
|
16
|
+
|
|
17
|
+
| Directory | Purpose |
|
|
18
|
+
| ------------------ | ------------------------------------------------- |
|
|
19
|
+
| `src/brand/ams/` | Brand-level values (colors, typography, spacing) |
|
|
20
|
+
| `src/common/ams/` | Shared patterns across components (inputs, links) |
|
|
21
|
+
| `src/components/ams/` | Component-specific tokens |
|
|
22
|
+
|
|
23
|
+
## Token file format
|
|
24
|
+
|
|
25
|
+
Token files use the `.tokens.json` extension and follow the DTCG format:
|
|
26
|
+
|
|
27
|
+
```json
|
|
28
|
+
{
|
|
29
|
+
"ams": {
|
|
30
|
+
"<component-name>": {
|
|
31
|
+
"<property>": {
|
|
32
|
+
"$value": "{ams.<reference>}",
|
|
33
|
+
"$type": "<dtcg-type>"
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
- Always reference existing brand or common tokens where possible — do not hardcode raw values.
|
|
41
|
+
- Valid `$type` values used in this project: `color`, `dimension`, `fontFamily`, `fontWeight`, `shadow`. Do not invent other `$type` values.
|
|
42
|
+
- Use the `$extensions` field for Amsterdam-specific metadata (e.g. `nl.amsterdam.type`, `nl.amsterdam.subtype`). Common `$extensions` types include `fontSize`, `lineHeight`, and `space` (via `nl.amsterdam.subtype`). See existing component tokens for examples.
|
|
43
|
+
- Variant tokens are nested under the component (e.g. `ams.badge.azure.background-color`).
|
|
44
|
+
|
|
45
|
+
## Compact mode
|
|
46
|
+
|
|
47
|
+
Some token categories have `.compact.tokens.json` variants (e.g. `space.compact.tokens.json`, `typography.compact.tokens.json`). These provide denser values for compact layouts.
|
|
48
|
+
|
|
49
|
+
## Build
|
|
50
|
+
|
|
51
|
+
- Build command: `pnpm build` (runs `node build.js`)
|
|
52
|
+
- Watch mode: `pnpm build:watch`
|
|
53
|
+
- Output: `dist/` — never edit generated output directly.
|
|
54
|
+
- Build config: `build.js` with custom Style Dictionary logic in `style-dictionary/` (includes `transforms/` and `dimensionToString.js`).
|
|
55
|
+
|
|
56
|
+
## File locations
|
|
57
|
+
|
|
58
|
+
- Component tokens: `src/components/ams/<name>.tokens.json`
|
|
59
|
+
- Brand tokens: `src/brand/ams/`
|
|
60
|
+
- Common tokens: `src/common/ams/`
|
|
61
|
+
- Build script: `build.js`
|
|
62
|
+
- Custom transforms: `style-dictionary/transforms/`
|
|
63
|
+
|
|
64
|
+
## Key rules
|
|
65
|
+
|
|
66
|
+
- Every token must have a `$value`. Type information is provided through either `$type` (DTCG standard) or `$extensions` with `nl.amsterdam.type` / `nl.amsterdam.subtype`. Some tokens (e.g. cursors, aspect ratios) have no type annotation — follow the existing pattern for the token category you are editing.
|
|
67
|
+
- Token names use kebab-case and mirror CSS property names where applicable.
|
|
68
|
+
- No unused tokens — every defined token must be consumed by CSS or another token.
|
|
69
|
+
- No hardcoded design values in CSS or React — if a value is missing, add a token here first.
|
|
70
|
+
- Changes to brand-level tokens in `src/brand/ams/` have wide impact; do not change them unless the task explicitly calls for brand updates.
|
|
71
|
+
- When adding new component tokens, wire them into CSS (and React where applicable) in the same change so they are immediately used.
|
package/CHANGELOG.md
CHANGED
|
@@ -3,6 +3,60 @@
|
|
|
3
3
|
All notable changes to this project will be documented in this file.
|
|
4
4
|
See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
|
|
5
5
|
|
|
6
|
+
## [4.0.1](https://github.com/Amsterdam/design-system/compare/design-system-tokens-v4.0.0...design-system-tokens-v4.0.1) (2026-04-24)
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
### Bug Fixes
|
|
10
|
+
|
|
11
|
+
* **Grid:** Set correct horizontal padding in Compact Mode ([#2582](https://github.com/Amsterdam/design-system/issues/2582)) ([049fa6c](https://github.com/Amsterdam/design-system/commit/049fa6c205e2a73f3a4eac66642e000e90aa8369))
|
|
12
|
+
|
|
13
|
+
## [4.0.0](https://github.com/Amsterdam/design-system/compare/design-system-tokens-v3.4.0...design-system-tokens-v4.0.0) (2026-04-20)
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
### ⚠ BREAKING CHANGES
|
|
17
|
+
|
|
18
|
+
* Remove deprecated tokens, classes and components for v4.0.0 ([#2549](https://github.com/Amsterdam/design-system/issues/2549))
|
|
19
|
+
* **Grid, Page:** Make Page grey and Grid Cell white in Compact Mode ([#2398](https://github.com/Amsterdam/design-system/issues/2398))
|
|
20
|
+
|
|
21
|
+
### Features
|
|
22
|
+
|
|
23
|
+
* **Grid, Page:** Make Page grey and Grid Cell white in Compact Mode ([#2398](https://github.com/Amsterdam/design-system/issues/2398)) ([6b5bb5b](https://github.com/Amsterdam/design-system/commit/6b5bb5b2f7c273d35e25e18e29cfa6557d20c38f))
|
|
24
|
+
* Introduce Tab Navigation component ([#2552](https://github.com/Amsterdam/design-system/issues/2552)) ([1d6e0a3](https://github.com/Amsterdam/design-system/commit/1d6e0a32e856775e6d42879c71902d0aa5ddace8))
|
|
25
|
+
* **Table:** Add whitespace below Caption ([#2515](https://github.com/Amsterdam/design-system/issues/2515)) ([092c0ff](https://github.com/Amsterdam/design-system/commit/092c0fff4ebfd9e395caee721cb55732e57d7cc5))
|
|
26
|
+
* **tokens:** Introduce `vi-` prefix for viewport-dependent component tokens ([#2502](https://github.com/Amsterdam/design-system/issues/2502)) ([90c19da](https://github.com/Amsterdam/design-system/commit/90c19da8f309eedb926bbd3f65f52990b880b661))
|
|
27
|
+
|
|
28
|
+
### Deprecations
|
|
29
|
+
|
|
30
|
+
The following deprecated tokens have been removed:
|
|
31
|
+
|
|
32
|
+
- `ams.accordion.button.font-family`, `ams.accordion.button.font-size`, `ams.accordion.button.font-weight`, `ams.accordion.button.line-height`, `ams.accordion.button.text-wrap`, `ams.accordion.panel.padding-block`, and `ams.accordion.panel.padding-inline`.
|
|
33
|
+
- `ams.checkbox.hover.text-decoration-thickness`, `ams.checkbox.rectangle.checked.disabled.hover.*`, `ams.checkbox.rectangle.checked.hover.disabled-invalid.*`, `ams.checkbox.rectangle.hover.disabled-invalid.*`, `ams.checkbox.rectangle.indeterminate.disabled.hover.*`, and `ams.checkbox.rectangle.indeterminate.hover.disabled-invalid.*`.
|
|
34
|
+
- `ams.color.link.secondary`.
|
|
35
|
+
- `ams.date-input.calender-picker-indicator.*`, `ams.date-input.disabled.calender-picker-indicator.*`, and `ams.date-input.hover.calender-picker-indicator.*`.
|
|
36
|
+
- `ams.heading.6.*`.
|
|
37
|
+
- `ams.icon.heading-0.*` and `ams.icon.heading-6.*`.
|
|
38
|
+
- `ams.menu.link.contrast.*` and `ams.menu.link.inverse.*`.
|
|
39
|
+
- `ams.page-heading.*`.
|
|
40
|
+
- `ams.standalone-link.hover.text-decoration-thickness`, `ams.standalone-link.hover.text-underline-offset`, and `ams.standalone-link.with-icon.*`.
|
|
41
|
+
- `ams.table-of-contents.heading.*`.
|
|
42
|
+
- `ams.time-input.calender-picker-indicator.*`, `ams.time-input.disabled.calender-picker-indicator.*`, and `ams.time-input.hover.calender-picker-indicator.*`.
|
|
43
|
+
- `ams.typography.heading.0.*` and `ams.typography.heading.6.*`.
|
|
44
|
+
|
|
45
|
+
The following tokens have been deprecated and will be removed on or after 2026-10-20:
|
|
46
|
+
|
|
47
|
+
- `ams.description-list.column-gap`, `ams.description-list.row-gap`, `ams.description-list.narrow.grid-template-columns`,
|
|
48
|
+
`ams.description-list.medium.grid-template-columns`, and `ams.description-list.wide.grid-template-columns`
|
|
49
|
+
- `ams.dialog.medium.inline-size`, `ams.dialog.medium.max-block-size`,
|
|
50
|
+
`ams.dialog.header.medium.padding-block`, `ams.dialog.header.medium.padding-inline`, `ams.dialog.body.medium.padding-inline`,
|
|
51
|
+
`ams.dialog.footer.medium.padding-block`, `ams.dialog.footer.medium.padding-inline`
|
|
52
|
+
- `ams.grid.medium.column-count`, `ams.grid.medium.padding-inline`, `ams.grid.wide.column-count`, and `ams.grid.wide.padding-inline`
|
|
53
|
+
- `ams.menu.wide.max-inline-size`, `ams.menu.wide.padding-block`, `ams.menu.wide.padding-inline`, and `ams.menu-link.wide.gap`
|
|
54
|
+
- `ams.page-footer.menu.medium.padding-inline`, `ams.page-footer.menu.wide.padding-inline`
|
|
55
|
+
- `ams.page-header.medium.padding-inline`, `ams.page-header.wide.padding-inline`
|
|
56
|
+
- `ams.progress-list.step.medium.gap` and `ams.progress-list.substeps.step.indicator.medium.margin-inline-end`
|
|
57
|
+
|
|
58
|
+
For tokens containing `*.medium.*` and `*.wide.*`, replace them with `*.vi-medium.*` and `*.vi-wide.*`.
|
|
59
|
+
|
|
6
60
|
## [3.4.0](https://github.com/Amsterdam/design-system/compare/design-system-tokens-v3.3.0...design-system-tokens-v3.4.0) (2026-04-03)
|
|
7
61
|
|
|
8
62
|
|
|
@@ -50,7 +104,7 @@ See [Conventional Commits](https://conventionalcommits.org) for commit guideline
|
|
|
50
104
|
|
|
51
105
|
### Deprecations
|
|
52
106
|
|
|
53
|
-
The following tokens will be removed
|
|
107
|
+
The following tokens will be removed on or after 2026-07-09:
|
|
54
108
|
|
|
55
109
|
- `ams.field-set.legend.margin-block-end`
|
|
56
110
|
- `ams.field.gap`
|
|
@@ -77,7 +131,7 @@ The following tokens will be removed in release 5.0.0:
|
|
|
77
131
|
|
|
78
132
|
### Deprecations
|
|
79
133
|
|
|
80
|
-
The following tokens
|
|
134
|
+
The following tokens have been removed in release 4.0.0.
|
|
81
135
|
|
|
82
136
|
- `ams.menu.link.contrast.color`, `ams.menu.link.contrast.hover.color`, `ams.menu.link.inverse.color`, `ams.menu.link.inverse.hover.color`.
|
|
83
137
|
- `ams.date-input.disabled.calender-picker-indicator.background-image`, `ams.date-input.hover.calender-picker-indicator.background-image`, `ams.date-input.calender-picker-indicator.background-image`, `ams.date-input.calender-picker-indicator.cursor`.
|
|
@@ -101,7 +155,7 @@ The following tokens will be removed in release 4.0.0. If you use them in your c
|
|
|
101
155
|
|
|
102
156
|
### Deprecations
|
|
103
157
|
|
|
104
|
-
The following tokens
|
|
158
|
+
The following tokens have been removed in release 4.0.0.
|
|
105
159
|
|
|
106
160
|
* `ams.accordion.panel.*` and some tokens in `ams.accordion.button`
|
|
107
161
|
* `ams.checkbox.hover.text-decoration-thickness` and `ams.checkbox.rectangle.*`
|
package/CONTRIBUTING.md
ADDED
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
<!-- @license CC0-1.0 -->
|
|
2
|
+
|
|
3
|
+
# Contributing to the tokens package
|
|
4
|
+
|
|
5
|
+
See the [repository-wide contributing guidelines](../../CONTRIBUTING.md) for general instructions.
|
|
6
|
+
The notes below apply specifically to design tokens.
|
|
7
|
+
|
|
8
|
+
## Compact Mode and responsive overrides
|
|
9
|
+
|
|
10
|
+
Components may expose separate tokens for responsive variants, such as `vi-medium` and `vi-wide` for the Grid.
|
|
11
|
+
These are applied at breakpoints in the component stylesheet and override the base token.
|
|
12
|
+
|
|
13
|
+
When you add or change a token in a `*.compact.tokens.json` file, check whether the component stylesheet also applies a responsive variant of that token at larger breakpoints.
|
|
14
|
+
If it does, override every responsive variant in the compact file as well.
|
|
15
|
+
Otherwise, the compact value only applies below the first breakpoint, and the component silently reverts to the default token at larger viewports.
|
|
16
|
+
|
|
17
|
+
For example, the Grid mixin sets `padding-inline` from `--ams-grid-padding-inline`, then overrides it with `--ams-grid-vi-medium-padding-inline` and `--ams-grid-vi-wide-padding-inline` at the medium and wide breakpoints.
|
|
18
|
+
Compact Mode must override all three, not just the base.
|
package/README.md
CHANGED
|
@@ -150,6 +150,18 @@ We follow [the NL Design System token naming guidelines](https://nldesignsystem.
|
|
|
150
150
|
|
|
151
151
|
Find the [list of component tokens](https://github.com/Amsterdam/design-system/tree/main/packages-proprietary/tokens/src/component/ams) on GitHub.
|
|
152
152
|
|
|
153
|
+
#### Logical viewport inline size tokens
|
|
154
|
+
|
|
155
|
+
Some component tokens vary by viewport breakpoint and follow [CSS logical properties](https://developer.mozilla.org/en-US/docs/Glossary/Logical_properties) naming:
|
|
156
|
+
|
|
157
|
+
- `vi` means _viewport inline size_.
|
|
158
|
+
- Breakpoint-specific variants use `vi-medium` and `vi-wide`, for example:
|
|
159
|
+
- `ams.menu.vi-wide.padding-inline`
|
|
160
|
+
- `ams.dialog.vi-medium.inline-size`
|
|
161
|
+
- `ams.grid.vi-medium.column-count`
|
|
162
|
+
|
|
163
|
+
Components can also use `narrow`, `medium` or `wide` keys without the `vi` prefix when the dimension is intrinsic to the component and not tied to the active viewport breakpoint.
|
|
164
|
+
|
|
153
165
|
### Overriding tokens
|
|
154
166
|
|
|
155
167
|
This package allows the creation of a theme to reuse our components for a different brand.
|
|
@@ -162,50 +174,147 @@ At the same time, we are aware that adopting a design system can pose challenges
|
|
|
162
174
|
If there is a good reason to (temporarily) adapt a component, do so by overriding the values of its appropriate tokens in a separate stylesheet.
|
|
163
175
|
Note that redefining the value of a token is a much better approach than redeclaring styles, adding class names or even inline styles.
|
|
164
176
|
|
|
177
|
+
## Deprecating tokens
|
|
178
|
+
|
|
179
|
+
We deprecate tokens using the DTCG `$deprecated` field. The [official definition](https://www.designtokens.org/tr/drafts/format/#deprecated) allows `$deprecated` to be `true`, `false` or a string explanation.
|
|
180
|
+
|
|
181
|
+
In ADS, `$deprecated` should be a string so consumers always get a reason + migration path.
|
|
182
|
+
|
|
183
|
+
### Deprecation message format
|
|
184
|
+
|
|
185
|
+
- Always include a removal date: `Will be removed on or after YYYY-MM-DD.`
|
|
186
|
+
- If there is a direct replacement, start with: ``Use `<replacement-token>` instead.``
|
|
187
|
+
|
|
188
|
+
### Simple deprecation (no fallback)
|
|
189
|
+
|
|
190
|
+
If a deprecated token is still used directly, keep its existing `$value` until removal.
|
|
191
|
+
Also add a deprecation comment next to the token usage in the consuming CSS.
|
|
192
|
+
|
|
193
|
+
Token JSON:
|
|
194
|
+
|
|
195
|
+
```jsonc
|
|
196
|
+
"row-gap": {
|
|
197
|
+
"$deprecated": "Whitespace is now applied through the `ams.description-list.*.margin-block-end` tokens. Will be removed on or after 2026-10-20.",
|
|
198
|
+
"$value": "0"
|
|
199
|
+
}
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
Component CSS:
|
|
203
|
+
|
|
204
|
+
```css
|
|
205
|
+
row-gap: var(--ams-description-list-row-gap); /* This token is @deprecated. Will be removed on or after 2026-10-20. */
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
### Renames that use `var()` fallback
|
|
209
|
+
|
|
210
|
+
When a token is renamed but we still want (downstream) overrides of the old token to keep working, we implement the rename through CSS `var()` fallback.
|
|
211
|
+
|
|
212
|
+
Always add an inline deprecation comment next to the deprecated custom property inside the `var()` call.
|
|
213
|
+
|
|
214
|
+
1. Update the component CSS to reference the deprecated token first, and the replacement token as the fallback:
|
|
215
|
+
|
|
216
|
+
```css
|
|
217
|
+
padding-inline: var(
|
|
218
|
+
--ams-grid-medium-padding-inline /* This token is @deprecated. Will be removed on or after 2026-10-20. */,
|
|
219
|
+
var(--ams-grid-vi-medium-padding-inline)
|
|
220
|
+
);
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
2. In the token JSON, mark the old token as deprecated and set its `$value` to the CSS-wide keyword `initial`:
|
|
224
|
+
|
|
225
|
+
```jsonc
|
|
226
|
+
"medium": {
|
|
227
|
+
"padding-inline": {
|
|
228
|
+
"$deprecated": "Use `ams.grid.vi-medium.padding-inline` instead. Will be removed on or after 2026-10-20.",
|
|
229
|
+
"$value": "initial"
|
|
230
|
+
}
|
|
231
|
+
}
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
Why `initial`? Per CSS `var()` rules, when a custom property is [not set or is set to a CSS-wide keyword](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/var#syntax) like `initial`, the fallback value is used. This makes the replacement token the default while keeping the deprecated token visible and overrideable.
|
|
235
|
+
|
|
236
|
+
Only apply this `initial` rule when the deprecated token is used in a `var(--deprecated, <fallback>)` pattern.
|
|
237
|
+
|
|
238
|
+
### Deprecations without a 1:1 replacement
|
|
239
|
+
|
|
240
|
+
If there is no 1:1 replacement (design/behavior changed), keep the existing `$value` until removal and update the consuming CSS/markup before deleting the token.
|
|
241
|
+
|
|
165
242
|
## Token types
|
|
166
243
|
|
|
167
|
-
Tokens
|
|
168
|
-
|
|
169
|
-
|
|
244
|
+
Tokens may define their type using a DTCG `$type`, or, when no standard DTCG type applies, using our Amsterdam-specific `$extensions.nl.amsterdam.type`.
|
|
245
|
+
References inherit the type of the token they refer to.
|
|
246
|
+
|
|
247
|
+
We also use group-level inheritance where all tokens in a group share the same DTCG type.
|
|
248
|
+
A `$type` set on a group applies to all its descendants, so individual tokens do not need to repeat it.
|
|
170
249
|
|
|
171
250
|
### DTCG standard types
|
|
172
251
|
|
|
173
252
|
The following types come from the [Design Tokens Community Group (DTCG) specification](https://www.designtokens.org/tr/2025.10/format/):
|
|
174
253
|
|
|
175
|
-
| Type | Description
|
|
176
|
-
| ------------ |
|
|
177
|
-
| `color` | Any colour value
|
|
178
|
-
| `dimension` | Any dimension with a unit
|
|
179
|
-
| `
|
|
180
|
-
| `
|
|
254
|
+
| Type | Description |
|
|
255
|
+
| ------------ | -------------------------------------- |
|
|
256
|
+
| `color` | Any colour value |
|
|
257
|
+
| `dimension` | Any dimension with a unit |
|
|
258
|
+
| `duration` | A length of time |
|
|
259
|
+
| `fontFamily` | Font family definitions (string array) |
|
|
260
|
+
| `fontWeight` | Font weight values |
|
|
261
|
+
| `number` | Unitless numeric values |
|
|
262
|
+
| `shadow` | Box shadow definitions |
|
|
181
263
|
|
|
182
264
|
### Custom extensions
|
|
183
265
|
|
|
184
266
|
#### Type
|
|
185
267
|
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
268
|
+
We add a custom type under `$extensions.nl.amsterdam.type` for:
|
|
269
|
+
|
|
270
|
+
1. tokens that refer to another token
|
|
271
|
+
2. properties that the DTCG specification does not cover
|
|
272
|
+
3. values that do not conform to a standard type
|
|
273
|
+
|
|
274
|
+
We use these types to help decide which preview to render in the Design Tokens Table on each component’s documentation page.
|
|
275
|
+
|
|
276
|
+
| Type | Description |
|
|
277
|
+
| -------------------------- | ----------------------------------- |
|
|
278
|
+
| `aspectRatio` | Aspect ratio values |
|
|
279
|
+
| `backgroundImage` | Background image values (e.g. SVGs) |
|
|
280
|
+
| `backgroundPosition` | Background position values |
|
|
281
|
+
| `border` | Border shorthand values |
|
|
282
|
+
| `borderRadius` | Border radius values |
|
|
283
|
+
| `borderStyle` | Border style values |
|
|
284
|
+
| `borderWidth` | Border thickness values |
|
|
285
|
+
| `cursor` | Cursor values |
|
|
286
|
+
| `dimension` | Responsive dimensions |
|
|
287
|
+
| `fontSize` | Font size values |
|
|
288
|
+
| `gridTemplateColumns` | Grid track definitions |
|
|
289
|
+
| `hyphenateLimitChars` | Hyphenation limit values |
|
|
290
|
+
| `listStyleType` | List marker styles |
|
|
291
|
+
| `opacity` | Opacity values |
|
|
292
|
+
| `textDecorationLine` | Text decoration line values |
|
|
293
|
+
| `textWrap` | Text wrapping values |
|
|
294
|
+
| `transitionTimingFunction` | Transition timing function values |
|
|
295
|
+
|
|
296
|
+
Note that `dimension` appears both as a standard `$type` and as a custom extension type.
|
|
297
|
+
The standard type is for values that conform to the DTCG dimension format (an object with a `value` and `unit`).
|
|
298
|
+
The extension type is for responsive dimensions that use `clamp()` expressions, which are not valid DTCG dimensions.
|
|
196
299
|
|
|
197
300
|
#### Subtype
|
|
198
301
|
|
|
199
302
|
We add a subtype for certain types to further specify their purpose and preview.
|
|
200
303
|
|
|
201
|
-
| Subtype
|
|
202
|
-
|
|
|
203
|
-
| `
|
|
304
|
+
| Subtype | For type | Description |
|
|
305
|
+
| ------------ | ----------- | -------------------------- |
|
|
306
|
+
| `lineHeight` | `number` | Line height multipliers |
|
|
307
|
+
| `space` | `dimension` | Margins, paddings and gaps |
|
|
204
308
|
|
|
205
309
|
#### Hint
|
|
206
310
|
|
|
207
311
|
An `$extensions.nl.amsterdam.hint` indicates special handling for internal use.
|
|
208
312
|
|
|
313
|
+
### Descriptions
|
|
314
|
+
|
|
315
|
+
Brand and common tokens use the DTCG `$description` property to explain the purpose of a token or group when the name alone is not sufficient.
|
|
316
|
+
Add a `$description` when a token has a non-obvious value (e.g. `currentColor`), when similar tokens need to be distinguished (e.g. `background.body` vs `background.default`), or when the value encodes design rationale worth preserving (e.g. pixel equivalents for responsive `clamp()` values).
|
|
317
|
+
|
|
209
318
|
## Usage in Sass
|
|
210
319
|
|
|
211
320
|
The tokens can be imported as Sass variables as well.
|
package/build.js
CHANGED
|
@@ -6,16 +6,23 @@
|
|
|
6
6
|
import StyleDictionary from 'style-dictionary'
|
|
7
7
|
|
|
8
8
|
import { dtcgDimension } from './style-dictionary/transforms/dtcg-dimension.js'
|
|
9
|
+
import { dtcgFontFamily } from './style-dictionary/transforms/dtcg-font-family.js'
|
|
9
10
|
import { nameCustomCamel } from './style-dictionary/transforms/name-custom-camel.js'
|
|
10
11
|
import { nameCustomKebab } from './style-dictionary/transforms/name-custom-kebab.js'
|
|
11
12
|
import { shadowDTCGDimensionNormalize } from './style-dictionary/transforms/shadow-dtcg-dimension-normalize.js'
|
|
12
13
|
|
|
13
14
|
StyleDictionary.registerTransform(dtcgDimension)
|
|
15
|
+
StyleDictionary.registerTransform(dtcgFontFamily)
|
|
14
16
|
StyleDictionary.registerTransform(nameCustomCamel)
|
|
15
17
|
StyleDictionary.registerTransform(nameCustomKebab)
|
|
16
18
|
StyleDictionary.registerTransform(shadowDTCGDimensionNormalize)
|
|
17
19
|
|
|
18
|
-
const commonCssTransforms = [
|
|
20
|
+
const commonCssTransforms = [
|
|
21
|
+
'shadow/dtcg-dimension-normalize',
|
|
22
|
+
'shadow/css/shorthand',
|
|
23
|
+
'dtcg/dimension',
|
|
24
|
+
'dtcg/fontFamily',
|
|
25
|
+
]
|
|
19
26
|
const modes = ['compact']
|
|
20
27
|
|
|
21
28
|
function generateSharedConfig(mode) {
|
|
@@ -111,6 +118,9 @@ defaultMode.buildAllPlatforms()
|
|
|
111
118
|
|
|
112
119
|
for (const mode of modes) {
|
|
113
120
|
const styleDictionary = new StyleDictionary({
|
|
121
|
+
log: {
|
|
122
|
+
verbosity: 'verbose',
|
|
123
|
+
},
|
|
114
124
|
platforms: generateSharedConfig(mode),
|
|
115
125
|
source: [`./src/**/*.${mode}.tokens.json`],
|
|
116
126
|
})
|
package/dist/compact.css
CHANGED
|
@@ -9,6 +9,8 @@
|
|
|
9
9
|
--ams-border-width-xl: 0.1875rem;
|
|
10
10
|
--ams-border-width-negative-m: -0.0625rem;
|
|
11
11
|
--ams-border-width-negative-xl: -0.1875rem;
|
|
12
|
+
--ams-color-background-body: #e8e8e8;
|
|
13
|
+
--ams-color-background: #ffffff;
|
|
12
14
|
--ams-space-xs: 0.25rem;
|
|
13
15
|
--ams-space-s: 0.5rem;
|
|
14
16
|
--ams-space-m: clamp(0.75rem, 0.6786rem + 0.3571vw, 1rem);
|
|
@@ -23,7 +25,6 @@
|
|
|
23
25
|
--ams-typography-body-text-large-line-height: 1.4;
|
|
24
26
|
--ams-typography-body-text-x-large-font-size: clamp(1.25rem, 1.1964rem + 0.2679vw, 1.4375rem);
|
|
25
27
|
--ams-typography-body-text-x-large-line-height: 1.3;
|
|
26
|
-
--ams-typography-heading-0-font-size: clamp(2.1645rem, 2.072rem + 0.4626vw, 2.4883rem);
|
|
27
28
|
--ams-typography-heading-1-font-size: clamp(1.5rem, 1.4286rem + 0.3571vw, 1.75rem);
|
|
28
29
|
--ams-typography-heading-1-line-height: 1.2;
|
|
29
30
|
--ams-typography-heading-2-line-height: 1.3;
|
|
@@ -35,8 +36,14 @@
|
|
|
35
36
|
--ams-typography-heading-3-font-size: var(--ams-typography-body-text-large-font-size);
|
|
36
37
|
--ams-typography-heading-4-font-size: var(--ams-typography-body-text-font-size);
|
|
37
38
|
--ams-typography-heading-5-font-size: var(--ams-typography-body-text-small-font-size);
|
|
38
|
-
--ams-
|
|
39
|
-
--ams-grid-padding-inline: var(--ams-space-
|
|
39
|
+
--ams-body-background-color: var(--ams-color-background-body);
|
|
40
|
+
--ams-grid-padding-inline: var(--ams-space-m);
|
|
41
|
+
--ams-grid-vi-medium-padding-inline: var(--ams-space-l);
|
|
42
|
+
--ams-grid-vi-wide-padding-inline: var(--ams-space-xl);
|
|
43
|
+
--ams-grid-cell-background-color: var(--ams-color-background);
|
|
44
|
+
--ams-grid-cell-padding-block: var(--ams-space-m);
|
|
45
|
+
--ams-grid-cell-padding-inline: var(--ams-space-m);
|
|
40
46
|
--ams-page-header-brand-name-line-height: var(--ams-typography-heading-2-line-height);
|
|
47
|
+
--ams-page-background-color: var(--ams-color-background-body);
|
|
41
48
|
--ams-page-header-brand-name-font-size: var(--ams-typography-heading-2-font-size);
|
|
42
49
|
}
|
package/dist/compact.d.ts
CHANGED
|
@@ -28,6 +28,12 @@ declare const tokens: {
|
|
|
28
28
|
};
|
|
29
29
|
};
|
|
30
30
|
};
|
|
31
|
+
color: {
|
|
32
|
+
background: {
|
|
33
|
+
body: DesignToken;
|
|
34
|
+
default: DesignToken;
|
|
35
|
+
};
|
|
36
|
+
};
|
|
31
37
|
space: {
|
|
32
38
|
xs: DesignToken;
|
|
33
39
|
s: DesignToken;
|
|
@@ -54,9 +60,6 @@ declare const tokens: {
|
|
|
54
60
|
};
|
|
55
61
|
};
|
|
56
62
|
heading: {
|
|
57
|
-
"0": {
|
|
58
|
-
"font-size": DesignToken;
|
|
59
|
-
};
|
|
60
63
|
"1": {
|
|
61
64
|
"font-size": DesignToken;
|
|
62
65
|
"line-height": DesignToken;
|
|
@@ -77,13 +80,24 @@ declare const tokens: {
|
|
|
77
80
|
"font-size": DesignToken;
|
|
78
81
|
"line-height": DesignToken;
|
|
79
82
|
};
|
|
80
|
-
"6": {
|
|
81
|
-
"font-size": DesignToken;
|
|
82
|
-
};
|
|
83
83
|
};
|
|
84
84
|
};
|
|
85
|
+
body: {
|
|
86
|
+
"background-color": DesignToken;
|
|
87
|
+
};
|
|
85
88
|
grid: {
|
|
86
89
|
"padding-inline": DesignToken;
|
|
90
|
+
"vi-medium": {
|
|
91
|
+
"padding-inline": DesignToken;
|
|
92
|
+
};
|
|
93
|
+
"vi-wide": {
|
|
94
|
+
"padding-inline": DesignToken;
|
|
95
|
+
};
|
|
96
|
+
cell: {
|
|
97
|
+
"background-color": DesignToken;
|
|
98
|
+
"padding-block": DesignToken;
|
|
99
|
+
"padding-inline": DesignToken;
|
|
100
|
+
};
|
|
87
101
|
};
|
|
88
102
|
"page-header": {
|
|
89
103
|
"brand-name": {
|
|
@@ -94,5 +108,8 @@ declare const tokens: {
|
|
|
94
108
|
"padding-block": DesignToken;
|
|
95
109
|
};
|
|
96
110
|
};
|
|
111
|
+
page: {
|
|
112
|
+
"background-color": DesignToken;
|
|
113
|
+
};
|
|
97
114
|
};
|
|
98
115
|
};
|
package/dist/compact.json
CHANGED
|
@@ -12,6 +12,12 @@
|
|
|
12
12
|
}
|
|
13
13
|
}
|
|
14
14
|
},
|
|
15
|
+
"color": {
|
|
16
|
+
"background": {
|
|
17
|
+
"body": "#e8e8e8",
|
|
18
|
+
"default": "#ffffff"
|
|
19
|
+
}
|
|
20
|
+
},
|
|
15
21
|
"space": {
|
|
16
22
|
"xs": "0.25rem",
|
|
17
23
|
"s": "0.5rem",
|
|
@@ -23,60 +29,71 @@
|
|
|
23
29
|
"typography": {
|
|
24
30
|
"body-text": {
|
|
25
31
|
"font-size": "1rem",
|
|
26
|
-
"line-height":
|
|
32
|
+
"line-height": 1.5,
|
|
27
33
|
"small": {
|
|
28
34
|
"font-size": "0.875rem",
|
|
29
|
-
"line-height":
|
|
35
|
+
"line-height": 1.4
|
|
30
36
|
},
|
|
31
37
|
"large": {
|
|
32
38
|
"font-size": "clamp(1.125rem, 1.1071rem + 0.0893vw, 1.1875rem)",
|
|
33
|
-
"line-height":
|
|
39
|
+
"line-height": 1.4
|
|
34
40
|
},
|
|
35
41
|
"x-large": {
|
|
36
42
|
"font-size": "clamp(1.25rem, 1.1964rem + 0.2679vw, 1.4375rem)",
|
|
37
|
-
"line-height":
|
|
43
|
+
"line-height": 1.3
|
|
38
44
|
}
|
|
39
45
|
},
|
|
40
46
|
"heading": {
|
|
41
|
-
"0": {
|
|
42
|
-
"font-size": "clamp(2.1645rem, 2.072rem + 0.4626vw, 2.4883rem)"
|
|
43
|
-
},
|
|
44
47
|
"1": {
|
|
45
48
|
"font-size": "clamp(1.5rem, 1.4286rem + 0.3571vw, 1.75rem)",
|
|
46
|
-
"line-height":
|
|
49
|
+
"line-height": 1.2
|
|
47
50
|
},
|
|
48
51
|
"2": {
|
|
49
52
|
"font-size": "clamp(1.25rem, 1.1964rem + 0.2679vw, 1.4375rem)",
|
|
50
|
-
"line-height":
|
|
53
|
+
"line-height": 1.3
|
|
51
54
|
},
|
|
52
55
|
"3": {
|
|
53
56
|
"font-size": "clamp(1.125rem, 1.1071rem + 0.0893vw, 1.1875rem)",
|
|
54
|
-
"line-height":
|
|
57
|
+
"line-height": 1.3
|
|
55
58
|
},
|
|
56
59
|
"4": {
|
|
57
60
|
"font-size": "1rem",
|
|
58
|
-
"line-height":
|
|
61
|
+
"line-height": 1.4
|
|
59
62
|
},
|
|
60
63
|
"5": {
|
|
61
64
|
"font-size": "0.875rem",
|
|
62
|
-
"line-height":
|
|
63
|
-
},
|
|
64
|
-
"6": {
|
|
65
|
-
"font-size": "0.875rem"
|
|
65
|
+
"line-height": 1.4
|
|
66
66
|
}
|
|
67
67
|
}
|
|
68
68
|
},
|
|
69
|
+
"body": {
|
|
70
|
+
"background-color": "#e8e8e8"
|
|
71
|
+
},
|
|
69
72
|
"grid": {
|
|
70
|
-
"padding-inline": "clamp(
|
|
73
|
+
"padding-inline": "clamp(0.75rem, 0.6786rem + 0.3571vw, 1rem)",
|
|
74
|
+
"vi-medium": {
|
|
75
|
+
"padding-inline": "clamp(1rem, 0.8571rem + 0.7143vw, 1.5rem)"
|
|
76
|
+
},
|
|
77
|
+
"vi-wide": {
|
|
78
|
+
"padding-inline": "clamp(1.5rem, 1.2857rem + 1.0714vw, 2.25rem)"
|
|
79
|
+
},
|
|
80
|
+
"cell": {
|
|
81
|
+
"background-color": "#ffffff",
|
|
82
|
+
"padding-block": "clamp(0.75rem, 0.6786rem + 0.3571vw, 1rem)",
|
|
83
|
+
"padding-inline": "clamp(0.75rem, 0.6786rem + 0.3571vw, 1rem)"
|
|
84
|
+
}
|
|
71
85
|
},
|
|
72
86
|
"page-header": {
|
|
73
87
|
"brand-name": {
|
|
74
88
|
"font-size": "clamp(1.25rem, 1.1964rem + 0.2679vw, 1.4375rem)",
|
|
75
|
-
"line-height":
|
|
89
|
+
"line-height": 1.3
|
|
76
90
|
},
|
|
77
91
|
"mega-menu": {
|
|
78
92
|
"padding-block": "0"
|
|
79
93
|
}
|
|
94
|
+
},
|
|
95
|
+
"page": {
|
|
96
|
+
"background-color": "#e8e8e8"
|
|
80
97
|
}
|
|
81
98
|
}
|
|
82
99
|
}
|