@amsterdam/design-system-css 3.2.1 → 4.0.0

package/src/components/margin/README.md

@@ -15,9 +15,10 @@ Six options are available for the width or height of the bottom margin:
 - `ams-mb-xl`
 - `ams-mb-2xl`
 
+These classes apply the [design tokens for space](/docs/brand-design-tokens-space--docs).
+
 Because spacing is responsive, the margins are as well.
 They are also smaller in [Compact Mode](https://designsystem.amsterdam/docs/docs-developer-guide-modes--docs).
-Consult the [Space](/docs/brand-design-tokens-space--docs) docs for an indication of their sizes.
 
 ## Guidelines
 
@@ -29,3 +30,4 @@ Consult the [Space](/docs/brand-design-tokens-space--docs) docs for an indicatio
   Consult [MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_box_model/Mastering_margin_collapsing) for details.
 - To add equal margins between elements, either use the [Gap](/docs/utilities-css-gap--docs) utility class on their common parent or wrap them in a [Column](/docs/components-layout-column--docs) component.
   This helps in loops: it prevents having to treat the last element differently.
+- Wrap editorial content in the [Prose](/docs/utilities-css-prose--docs) utility class to have all spacing set automatically.

package/src/components/menu/menu.scss

@@ -23,24 +23,42 @@
   // We subtract the menu link padding to align the items with surrounding content.
   padding-inline: calc(var(--ams-grid-padding-inline) - var(--ams-menu-link-padding-inline));
 
-  @media screen and (min-width: $ams-breakpoint-medium) {
-    margin-inline: calc(var(--ams-grid-medium-padding-inline) * -1);
-    padding-inline: var(--ams-grid-medium-padding-inline);
+  @media (min-width: $ams-breakpoint-medium) {
+    margin-inline: calc(
+      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)
+        ) *
+        -1
+    );
+    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)
+    );
   }
 
-  @media screen and (min-width: $ams-breakpoint-wide) {
+  @media (min-width: $ams-breakpoint-wide) {
     display: none;
     margin-inline: 0; // Override negative margin above.
-    max-inline-size: var(--ams-menu-wide-max-inline-size);
-    padding-block: var(--ams-menu-wide-padding-block);
-    padding-inline: var(--ams-menu-wide-padding-inline);
+    max-inline-size: var(
+      --ams-menu-wide-max-inline-size /* This token is @deprecated. Will be removed on or after 2026-10-20. */,
+      var(--ams-menu-vi-wide-max-inline-size)
+    );
+    padding-block: var(
+      --ams-menu-wide-padding-block /* This token is @deprecated. Will be removed on or after 2026-10-20. */,
+      var(--ams-menu-vi-wide-padding-block)
+    );
+    padding-inline: var(
+      --ams-menu-wide-padding-inline /* This token is @deprecated. Will be removed on or after 2026-10-20. */,
+      var(--ams-menu-vi-wide-padding-inline)
+    );
   }
 }
 
 .ams-menu--in-wide-window {
   display: none;
 
-  @media screen and (min-width: $ams-breakpoint-wide) {
+  @media (min-width: $ams-breakpoint-wide) {
     display: block;
   }
 }
@@ -53,7 +71,7 @@
   @include hyphenation;
   @include text-rendering;
 
-  @media screen and (min-width: $ams-breakpoint-wide) {
+  @media (min-width: $ams-breakpoint-wide) {
     gap: var(--ams-menu-list-gap);
   }
 }
@@ -79,11 +97,14 @@
     align-self: initial;
   }
 
-  @media screen and (min-width: $ams-breakpoint-wide) {
+  @media (min-width: $ams-breakpoint-wide) {
     align-items: center;
     display: flex; // The links do stretch in the vertical layout of Menu.
     flex-direction: column;
-    gap: var(--ams-menu-link-wide-gap);
+    gap: var(
+      --ams-menu-link-wide-gap /* This token is @deprecated. Will be removed on or after 2026-10-20. */,
+      var(--ams-menu-link-vi-wide-gap)
+    );
     text-align: center;
 
     .ams-menu__icon {
@@ -92,21 +113,3 @@
     }
   }
 }
-
-/** @deprecated The menu has a dark background now, so this is no longer needed. */
-.ams-menu__link--contrast {
-  color: var(--ams-menu-link-contrast-color);
-
-  &:hover {
-    color: var(--ams-menu-link-contrast-hover-color);
-  }
-}
-
-/** @deprecated The menu has a dark background now, so this is no longer needed. */
-.ams-menu__link--inverse {
-  color: var(--ams-menu-link-inverse-color);
-
-  &:hover {
-    color: var(--ams-menu-link-inverse-hover-color);
-  }
-}

package/src/components/page-footer/page-footer.scss

@@ -5,16 +5,20 @@
 
 @use "../../common/breakpoint" as *;
 @use "../../common/hyphenation" as *;
+@use "../../common/print-exact" as *;
 @use "../../common/resets" as *;
 @use "../../common/text-rendering" as *;
 
 .ams-page-footer__spotlight {
   background-color: var(--ams-page-footer-spotlight-background-color);
+
+  @include print-exact;
 }
 
 .ams-page-footer__menu {
   @include reset-ul;
 
+  background-color: var(--ams-page-footer-menu-background-color);
   column-gap: var(--ams-page-footer-menu-column-gap);
   display: flex;
   flex-wrap: wrap;
@@ -22,12 +26,20 @@
   padding-inline: var(--ams-page-footer-menu-padding-inline);
   row-gap: var(--ams-page-footer-menu-row-gap);
 
-  @media screen and (min-width: $ams-breakpoint-medium) {
-    padding-inline: var(--ams-page-footer-menu-medium-padding-inline);
+  @media (min-width: $ams-breakpoint-medium) {
+    padding-inline: var(
+      --ams-page-footer-menu-medium-padding-inline
+        /* This token is @deprecated. Will be removed on or after 2026-10-20. */,
+      var(--ams-page-footer-menu-vi-medium-padding-inline)
+    );
   }
 
-  @media screen and (min-width: $ams-breakpoint-wide) {
-    padding-inline: var(--ams-page-footer-menu-wide-padding-inline);
+  @media (min-width: $ams-breakpoint-wide) {
+    padding-inline: var(
+      --ams-page-footer-menu-wide-padding-inline
+        /* This token is @deprecated. Will be removed on or after 2026-10-20. */,
+      var(--ams-page-footer-menu-vi-wide-padding-inline)
+    );
   }
 }
 

package/src/components/page-header/README.md

@@ -2,30 +2,14 @@
 
 # Page Header
 
-Displays the City’s logo at the top of every page, and optionally a navigation menu.
-Includes the name of the website if it is not the general one.
+Conveys the origin and authority of the website through a logo and an optional name.
+Can serve as a consistent starting point for navigation.
 
 ## Guidelines
 
-- The Page Header must be used on all websites for the City of Amsterdam.
-- It includes the logo of the City or the organization, the site title (except for the general website), and a menu with links to commonly used pages.
-- The Page Header is important because it conveys our corporate identity and is the first thing people see.
-  Using it consistently helps users recognize and trust the website.
-- The Page Header is the same on every page of the website, although full-screen pages may hide it, e.g. a video or a map.
-- The inline menu can contain a maximum of 5 items.
-  The last two will often be ‘Search’ and ‘Menu’.
-- An icon can be added to such a menu item if it helps clarify it, e.g. for searching and for logging in and out.
-- The 'Menu' button opens a collapsible menu, which has room for more links.
-- On narrow windows, links can move from the inline menu to the collapsible one.
-- Labels should be short to help the inline menu fit on a single line whenever possible.
-- An icon can be added to the end of a link to make its destination easier to guess.
-- For websites with a brand name that feature the standard Amsterdam logo, only the emblem is shown in narrow windows.
-- An abbreviated brand name can be shown in narrow or medium-wide windows if the full name does not fit.
-- If the collapsible menu contains [Headings](https://designsystem.amsterdam/?path=/docs/components-text-heading--docs), give them level 2 and a size of ‘level-3’.
-- There’s no need to add whitespace to the Grid in the collapsible menu.
-  Its container already does this.
-
-## References
-
-- A Page Header is a [landmark](https://www.w3.org/TR/wai-aria-practices-1.1/#aria_landmark_roles) and can be used to group navigation elements.
-- [WCAG 3.2.3](https://wcag.com/designers/3-2-3-consistent-navigation/) Consistent Navigation: Navigation menus that appear on multiple pages are consistent.
+- All our websites must start with the Page Header.
+  Consistent use helps people identify, navigate, and trust our digital channels.
+- The Page Header must show the appropriate logo and brand name.
+  The navigation structure can be configured freely.
+- The Page Header is the same on every page of the website, although full-screen pages (e.g. a video or map) may hide it.
+- Continue below to the [guidelines for elements](#guidelines-for-elements).

package/src/components/page-header/page-header.scss

@@ -4,6 +4,7 @@
  */
 
 @use "../../common/breakpoint" as *;
+@use "../../common/print-exact" as *;
 @use "../../common/resets" as *;
 @use "../../common/text-rendering" as *;
 
@@ -11,19 +12,25 @@
   /*
   * The logo link section is created twice: once outside the navigation and once hidden inside it.
   * This keeps all navigation in one nav element and lets the menu wrap around the logo link section.
-  * Display grid is used to let both logo link sections overlap.
   */
-  display: grid;
+  background-color: var(--ams-page-header-background-color);
+  display: grid; /* Allows both instances of Logo Link to overlap */
   font-family: var(--ams-page-header-font-family);
   padding-block: var(--ams-page-header-padding-block);
   padding-inline: var(--ams-page-header-padding-inline);
 
-  @media screen and (min-width: $ams-breakpoint-medium) {
-    padding-inline: var(--ams-page-header-medium-padding-inline);
+  @media (min-width: $ams-breakpoint-medium) {
+    padding-inline: var(
+      --ams-page-header-medium-padding-inline /* This token is @deprecated. Will be removed on or after 2026-10-20. */,
+      var(--ams-page-header-vi-medium-padding-inline)
+    );
   }
 
-  @media screen and (min-width: $ams-breakpoint-wide) {
-    padding-inline: var(--ams-page-header-wide-padding-inline);
+  @media (min-width: $ams-breakpoint-wide) {
+    padding-inline: var(
+      --ams-page-header-wide-padding-inline /* This token is @deprecated. Will be removed on or after 2026-10-20. */,
+      var(--ams-page-header-vi-wide-padding-inline)
+    );
   }
 }
 
@@ -32,7 +39,7 @@
   align-self: start; // To align the logo link section to the top of the header when it wraps
   column-gap: var(--ams-page-header-logo-link-column-gap);
   display: flex;
-  grid-area: 1 / 1; // To allow this section to overlap with the second logo link section
+  grid-area: 1 / 1; /* Lets this visible instance of Logo Link overlap the hidden one in Navigation. */
   inline-size: fit-content;
   outline-offset: var(--ams-page-header-logo-link-outline-offset);
   text-decoration: none;
@@ -60,7 +67,7 @@
   inline-size: 0.75rem;
   overflow: hidden;
 
-  @media screen and (min-width: $ams-breakpoint-medium) {
+  @media (min-width: $ams-breakpoint-medium) {
     inline-size: auto;
   }
 }
@@ -72,23 +79,19 @@
   font-weight: var(--ams-page-header-brand-name-font-weight);
   line-height: var(--ams-page-header-brand-name-line-height);
 
-  /*
-   * If text-wrap is not supported, it is ignored.
-   * This means the wrapped text will look less balanced, which is fine.
-   */
-  /* stylelint-disable-next-line plugin/use-baseline */
+  /* stylelint-disable-next-line plugin/use-baseline -- Unbalanced line lengths in non-supporting browsers are acceptable */
   text-wrap: var(--ams-page-header-brand-name-text-wrap);
 }
 
 .ams-page-header__brand-name-short {
-  @media screen and (min-width: $ams-breakpoint-wide) {
+  @media (min-width: $ams-breakpoint-wide) {
     display: none;
   }
 
   & + .ams-page-header__brand-name {
     display: none;
 
-    @media screen and (min-width: $ams-breakpoint-wide) {
+    @media (min-width: $ams-breakpoint-wide) {
       display: initial;
     }
   }
@@ -98,7 +101,7 @@
   column-gap: var(--ams-page-header-navigation-column-gap);
   display: flex;
   flex-wrap: wrap;
-  grid-area: 1 / 1; // To allow this section to overlap with the logo link section
+  grid-area: 1 / 1; /* Makes the hidden Logo Link child overlap the visible one. */
   // This section blocks pointer events initially, so the hidden logo link section can't be activated.
   // The menu and collapsible menu set it back to auto, to make sure they can be activated.
   pointer-events: none;
@@ -120,7 +123,7 @@
 
 // Do not show menu items below the wide breakpoint...
 .ams-page-header__menu-item {
-  @media screen and (not (min-width: $ams-breakpoint-wide)) {
+  @media (not (min-width: $ams-breakpoint-wide)) {
     display: none;
   }
 }
@@ -131,6 +134,10 @@
 }
 
 @mixin page-header-menu-action {
+  color: var(
+    --ams-page-header-menu-item-color
+  ); /* This token is @deprecated. Will be removed on or after 2026-09-13. */
+
   font-size: var(--ams-page-header-menu-item-font-size);
   font-weight: var(--ams-page-header-menu-item-font-weight);
   line-height: var(--ams-page-header-menu-item-line-height);
@@ -147,6 +154,8 @@
 }
 
 .ams-page-header__menu-link {
+  @include page-header-menu-action;
+
   color: var(--ams-page-header-menu-link-color);
   display: inline-flex;
   gap: var(--ams-page-header-menu-link-gap);
@@ -154,8 +163,6 @@
   text-decoration-thickness: var(--ams-page-header-menu-link-text-decoration-thickness);
   text-underline-offset: var(--ams-page-header-menu-link-text-underline-offset);
 
-  @include page-header-menu-action;
-
   &:hover {
     text-decoration-line: var(--ams-page-header-menu-link-hover-text-decoration-line);
   }
@@ -166,13 +173,14 @@
 }
 
 .ams-page-header__mega-menu-button-item--hide-on-wide-window {
-  @media screen and (min-width: $ams-breakpoint-wide) {
+  @media (min-width: $ams-breakpoint-wide) {
     display: none;
   }
 }
 
 .ams-page-header__mega-menu-button {
   @include reset-button;
+  @include page-header-menu-action;
 
   background-color: var(--ams-page-header-mega-menu-button-background-color);
   color: var(--ams-page-header-mega-menu-button-color);
@@ -183,17 +191,23 @@
   grid-auto-flow: column;
   padding-inline: var(--ams-page-header-mega-menu-button-padding-inline);
 
-  @include page-header-menu-action;
+  @include print-exact;
 
   &:hover {
     background-color: var(--ams-page-header-mega-menu-button-hover-background-color);
     color: var(--ams-page-header-mega-menu-button-hover-color);
   }
+
+  &[aria-expanded="true"] {
+    font-weight: var(
+      --ams-page-header-mega-menu-button-label-open-font-weight
+    ); /* This token is @deprecated. Will be removed on or after 2026-09-13. */
+  }
 }
 
 .ams-page-header__mega-menu-button-label,
 .ams-page-header__mega-menu-button-hidden-label {
-  /* @deprecated These class names will be removed in 6.0.0. */
+  /* @deprecated These class names will be removed on or after 2026-09-13. */
 }
 
 .ams-page-header__menu-icon-top,
@@ -245,7 +259,7 @@
 .ams-page-header__grid-cell-narrow-window-only {
   display: initial; // Override the `hidden` attribute; this cell duplicates the non-fixed links in the Page Header Menu.
 
-  @media screen and (min-width: $ams-breakpoint-wide) {
+  @media (min-width: $ams-breakpoint-wide) {
     display: none;
   }
 }

package/src/components/pagination/pagination.scss

@@ -48,6 +48,10 @@
   }
 }
 
+.ams-pagination__link-label {
+  display: inline; // Override the default 'hidden' attribute, showing the visible label when CSS loads
+}
+
 .ams-pagination__link[aria-current="page"] {
   font-weight: var(--ams-pagination-link-current-font-weight);
 

package/src/components/paragraph/paragraph.scss

@@ -25,11 +25,7 @@
   font-size: var(--ams-paragraph-large-font-size);
   line-height: var(--ams-paragraph-large-line-height);
 
-  /*
-   * If text-wrap is not supported, it is ignored.
-   * This means the wrapped text will look less balanced, which is fine.
-   */
-  /* stylelint-disable-next-line plugin/use-baseline */
+  /* stylelint-disable-next-line plugin/use-baseline -- Unbalanced line lengths in non-supporting browsers are acceptable */
   text-wrap: var(--ams-paragraph-large-text-wrap);
 }
 

package/src/components/progress-list/README.md

@@ -6,9 +6,10 @@ Displays the progress of a sequence of steps, with optional additional details p
 
 ## Guidelines
 
-- Choose the correct level for the steps’ headings.
+- Choose the correct level for the headings of the steps.
 - Assign a status to each step: _completed_ or _current_.
   Steps without a status are considered _upcoming_.
 - Maintain a correct chronological order.
   Only one step may be _current_; preceding steps must be _completed_.
+- Decide whether the user should be able to collapse and expand steps.
 - Progress List must only be used on a white background.

package/src/components/progress-list/progress-list.scss

@@ -4,6 +4,7 @@
  */
 
 @use "../../common/breakpoint" as *;
+@use "../../common/print-exact" as *;
 @use "../../common/resets" as *;
 
 @mixin indicator {
@@ -36,8 +37,11 @@
   display: flex;
   gap: var(--ams-progress-list-step-gap);
 
-  @media screen and (min-width: $ams-breakpoint-medium) {
-    gap: var(--ams-progress-list-step-medium-gap);
+  @media (min-width: $ams-breakpoint-medium) {
+    gap: var(
+      --ams-progress-list-step-medium-gap /* This token is @deprecated. Will be removed on or after 2026-10-20. */,
+      var(--ams-progress-list-step-vi-medium-gap)
+    );
   }
 }
 
@@ -80,6 +84,7 @@
     var(--ams-progress-list-step-marker-shape-outline-style) var(--ams-progress-list-step-marker-shape-outline-color);
 
   @include marker-shape;
+  @include print-exact;
 
   .ams-progress-list__step--completed & {
     background-color: var(--ams-progress-list-step-completed-marker-shape-background-color);
@@ -127,16 +132,25 @@
   .ams-progress-list > :last-child:not(.ams-progress-list__step--has-substeps) & {
     display: none;
   }
+
+  /* Hide connector for last step when collapsed. */
+  .ams-progress-list > :last-child.ams-progress-list__step--collapsed & {
+    display: none;
+  }
 }
 
 /* Content */
 
 .ams-progress-list__content {
   flex: auto;
-  min-inline-size: 0; /* Ensure content can shrink to fit container */
-
-  /* Add white space below all but the last step and steps with substeps. */
-  .ams-progress-list__step:not(:last-child, .ams-progress-list__step--has-substeps) & {
+  min-inline-size: 0;
+
+  /* Add space below content, unless it is the last child, or if it has substeps and it is not collapsed. */
+  .ams-progress-list__step:not(
+      :last-child,
+      .ams-progress-list__step--has-substeps:not(.ams-progress-list__step--collapsed)
+    )
+    & {
     margin-block-end: var(--ams-progress-list-step-content-margin-block-end);
   }
 }
@@ -145,9 +159,66 @@
 
 .ams-progress-list__heading {
   margin-block-end: var(--ams-progress-list-step-heading-margin-block-end);
+
+  .ams-progress-list__step--collapsed & {
+    margin-block-end: 0;
+  }
 }
 
-/* Substeps is its own block in BEM and has the same elements as above */
+/* Button */
+
+.ams-progress-list__button {
+  @include reset-button;
+
+  background-color: transparent;
+  color: var(--ams-progress-list-button-color);
+  cursor: var(--ams-progress-list-button-cursor);
+  display: flex;
+  font-family: inherit;
+  font-size: inherit;
+  font-weight: inherit;
+  gap: var(--ams-progress-list-button-gap);
+  inline-size: 100%;
+  line-height: inherit;
+  outline-offset: var(--ams-progress-list-button-outline-offset);
+  padding-block: var(--ams-progress-list-button-padding-block);
+  padding-inline: var(--ams-progress-list-button-padding-inline);
+  text-align: start;
+
+  &:hover {
+    color: var(--ams-progress-list-button-hover-color);
+  }
+}
+
+/* Icon */
+
+.ams-progress-list__icon svg {
+  rotate: 0deg;
+  transition: none;
+
+  [aria-expanded="true"] & {
+    rotate: -180deg;
+  }
+
+  @media (prefers-reduced-motion: no-preference) {
+    transition: rotate var(--ams-progress-list-icon-transition-duration)
+      var(--ams-progress-list-icon-transition-timing-function);
+  }
+}
+
+/* Panel */
+
+.ams-progress-list__panel {
+  .ams-progress-list__step--collapsed & {
+    display: none;
+
+    @media print {
+      display: block;
+    }
+  }
+}
+
+/* Substeps – is its own block in BEM and has the same elements as above */
 
 .ams-progress-list-substeps {
   @include reset-ol;
@@ -170,10 +241,18 @@
 
   @include indicator;
 
-  @media screen and (min-width: $ams-breakpoint-medium) {
-    margin-inline-end: var(--ams-progress-list-substeps-step-indicator-medium-margin-inline-end);
+  @media (min-width: $ams-breakpoint-medium) {
+    margin-inline-end: var(
+      --ams-progress-list-substeps-step-indicator-medium-margin-inline-end
+        /* This token is @deprecated. Will be removed on or after 2026-10-20. */,
+      var(--ams-progress-list-substeps-step-indicator-vi-medium-margin-inline-end)
+    );
     margin-inline-start: calc(
-      -1 * var(--ams-progress-list-step-medium-gap) - var(--ams-progress-list-step-marker-shape-block-size)
+      -1 *
+        var(
+          --ams-progress-list-step-medium-gap /* This token is @deprecated. Will be removed on or after 2026-10-20. */,
+          var(--ams-progress-list-step-vi-medium-gap)
+        ) - var(--ams-progress-list-step-marker-shape-block-size)
     );
   }
 }
@@ -199,6 +278,7 @@
     var(--ams-progress-list-substeps-step-marker-shape-outline-color);
 
   @include marker-shape;
+  @include print-exact;
 
   .ams-progress-list-substeps__step--completed & {
     background-color: var(--ams-progress-list-substeps-step-completed-marker-shape-background-color);

package/src/components/prose/README.md

@@ -0,0 +1,15 @@
+<!-- @license CC0-1.0 -->
+
+# Prose
+
+Applies the recommended vertical spacing between the direct children of a container, so editorial content flows without hand-picked margins.
+
+## Class name
+
+`ams-prose`
+
+## Guidelines
+
+- Wrap this utility class around editorial content to space its content according to the [Vertical space](/docs/docs-designer-guide-vertical-space--docs) recommendations.
+- To add a single ad-hoc gap between two elements, prefer the [Margin Bottom](/docs/utilities-css-margin--docs) utility class on the first one.
+- To add even spacing between a set of siblings, prefer the [Gap](/docs/utilities-css-gap--docs) utility class on their parent.