@amsterdam/design-system-tokens 4.0.0 → 4.1.0

package/AGENTS.md

@@ -0,0 +1,71 @@
+<!-- @license CC0-1.0 -->
+
+# Tokens Package — Agent Instructions
+
+These instructions are additive to the root [AGENTS.md](../../AGENTS.md). Read that first.
+
+See [README.md](README.md) for full token usage and design guidance; this file focuses on agent-specific rules for editing token source files.
+
+## Overview
+
+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/).
+
+## Token structure
+
+Tokens are organized into three layers:
+
+| Directory          | Purpose                                           |
+| ------------------ | ------------------------------------------------- |
+| `src/brand/ams/`   | Brand-level values (colors, typography, spacing)  |
+| `src/common/ams/`  | Shared patterns across components (inputs, links) |
+| `src/components/ams/` | Component-specific tokens                      |
+
+## Token file format
+
+Token files use the `.tokens.json` extension and follow the DTCG format:
+
+```json
+{
+  "ams": {
+    "<component-name>": {
+      "<property>": {
+        "$value": "{ams.<reference>}",
+        "$type": "<dtcg-type>"
+      }
+    }
+  }
+}
+```
+
+- Always reference existing brand or common tokens where possible — do not hardcode raw values.
+- Valid `$type` values used in this project: `color`, `dimension`, `fontFamily`, `fontWeight`, `shadow`. Do not invent other `$type` values.
+- 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.
+- Variant tokens are nested under the component (e.g. `ams.badge.azure.background-color`).
+
+## Compact mode
+
+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.
+
+## Build
+
+- Build command: `pnpm build` (runs `node build.js`)
+- Watch mode: `pnpm build:watch`
+- Output: `dist/` — never edit generated output directly.
+- Build config: `build.js` with custom Style Dictionary logic in `style-dictionary/` (includes `transforms/` and `dimensionToString.js`).
+
+## File locations
+
+- Component tokens: `src/components/ams/<name>.tokens.json`
+- Brand tokens: `src/brand/ams/`
+- Common tokens: `src/common/ams/`
+- Build script: `build.js`
+- Custom transforms: `style-dictionary/transforms/`
+
+## Key rules
+
+- 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.
+- Token names use kebab-case and mirror CSS property names where applicable.
+- No unused tokens — every defined token must be consumed by CSS or another token.
+- No hardcoded design values in CSS or React — if a value is missing, add a token here first.
+- Changes to brand-level tokens in `src/brand/ams/` have wide impact; do not change them unless the task explicitly calls for brand updates.
+- 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

@@ -3,6 +3,31 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [4.1.0](https://github.com/Amsterdam/design-system/compare/design-system-tokens-v4.0.1...design-system-tokens-v4.1.0) (2026-06-23)
+
+
+### Features
+
+* **Calendar:** Add Calendar component ([#2659](https://github.com/Amsterdam/design-system/issues/2659)) ([03e51f3](https://github.com/Amsterdam/design-system/commit/03e51f3bfff4062f9523a57e3aad920c324665ff))
+* **Date Picker:** Add Date Picker component ([#2660](https://github.com/Amsterdam/design-system/issues/2660)) ([b7c5a10](https://github.com/Amsterdam/design-system/commit/b7c5a1091aeafac1b3f75f657c2dce7e92c5da50))
+* Decrease font weight for all bold text ([#2647](https://github.com/Amsterdam/design-system/issues/2647)) ([d0bac44](https://github.com/Amsterdam/design-system/commit/d0bac44d15f40c53f6640564a1f08698ad4b44e9))
+* **Dialog, Grid Cell, Page:** Add containment context to allow container-based layouts ([#2562](https://github.com/Amsterdam/design-system/issues/2562)) ([7e4fc6a](https://github.com/Amsterdam/design-system/commit/7e4fc6af2ad12c1a0778513269922b2f2ab5f148))
+* **Pagination:** Add tokens and elements for theming, active state, ellipsis, and relative-link ([#2690](https://github.com/Amsterdam/design-system/issues/2690)) ([f1ad13a](https://github.com/Amsterdam/design-system/commit/f1ad13a5ec9f8dca214090eff8064a0b2e5b24d8))
+* **Table of Contents:** Make items with nested lists optionally collapsible ([#2584](https://github.com/Amsterdam/design-system/issues/2584)) ([cf6871b](https://github.com/Amsterdam/design-system/commit/cf6871b51dedb727255708425c3a9723965b9169))
+
+
+### Bug Fixes
+
+* **Switch:** Keep the track border visible in forced colors mode ([#2656](https://github.com/Amsterdam/design-system/issues/2656)) ([b402c31](https://github.com/Amsterdam/design-system/commit/b402c31cc326c1cea0524fcd4da96ded54a56a88))
+* **tokens:** Restore real values to deprecated tokens ([#2707](https://github.com/Amsterdam/design-system/issues/2707)) ([6363654](https://github.com/Amsterdam/design-system/commit/6363654e98312aed6e5f9b053300f5d02424f99f))
+
+## [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)
+
+
+### Bug Fixes
+
+* **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))
+
 ## [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)
 
 

package/CONTRIBUTING.md

@@ -0,0 +1,18 @@
+<!-- @license CC0-1.0 -->
+
+# Contributing to the tokens package
+
+See the [repository-wide contributing guidelines](../../CONTRIBUTING.md) for general instructions.
+The notes below apply specifically to design tokens.
+
+## Compact Mode and responsive overrides
+
+Components may expose separate tokens for responsive variants, such as `vi-medium` and `vi-wide` for the Grid.
+These are applied at breakpoints in the component stylesheet and override the base token.
+
+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.
+If it does, override every responsive variant in the compact file as well.
+Otherwise, the compact value only applies below the first breakpoint, and the component silently reverts to the default token at larger viewports.
+
+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.
+Compact Mode must override all three, not just the base.

package/README.md

@@ -176,68 +176,56 @@ Note that redefining the value of a token is a much better approach than redecla
 
 ## Deprecating tokens
 
-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.
+A deprecated token keeps working until it is removed, so it must always hold a real value.
 
-In ADS, `$deprecated` should be a string so consumers always get a reason + migration path.
+We provide a reason and a migration path through the DTCG `$deprecated` field.
+When there is a direct replacement, start the message with ``Use `<replacement-token>` instead.``
+End every message with a removal date: `Will be removed on or after YYYY-MM-DD.`
 
-### Deprecation message format
+### Renaming a token
 
-- Always include a removal date: `Will be removed on or after YYYY-MM-DD.`
-- If there is a direct replacement, start with: ``Use `<replacement-token>` instead.``
+Keep the old name intact during the deprecation window, while adding the new name for the same value.
+Wire the rename through a `var()` fallback, so downstream overrides of the old name keep working.
 
-### Simple deprecation (no fallback)
-
-If a deprecated token is still used directly, keep its existing `$value` until removal.
-Also add a deprecation comment next to the token usage in the consuming CSS.
-
-Token JSON:
+1. Point the deprecated token’s `$value` at the replacement, so it resolves to the same value:
 
 ```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": "0"
+"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}"
+  }
 }
 ```
 
-Component CSS:
+2. In the component CSS, reference the deprecated token first, with the replacement as the fallback:
+   Mark the deprecation in the component stylesheet as well; no need to copy the details from the tokens file.
 
 ```css
-row-gap: var(--ams-description-list-row-gap); /* This token is @deprecated. Will be removed on or after 2026-10-20. */
+padding-inline: var(--ams-grid-medium-padding-inline /* @deprecated */, var(--ams-grid-vi-medium-padding-inline));
 ```
 
-### Renames that use `var()` fallback
-
-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.
+3. If a theme overrides the replacement (for example Compact Mode), overriding the replacement token is enough because the deprecated token references it.
+   Only repeat the deprecated token in a theme tokens file if you need to override the deprecated token itself for legacy consumers.
 
-Always add an inline deprecation comment next to the deprecated custom property inside the `var()` call.
+### Removing a token
 
-1. Update the component CSS to reference the deprecated token first, and the replacement token as the fallback:
-
-```css
-padding-inline: var(
-  --ams-grid-medium-padding-inline /* This token is @deprecated. Will be removed on or after 2026-10-20. */,
-  var(--ams-grid-vi-medium-padding-inline)
-);
-```
-
-2. In the token JSON, mark the old token as deprecated and set its `$value` to the CSS-wide keyword `initial`:
+A removal will always be a breaking change, so it must be part of a major release.
+Plan the deprecation early, as it must stay in place for at least six months.
+The value of the token cannot change during the deprecation window, as we consider visual consequences for downstream users a breaking change.
 
 ```jsonc
-"medium": {
-  "padding-inline": {
-    "$deprecated": "Use `ams.grid.vi-medium.padding-inline` instead. Will be removed on or after 2026-10-20.",
-    "$value": "initial"
-  }
+"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)"
 }
 ```
 
-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.
-
-Only apply this `initial` rule when the deprecated token is used in a `var(--deprecated, <fallback>)` pattern.
-
-### Deprecations without a 1:1 replacement
+Surface the deprecation in the stylesheet as well.
 
-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.
+```css
+row-gap: var(--ams-description-list-row-gap); /* @deprecated Will be removed on or after 2026-10-20. */
+```
 
 ## Token types
 

package/dist/compact.css

@@ -31,13 +31,16 @@
   --ams-typography-heading-3-line-height: 1.3;
   --ams-typography-heading-4-line-height: 1.4;
   --ams-typography-heading-5-line-height: 1.4;
+  --ams-calendar-inline-size: 16rem;
   --ams-page-header-mega-menu-padding-block: 0;
   --ams-typography-heading-2-font-size: var(--ams-typography-body-text-x-large-font-size);
   --ams-typography-heading-3-font-size: var(--ams-typography-body-text-large-font-size);
   --ams-typography-heading-4-font-size: var(--ams-typography-body-text-font-size);
   --ams-typography-heading-5-font-size: var(--ams-typography-body-text-small-font-size);
   --ams-body-background-color: var(--ams-color-background-body);
-  --ams-grid-padding-inline: var(--ams-space-xl);
+  --ams-grid-padding-inline: var(--ams-space-m);
+  --ams-grid-vi-medium-padding-inline: var(--ams-space-l);
+  --ams-grid-vi-wide-padding-inline: var(--ams-space-xl);
   --ams-grid-cell-background-color: var(--ams-color-background);
   --ams-grid-cell-padding-block: var(--ams-space-m);
   --ams-grid-cell-padding-inline: var(--ams-space-m);

package/dist/compact.d.ts

@@ -85,8 +85,17 @@ declare const tokens: {
     body: {
       "background-color": DesignToken;
     };
+    calendar: {
+      "inline-size": DesignToken;
+    };
     grid: {
       "padding-inline": DesignToken;
+      "vi-medium": {
+        "padding-inline": DesignToken;
+      };
+      "vi-wide": {
+        "padding-inline": DesignToken;
+      };
       cell: {
         "background-color": DesignToken;
         "padding-block": DesignToken;

package/dist/compact.json

@@ -69,8 +69,17 @@
     "body": {
       "background-color": "#e8e8e8"
     },
+    "calendar": {
+      "inline-size": "16rem"
+    },
     "grid": {
-      "padding-inline": "clamp(1.5rem, 1.2857rem + 1.0714vw, 2.25rem)",
+      "padding-inline": "clamp(0.75rem, 0.6786rem + 0.3571vw, 1rem)",
+      "vi-medium": {
+        "padding-inline": "clamp(1rem, 0.8571rem + 0.7143vw, 1.5rem)"
+      },
+      "vi-wide": {
+        "padding-inline": "clamp(1.5rem, 1.2857rem + 1.0714vw, 2.25rem)"
+      },
       "cell": {
         "background-color": "#ffffff",
         "padding-block": "clamp(0.75rem, 0.6786rem + 0.3571vw, 1rem)",

package/dist/compact.mjs

@@ -40,7 +40,12 @@ export const amsTypographyHeading_4LineHeight = 1.4;
 export const amsTypographyHeading_5FontSize = "0.875rem";
 export const amsTypographyHeading_5LineHeight = 1.4;
 export const amsBodyBackgroundColor = "#e8e8e8";
+export const amsCalendarInlineSize = "16rem";
 export const amsGridPaddingInline =
+  "clamp(0.75rem, 0.6786rem + 0.3571vw, 1rem)";
+export const amsGridViMediumPaddingInline =
+  "clamp(1rem, 0.8571rem + 0.7143vw, 1.5rem)";
+export const amsGridViWidePaddingInline =
   "clamp(1.5rem, 1.2857rem + 1.0714vw, 2.25rem)";
 export const amsGridCellBackgroundColor = "#ffffff";
 export const amsGridCellPaddingBlock =

package/dist/compact.scss

@@ -29,13 +29,16 @@ $ams-typography-heading-2-line-height: 1.3;
 $ams-typography-heading-3-line-height: 1.3;
 $ams-typography-heading-4-line-height: 1.4;
 $ams-typography-heading-5-line-height: 1.4;
+$ams-calendar-inline-size: 16rem;
 $ams-page-header-mega-menu-padding-block: 0;
 $ams-typography-heading-2-font-size: $ams-typography-body-text-x-large-font-size;
 $ams-typography-heading-3-font-size: $ams-typography-body-text-large-font-size;
 $ams-typography-heading-4-font-size: $ams-typography-body-text-font-size;
 $ams-typography-heading-5-font-size: $ams-typography-body-text-small-font-size;
 $ams-body-background-color: $ams-color-background-body;
-$ams-grid-padding-inline: $ams-space-xl;
+$ams-grid-padding-inline: $ams-space-m;
+$ams-grid-vi-medium-padding-inline: $ams-space-l;
+$ams-grid-vi-wide-padding-inline: $ams-space-xl;
 $ams-grid-cell-background-color: $ams-color-background;
 $ams-grid-cell-padding-block: $ams-space-m;
 $ams-grid-cell-padding-inline: $ams-space-m;

package/dist/compact.theme.css

@@ -31,13 +31,16 @@
   --ams-typography-heading-3-line-height: 1.3;
   --ams-typography-heading-4-line-height: 1.4;
   --ams-typography-heading-5-line-height: 1.4;
+  --ams-calendar-inline-size: 16rem;
   --ams-page-header-mega-menu-padding-block: 0;
   --ams-typography-heading-2-font-size: var(--ams-typography-body-text-x-large-font-size);
   --ams-typography-heading-3-font-size: var(--ams-typography-body-text-large-font-size);
   --ams-typography-heading-4-font-size: var(--ams-typography-body-text-font-size);
   --ams-typography-heading-5-font-size: var(--ams-typography-body-text-small-font-size);
   --ams-body-background-color: var(--ams-color-background-body);
-  --ams-grid-padding-inline: var(--ams-space-xl);
+  --ams-grid-padding-inline: var(--ams-space-m);
+  --ams-grid-vi-medium-padding-inline: var(--ams-space-l);
+  --ams-grid-vi-wide-padding-inline: var(--ams-space-xl);
   --ams-grid-cell-background-color: var(--ams-color-background);
   --ams-grid-cell-padding-block: var(--ams-space-m);
   --ams-grid-cell-padding-inline: var(--ams-space-m);