@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.
Files changed (97) hide show
  1. package/AGENTS.md +71 -0
  2. package/CHANGELOG.md +57 -3
  3. package/CONTRIBUTING.md +18 -0
  4. package/README.md +131 -22
  5. package/build.js +11 -1
  6. package/dist/compact.css +10 -3
  7. package/dist/compact.d.ts +23 -6
  8. package/dist/compact.json +34 -17
  9. package/dist/compact.mjs +23 -13
  10. package/dist/compact.scss +10 -3
  11. package/dist/compact.theme.css +10 -3
  12. package/dist/index.css +108 -110
  13. package/dist/index.d.ts +112 -110
  14. package/dist/index.json +218 -216
  15. package/dist/index.mjs +218 -208
  16. package/dist/index.scss +108 -110
  17. package/dist/index.theme.css +108 -110
  18. package/package.json +2 -2
  19. package/src/brand/ams/aspect-ratio.tokens.json +24 -6
  20. package/src/brand/ams/border.tokens.json +5 -0
  21. package/src/brand/ams/color.compact.tokens.json +15 -0
  22. package/src/brand/ams/color.tokens.json +37 -54
  23. package/src/brand/ams/cursor.tokens.json +9 -2
  24. package/src/brand/ams/focus.tokens.json +1 -0
  25. package/src/brand/ams/space.compact.tokens.json +16 -4
  26. package/src/brand/ams/space.tokens.json +31 -6
  27. package/src/brand/ams/typography.compact.tokens.json +36 -45
  28. package/src/brand/ams/typography.tokens.json +59 -63
  29. package/src/common/ams/inputs.tokens.json +41 -19
  30. package/src/common/ams/links.tokens.json +35 -10
  31. package/src/components/ams/accordion.tokens.json +17 -48
  32. package/src/components/ams/action-group.tokens.json +2 -2
  33. package/src/components/ams/alert.tokens.json +38 -20
  34. package/src/components/ams/avatar.tokens.json +79 -29
  35. package/src/components/ams/badge.tokens.json +60 -23
  36. package/src/components/ams/blockquote.tokens.json +14 -5
  37. package/src/components/ams/body.compact.tokens.json +12 -0
  38. package/src/components/ams/body.tokens.json +12 -0
  39. package/src/components/ams/breadcrumb.tokens.json +36 -15
  40. package/src/components/ams/button.tokens.json +74 -33
  41. package/src/components/ams/call-to-action-link.tokens.json +29 -16
  42. package/src/components/ams/card.tokens.json +30 -17
  43. package/src/components/ams/character-count.tokens.json +14 -5
  44. package/src/components/ams/checkbox.tokens.json +101 -74
  45. package/src/components/ams/column.tokens.json +10 -10
  46. package/src/components/ams/date-input.tokens.json +55 -50
  47. package/src/components/ams/description-list.tokens.json +85 -24
  48. package/src/components/ams/dialog.tokens.json +104 -28
  49. package/src/components/ams/error-message.tokens.json +13 -6
  50. package/src/components/ams/field-set.tokens.json +35 -20
  51. package/src/components/ams/field.tokens.json +13 -10
  52. package/src/components/ams/figure.tokens.json +16 -7
  53. package/src/components/ams/file-input.tokens.json +69 -31
  54. package/src/components/ams/file-list.tokens.json +20 -11
  55. package/src/components/ams/grid.compact.tokens.json +43 -3
  56. package/src/components/ams/grid.tokens.json +77 -24
  57. package/src/components/ams/heading.tokens.json +38 -36
  58. package/src/components/ams/hint.tokens.json +6 -2
  59. package/src/components/ams/icon-button.tokens.json +46 -16
  60. package/src/components/ams/icon.tokens.json +19 -39
  61. package/src/components/ams/image-slider.tokens.json +28 -16
  62. package/src/components/ams/image.tokens.json +4 -1
  63. package/src/components/ams/invalid-form-alert.tokens.json +2 -2
  64. package/src/components/ams/label.tokens.json +18 -6
  65. package/src/components/ams/link-list.tokens.json +50 -22
  66. package/src/components/ams/link.tokens.json +38 -25
  67. package/src/components/ams/logo.tokens.json +6 -2
  68. package/src/components/ams/mark.tokens.json +3 -1
  69. package/src/components/ams/menu.tokens.json +80 -55
  70. package/src/components/ams/ordered-list.tokens.json +39 -25
  71. package/src/components/ams/page-footer.tokens.json +70 -26
  72. package/src/components/ams/page-header.compact.tokens.json +2 -1
  73. package/src/components/ams/page-header.tokens.json +128 -59
  74. package/src/components/ams/page.compact.tokens.json +12 -0
  75. package/src/components/ams/page.tokens.json +5 -3
  76. package/src/components/ams/pagination.tokens.json +37 -17
  77. package/src/components/ams/paragraph.tokens.json +22 -8
  78. package/src/components/ams/password-input.tokens.json +47 -21
  79. package/src/components/ams/progress-list.tokens.json +152 -61
  80. package/src/components/ams/radio.tokens.json +97 -36
  81. package/src/components/ams/row.tokens.json +10 -10
  82. package/src/components/ams/search-field.tokens.json +57 -24
  83. package/src/components/ams/select.tokens.json +63 -25
  84. package/src/components/ams/skip-link.tokens.json +23 -12
  85. package/src/components/ams/spotlight.tokens.json +21 -7
  86. package/src/components/ams/standalone-link.tokens.json +42 -46
  87. package/src/components/ams/switch.tokens.json +23 -9
  88. package/src/components/ams/tab-navigation.tokens.json +205 -0
  89. package/src/components/ams/table-of-contents.tokens.json +38 -41
  90. package/src/components/ams/table.tokens.json +29 -10
  91. package/src/components/ams/tabs.tokens.json +36 -17
  92. package/src/components/ams/text-area.tokens.json +49 -23
  93. package/src/components/ams/text-input.tokens.json +47 -21
  94. package/src/components/ams/time-input.tokens.json +55 -50
  95. package/src/components/ams/unordered-list.tokens.json +37 -25
  96. package/style-dictionary/transforms/dtcg-font-family.js +32 -0
  97. 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 in release 5.0.0:
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 will be removed in release 4.0.0. If you use them in your code, please delete them.
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 will be removed in release 4.0.0. If you use them in your code, please delete them.
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.*`
@@ -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 have a type or extension that we use to generate visual previews in our documentation.
168
- When adding new tokens, define a type from the DTCG specification or add one of our custom extensions when needed.
169
- Do not add an type or extension if the token cannot be previewed.
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
- | `fontFamily` | Font family definitions |
180
- | `fontWeight` | Font weight values |
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
- For some properties, we add custom types under `$extensions.nl.amsterdam.type`:
187
-
188
- | Type | Description |
189
- | ------------- | -------------------------------- |
190
- | `borderStyle` | Border style values |
191
- | `borderWidth` | Border thickness values |
192
- | `fontSize` | Font size values |
193
- | `lineHeight` | Unitless line height multipliers |
194
-
195
- Tokens without a type have values that we currently do not preview.
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 | For type | Description |
202
- | ------- | ----------- | -------------------------- |
203
- | `space` | `dimension` | Margins, paddings and gaps |
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 = ['shadow/dtcg-dimension-normalize', 'shadow/css/shorthand', 'dtcg/dimension']
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-typography-heading-6-font-size: var(--ams-typography-body-text-small-font-size);
39
- --ams-grid-padding-inline: var(--ams-space-xl);
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": "1.5",
32
+ "line-height": 1.5,
27
33
  "small": {
28
34
  "font-size": "0.875rem",
29
- "line-height": "1.4"
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": "1.4"
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": "1.3"
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": "1.2"
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": "1.3"
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": "1.3"
57
+ "line-height": 1.3
55
58
  },
56
59
  "4": {
57
60
  "font-size": "1rem",
58
- "line-height": "1.4"
61
+ "line-height": 1.4
59
62
  },
60
63
  "5": {
61
64
  "font-size": "0.875rem",
62
- "line-height": "1.4"
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(1.5rem, 1.2857rem + 1.0714vw, 2.25rem)"
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": "1.3"
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
  }