@amsterdam/design-system-tokens 4.0.0 → 4.0.1

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,13 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [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/dist/compact.css

@@ -37,7 +37,9 @@
   --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

@@ -87,6 +87,12 @@ declare const tokens: {
     };
     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

@@ -70,7 +70,13 @@
       "background-color": "#e8e8e8"
     },
     "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

@@ -41,6 +41,10 @@ export const amsTypographyHeading_5FontSize = "0.875rem";
 export const amsTypographyHeading_5LineHeight = 1.4;
 export const amsBodyBackgroundColor = "#e8e8e8";
 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

@@ -35,7 +35,9 @@ $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

@@ -37,7 +37,9 @@
   --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/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "4.0.0",
+  "version": "4.0.1",
   "author": "Design System Team, City of Amsterdam <designsystem@amsterdam.nl>",
   "description": "All design tokens from the Amsterdam Design System. Use it to apply its visual design to your website or application.",
   "homepage": "https://designsystem.amsterdam",
@@ -30,6 +30,6 @@
   "scripts": {
     "clean": "rimraf dist/",
     "build": "node build.js",
-    "build:watch": "chokidar --follow-symlinks --initial --command \"npm run build\" \"src/**/*.tokens.json\""
+    "build:watch": "chokidar --follow-symlinks --initial --command \"pnpm run build\" \"src/**/*.tokens.json\""
   }
 }

package/src/components/ams/grid.compact.tokens.json

@@ -2,12 +2,30 @@
   "ams": {
     "grid": {
       "padding-inline": {
-        "$value": "{ams.space.xl}",
+        "$value": "{ams.space.m}",
         "$extensions": {
           "nl.amsterdam.subtype": "space",
           "nl.amsterdam.type": "dimension"
         }
       },
+      "vi-medium": {
+        "padding-inline": {
+          "$value": "{ams.space.l}",
+          "$extensions": {
+            "nl.amsterdam.subtype": "space",
+            "nl.amsterdam.type": "dimension"
+          }
+        }
+      },
+      "vi-wide": {
+        "padding-inline": {
+          "$value": "{ams.space.xl}",
+          "$extensions": {
+            "nl.amsterdam.subtype": "space",
+            "nl.amsterdam.type": "dimension"
+          }
+        }
+      },
       "cell": {
         "background-color": {
           "$value": "{ams.color.background.default}",