@amsterdam/design-system-css 0.14.1 → 0.15.0

package/src/components/field-set/field-set.scss

@@ -7,7 +7,7 @@
 @use "../../common/text-rendering" as *;
 
 @mixin reset-fieldset {
-  border: 0;
+  border: none;
   margin-inline: 0;
   padding-block: 0;
   padding-inline: 0;

package/src/components/figure/figure.scss

@@ -3,6 +3,7 @@
  * Copyright Gemeente Amsterdam
  */
 
+@use "../../common/hyphenation" as *;
 @use "../../common/text-rendering" as *;
 
 @mixin reset-figure {
@@ -25,9 +26,10 @@
   font-weight: var(--ams-figure-caption-font-weight);
   line-height: var(--ams-figure-caption-line-height);
 
+  @include hyphenation;
   @include text-rendering;
 }
 
-.ams-figure__caption--inverse-color {
+.ams-figure__caption--inverse {
   color: var(--ams-figure-caption-inverse-color);
 }

package/src/components/file-input/file-input.scss

@@ -6,7 +6,7 @@
 @use "../../common/text-rendering" as *;
 
 @mixin reset-button {
-  border: 0;
+  border: none;
   border-radius: 0; // Reset rounded borders on iOS devices
 }
 
@@ -21,7 +21,7 @@
   font-weight: var(--ams-file-input-font-weight);
   inline-size: 100%;
   line-height: var(--ams-file-input-line-height);
-  outline-offset: calc(var(--ams-focus-outline-offset) * 2); // Compensate for the dashed border
+  outline-offset: var(--ams-file-input-outline-offset);
   padding-block: var(--ams-file-input-padding-block);
   padding-inline: var(--ams-file-input-padding-inline);
   touch-action: manipulation;

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

@@ -3,6 +3,7 @@
  * Copyright Gemeente Amsterdam
  */
 
+@use "../../common/hyphenation" as *;
 @use "../../common/text-rendering" as *;
 
 @mixin reset-ul {
@@ -17,13 +18,13 @@
   gap: var(--ams-file-list-gap);
   padding-block: var(--ams-file-list-padding-block);
 
+  @include hyphenation;
   @include text-rendering;
   @include reset-ul;
 }
 
 .ams-file-list__item {
   display: flex;
-  flex-direction: row;
   font-family: var(--ams-file-list-file-font-family);
   font-size: var(--ams-file-list-file-font-size);
   font-weight: var(--ams-file-list-file-font-weight);

package/src/components/footer/README.md

@@ -6,8 +6,9 @@ Provides service information at the bottom of every page.
 
 ## Guidelines
 
-- The Footer usually consists of two sections: a full-width blue area and a [Page Menu](/docs/components-navigation-page-menu--docs) below it.
-- A Footer containing only a Page Menu can be sufficient for applications.
+- The Footer usually consists of two sections: a full-width blue area and a `Footer.Menu` below it.
+- Both sections are preceded by a visually hidden `Heading` for accessibility.
+- A Footer containing only a `Footer.Menu` can be sufficient for applications.
 - The Footer must be used on all websites for the City of Amsterdam.
 - It must be the same on every page.
 

package/src/components/footer/footer.scss

@@ -3,6 +3,45 @@
  * Copyright Gemeente Amsterdam
  */
 
-.ams-footer__top {
-  background-color: var(--ams-footer-top-background-color);
+@use "../../common/hyphenation" as *;
+@use "../../common/text-rendering" as *;
+
+@mixin reset-ul {
+  list-style: none;
+  margin-block: 0;
+}
+
+.ams-footer__spotlight {
+  background-color: var(--ams-footer-spotlight-background-color);
+}
+
+.ams-footer__menu {
+  column-gap: var(--ams-footer-menu-column-gap);
+  display: flex;
+  flex-wrap: wrap;
+  padding-block: var(--ams-footer-menu-padding-block);
+  padding-inline: var(--ams-footer-menu-padding-inline);
+  row-gap: var(--ams-footer-menu-row-gap);
+
+  @include reset-ul;
+}
+
+.ams-footer__menu-link {
+  color: var(--ams-footer-menu-link-color);
+  font-family: var(--ams-footer-menu-link-font-family);
+  font-size: var(--ams-footer-menu-link-font-size);
+  font-weight: var(--ams-footer-menu-link-font-weight);
+  line-height: var(--ams-footer-menu-link-line-height);
+  outline-offset: var(--ams-footer-menu-link-outline-offset);
+  text-decoration-line: var(--ams-footer-menu-link-text-decoration-line);
+  text-decoration-thickness: var(--ams-footer-menu-link-text-decoration-thickness);
+  text-underline-offset: var(--ams-footer-menu-link-text-underline-offset);
+
+  @include hyphenation;
+  @include text-rendering;
+
+  &:hover {
+    color: var(--ams-footer-menu-link-hover-color);
+    text-decoration-line: var(--ams-footer-menu-link-hover-text-decoration-line);
+  }
 }

package/src/components/gap/README.md

@@ -6,15 +6,19 @@ Adds white space between a set of elements.
 
 ## Class names
 
-The five sizes of [Component Space](/docs/brand-design-tokens-space--docs) are available for the width or height of the gap.
-
-| Class name    | Example                                                                                   |
-| ------------- | ----------------------------------------------------------------------------------------- |
-| `ams-gap--xs` | <div className="ams-docs-token-example--space" style="inline-size: var(--ams-gap-xs);" /> |
-| `ams-gap--sm` | <div className="ams-docs-token-example--space" style="inline-size: var(--ams-gap-sm);" /> |
-| `ams-gap--md` | <div className="ams-docs-token-example--space" style="inline-size: var(--ams-gap-md);" /> |
-| `ams-gap--lg` | <div className="ams-docs-token-example--space" style="inline-size: var(--ams-gap-lg);" /> |
-| `ams-gap--xl` | <div className="ams-docs-token-example--space" style="inline-size: var(--ams-gap-xl);" /> |
+Five options are available for the width or height of the gap:
+
+- `ams-gap-xs`
+- `ams-gap-s`
+- `ams-gap-m`
+- `ams-gap-l`
+- `ams-gap-xl`
+
+Because spacing is responsive, the gaps are as well.
+They are also smaller in Compact Mode.
+Consult the [Space](/docs/brand-design-tokens-space--docs) docs for an indication of their sizes.
+
+The `2xl` space is intended for whitespace around a [Grid](/docs/components-layout-grid--docs) only, which can be produced through a `padding*` of `large`.
 
 ## Guidelines
 

package/src/components/gap/gap.scss

@@ -3,17 +3,13 @@
  * Copyright Gemeente Amsterdam
  */
 
-@use "sass:map";
-@use "../../common/size" as *;
-
-[class|="ams-gap-"] {
-  display: grid !important;
-}
-
-@each $size in map.keys($ams-sizes) {
-  @if $size != "no" {
-    .ams-gap--#{$size} {
-      grid-gap: var(--ams-gap-#{$size}) !important;
-    }
+// If you modify this list, you must also update the object in
+// packages/react/src/common/shortSize.ts
+// Note that we don’t offer a 2xl gap on purpose.
+@each $size in ("xs", "s", "m", "l", "xl") {
+  .ams-gap-#{$size} {
+    display: grid !important;
+    /* stylelint-disable-next-line csstools/value-no-unknown-custom-properties */
+    gap: var(--ams-space-#{$size}) !important;
   }
 }

package/src/components/grid/_mixins.scss

@@ -10,14 +10,16 @@
   display: grid;
   grid-template-columns: repeat(var(--ams-grid-column-count), 1fr);
   padding-inline: var(--ams-grid-padding-inline);
-  row-gap: var(--ams-grid-row-gap-md);
+  row-gap: var(--ams-grid-row-gap-m);
 
   @media screen and (min-width: $ams-breakpoint-medium) {
     grid-template-columns: repeat(var(--ams-grid-medium-column-count), 1fr);
+    padding-inline: var(--ams-grid-medium-padding-inline);
   }
 
   @media screen and (min-width: $ams-breakpoint-wide) {
     grid-template-columns: repeat(var(--ams-grid-wide-column-count), 1fr);
+    padding-inline: var(--ams-grid-wide-padding-inline);
   }
 }
 
@@ -28,49 +30,49 @@
 }
 
 @mixin ams-grid--gap-vertical--small {
-  row-gap: var(--ams-grid-row-gap-sm);
+  row-gap: var(--ams-grid-row-gap-s);
 }
 
 @mixin ams-grid--gap-vertical--large {
-  row-gap: var(--ams-grid-row-gap-lg);
+  row-gap: var(--ams-grid-row-gap-l);
 }
 
 // Grid padding
 
 @mixin ams-grid--padding-bottom--small {
-  padding-block-end: var(--ams-grid-padding-block-sm);
+  padding-block-end: var(--ams-grid-padding-block-s);
 }
 
 @mixin ams-grid--padding-bottom--medium {
-  padding-block-end: var(--ams-grid-padding-block-md);
+  padding-block-end: var(--ams-grid-padding-block-m);
 }
 
 @mixin ams-grid--padding-bottom--large {
-  padding-block-end: var(--ams-grid-padding-block-lg);
+  padding-block-end: var(--ams-grid-padding-block-l);
 }
 
 @mixin ams-grid--padding-top--small {
-  padding-block-start: var(--ams-grid-padding-block-sm);
+  padding-block-start: var(--ams-grid-padding-block-s);
 }
 
 @mixin ams-grid--padding-top--medium {
-  padding-block-start: var(--ams-grid-padding-block-md);
+  padding-block-start: var(--ams-grid-padding-block-m);
 }
 
 @mixin ams-grid--padding-top--large {
-  padding-block-start: var(--ams-grid-padding-block-lg);
+  padding-block-start: var(--ams-grid-padding-block-l);
 }
 
 @mixin ams-grid--padding-vertical--small {
-  padding-block: var(--ams-grid-padding-block-sm);
+  padding-block: var(--ams-grid-padding-block-s);
 }
 
 @mixin ams-grid--padding-vertical--medium {
-  padding-block: var(--ams-grid-padding-block-md);
+  padding-block: var(--ams-grid-padding-block-m);
 }
 
 @mixin ams-grid--padding-vertical--large {
-  padding-block: var(--ams-grid-padding-block-lg);
+  padding-block: var(--ams-grid-padding-block-l);
 }
 
 @mixin ams-grid__cell--span-all {

package/src/components/header/README.md

@@ -18,6 +18,7 @@ Includes the name of the application if it is not the general website.
 - 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 on narrow screens.
 
 ## References
 

package/src/components/header/header.scss

@@ -8,34 +8,46 @@
 
 .ams-header {
   /*
-  * The branding 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 branding section.
-  * Display grid is used to let both branding sections overlap.
+  * 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;
+  font-family: var(--ams-header-font-family);
   padding-block: var(--ams-header-padding-block);
   padding-inline: var(--ams-header-padding-inline);
 }
 
-.ams-header__branding {
+.ams-header__logo-link {
   align-items: center;
-  align-self: start; // To align the branding section to the top of the header when it wraps
-  column-gap: var(--ams-header-branding-column-gap);
+  align-self: start; // To align the logo link section to the top of the header when it wraps
+  column-gap: var(--ams-header-logo-link-column-gap);
   display: flex;
-  grid-area: 1 / 1; // To allow this section to overlap with the second branding section
+  grid-area: 1 / 1; // To allow this section to overlap with the second logo link section
+  inline-size: fit-content;
+  outline-offset: var(--ams-header-logo-link-outline-offset);
+  text-decoration: none;
 }
 
-.ams-header__branding--hidden {
+.ams-header__logo-link--hidden {
   opacity: 0%;
-  user-select: none; // The hidden branding section should not be selectable
+  user-select: none; // The hidden logo link section should not be selectable
 }
 
-.ams-header__logo-link {
-  outline-offset: var(--ams-header-logo-link-outline-offset);
+.ams-header__logo-container {
+  flex-shrink: 0;
+  inline-size: 0.75rem;
+  overflow: hidden;
+
+  @media screen and (min-width: $ams-breakpoint-medium) {
+    inline-size: auto;
+  }
 }
 
-/* TODO Remove after updating Heading line heights in DES-973. */
-.ams-heading.ams-header__brand-name {
+.ams-header__brand-name {
+  color: var(--ams-header-brand-name-color);
+  font-size: var(--ams-header-brand-name-font-size);
+  font-weight: var(--ams-header-brand-name-font-weight);
   line-height: 1.35;
 }
 
@@ -43,8 +55,8 @@
   column-gap: var(--ams-header-navigation-column-gap);
   display: flex;
   flex-wrap: wrap;
-  grid-area: 1 / 1; // To allow this section to overlap with the branding section
-  // This section blocks pointer events initially, so the hidden branding section can't be activated.
+  grid-area: 1 / 1; // To allow this section to overlap with the logo link section
+  // 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;
   row-gap: var(--ams-header-navigation-row-gap);
@@ -83,7 +95,6 @@
 
 @mixin header-menu-action {
   color: var(--ams-header-menu-item-color);
-  font-family: var(--ams-header-menu-item-font-family);
   font-size: var(--ams-header-menu-item-font-size);
   font-weight: var(--ams-header-menu-item-font-weight);
   line-height: var(--ams-header-menu-item-line-height);
@@ -120,7 +131,7 @@
 
 @mixin reset-button {
   background: none;
-  border: 0;
+  border: none;
   margin-block: 0; // [1]
   margin-inline: 0; // [1]
   padding-inline: 0;
@@ -130,8 +141,9 @@
 
 .ams-header__mega-menu-button {
   column-gap: var(--ams-header-menu-item-column-gap);
-  cursor: pointer;
+  cursor: var(--ams-header-mega-menu-button-cursor);
   display: grid;
+  font-family: inherit;
   grid-auto-flow: column;
 
   @include header-menu-action;

package/src/components/heading/README.md

@@ -2,16 +2,16 @@
 
 # Heading
 
-Describes the content that follows it.
-Use Headings to allow the user to grasp the structure of the page quickly.
+Introduces a page section and describes the following content.
 
 ## Guidelines
 
-- A heading describes the content beneath it.
-- Every page should contain one Heading with level 1.
-- Do not skip heading levels, e.g. a level 2 Heading should be followed by one with level 3, not level 4.
-- Do not use a Heading for formatting and styling, but to represent the page’s structure.
-  Users of screen readers use headings to navigate the page – an incorrect hierarchy can confuse them.
+- Use Headings to allow the user to quickly grasp the structure of the page.
+- All headings together represent the document’s structure. Users of screen readers may use headings to navigate the page – an incorrect hierarchy will confuse them.
+- Every page should contain one heading with level 1.
+  Do not skip heading levels, e.g. a level 2 Heading should be followed by one with level 3, not level 4.
+  The `level` prop doesn’t have a default value; the correct level should be determined for each instance.
+- Don’t use a Heading just for its visual appearance.
 
 ## Relevant WCAG requirements
 

package/src/components/heading/heading.scss

@@ -23,36 +23,36 @@
   @include reset-hx;
 }
 
-.ams-heading--level-1 {
-  font-size: var(--ams-heading-level-1-font-size);
-  line-height: var(--ams-heading-level-1-line-height);
+.ams-heading--1 {
+  font-size: var(--ams-heading-1-font-size);
+  line-height: var(--ams-heading-1-line-height);
 }
 
-.ams-heading--level-2 {
-  font-size: var(--ams-heading-level-2-font-size);
-  line-height: var(--ams-heading-level-2-line-height);
+.ams-heading--2 {
+  font-size: var(--ams-heading-2-font-size);
+  line-height: var(--ams-heading-2-line-height);
 }
 
-.ams-heading--level-3 {
-  font-size: var(--ams-heading-level-3-font-size);
-  line-height: var(--ams-heading-level-3-line-height);
+.ams-heading--3 {
+  font-size: var(--ams-heading-3-font-size);
+  line-height: var(--ams-heading-3-line-height);
 }
 
-.ams-heading--level-4 {
-  font-size: var(--ams-heading-level-4-font-size);
-  line-height: var(--ams-heading-level-4-line-height);
+.ams-heading--4 {
+  font-size: var(--ams-heading-4-font-size);
+  line-height: var(--ams-heading-4-line-height);
 }
 
-.ams-heading--level-5 {
-  font-size: var(--ams-heading-level-5-font-size);
-  line-height: var(--ams-heading-level-5-line-height);
+.ams-heading--5 {
+  font-size: var(--ams-heading-5-font-size);
+  line-height: var(--ams-heading-5-line-height);
 }
 
-.ams-heading--level-6 {
-  font-size: var(--ams-heading-level-6-font-size);
-  line-height: var(--ams-heading-level-6-line-height);
+.ams-heading--6 {
+  font-size: var(--ams-heading-6-font-size);
+  line-height: var(--ams-heading-6-line-height);
 }
 
-.ams-heading--inverse-color {
+.ams-heading--inverse {
   color: var(--ams-heading-inverse-color);
 }

package/src/components/icon/README.md

@@ -12,10 +12,10 @@ Use an icon to support textual interactive elements like buttons and links.
 Always try to provide accompanying text for an icon.
 Only use icons without accompanying text if they adhere to international standards, such as menu (hamburger icon), search (magnifying glass), next, previous, play, pause, etc.
 
-## Color
+## Colour
 
 Icons are black or white.
-When used as part of an interactive element, they are dark blue.
+When used as part of an interactive element, they are blue.
 When disabled, they are grey.
 They must adhere to the same contrast ratio for accessibility as typography against a background colour.
 The icon defaults to the colour of the container it is in.
@@ -26,9 +26,9 @@ Icons are aligned to the left of the text by default and vertically centred to t
 
 ## Size
 
-Icons use the same text levels as all typographic components to determine their size.
-This ensures easy alignment between icons and text.
-[Refer to the typography documentation for more information](/docs/brand-design-tokens-text--docs).
+Icons have extra whitespace at their top and bottom to match the line height of text components.
+Specify the appropriate size to pair an icon with small or large body text or with a heading.
+[Read more in the typography documentation](/docs/brand-design-tokens-typography--docs).
 
 ## Overview
 

package/src/components/icon/icon.scss

@@ -4,55 +4,68 @@
  */
 
 .ams-icon {
-  align-items: center;
-  display: inline-flex;
-}
+  --ams-line-height: var(--ams-icon-line-height);
+
+  align-self: baseline; // Aligns the icon with text in flex or grid context
+  display: inline-flex; // Stretches the svg in order to align the icon vertically
+  font-size: var(--ams-icon-font-size);
+  line-height: var(--ams-line-height);
+
+  &::after {
+    content: "\00200B"; // This zero width space enables baseline alignment.
+  }
 
-.ams-icon svg {
-  fill: currentColor;
+  svg {
+    fill: currentColor;
+    inline-size: 1em;
+  }
 }
 
-.ams-icon--inverse-color {
+.ams-icon--inverse {
   color: var(--ams-icon-inverse-color);
 }
 
 .ams-icon--square {
-  aspect-ratio: 1 / 1;
+  inline-size: calc(1em * var(--ams-line-height));
   justify-content: center;
 }
 
-.ams-icon--size-3 {
-  block-size: calc(var(--ams-icon-size-3-font-size) * var(--ams-icon-size-3-line-height));
-}
+.ams-icon--small {
+  --ams-line-height: var(--ams-icon-small-line-height);
 
-.ams-icon--size-3 svg {
-  block-size: var(--ams-icon-size-3-font-size);
-  inline-size: var(--ams-icon-size-3-font-size);
+  font-size: var(--ams-icon-small-font-size);
 }
 
-.ams-icon--size-4 {
-  block-size: calc(var(--ams-icon-size-4-font-size) * var(--ams-icon-size-4-line-height));
-}
+.ams-icon--large {
+  --ams-line-height: var(--ams-icon-large-line-height);
 
-.ams-icon--size-4 svg {
-  block-size: var(--ams-icon-size-4-font-size);
-  inline-size: var(--ams-icon-size-4-font-size);
+  font-size: var(--ams-icon-large-font-size);
 }
 
-.ams-icon--size-5 {
-  block-size: calc(var(--ams-icon-size-5-font-size) * var(--ams-icon-size-5-line-height));
+.ams-icon--heading-3 {
+  --ams-line-height: var(--ams-icon-heading-3-line-height);
+
+  font-size: var(--ams-icon-heading-3-font-size);
+  line-height: var(--ams-icon-heading-3-line-height);
 }
 
-.ams-icon--size-5 svg {
-  block-size: var(--ams-icon-size-5-font-size);
-  inline-size: var(--ams-icon-size-5-font-size);
+.ams-icon--heading-4 {
+  --ams-line-height: var(--ams-icon-heading-4-line-height);
+
+  font-size: var(--ams-icon-heading-4-font-size);
+  line-height: var(--ams-icon-heading-4-line-height);
 }
 
-.ams-icon--size-6 {
-  block-size: calc(var(--ams-icon-size-6-font-size) * var(--ams-icon-size-6-line-height));
+.ams-icon--heading-5 {
+  --ams-line-height: var(--ams-icon-heading-5-line-height);
+
+  font-size: var(--ams-icon-heading-5-font-size);
+  line-height: var(--ams-icon-heading-5-line-height);
 }
 
-.ams-icon--size-6 svg {
-  block-size: var(--ams-icon-size-6-font-size);
-  inline-size: var(--ams-icon-size-6-font-size);
+.ams-icon--heading-6 {
+  --ams-line-height: var(--ams-icon-heading-6-line-height);
+
+  font-size: var(--ams-icon-heading-6-font-size);
+  line-height: var(--ams-icon-heading-6-line-height);
 }

package/src/components/icon-button/icon-button.scss

@@ -4,7 +4,7 @@
  */
 
 @mixin reset-button {
-  border: 0;
+  border: none;
   margin-block: 0; // [1]
   margin-inline: 0; // [1]
   padding-block: 0;
@@ -16,7 +16,8 @@
 .ams-icon-button {
   background-color: transparent;
   color: var(--ams-icon-button-color);
-  cursor: pointer;
+  cursor: var(--ams-icon-button-cursor);
+  display: inline-flex;
   outline-offset: var(--ams-icon-button-outline-offset);
   touch-action: manipulation;
 
@@ -30,35 +31,35 @@
   &:disabled {
     background-color: transparent;
     color: var(--ams-icon-button-disabled-color);
-    cursor: not-allowed;
+    cursor: var(--ams-icon-button-disabled-cursor);
   }
 }
 
-.ams-icon-button--contrast-color {
-  color: var(--ams-icon-button-contrast-color-color);
+.ams-icon-button--contrast {
+  color: var(--ams-icon-button-contrast-color);
 
   &:hover {
-    background-color: var(--ams-icon-button-contrast-color-hover-background-color);
-    color: var(--ams-icon-button-contrast-color-hover-color);
+    background-color: var(--ams-icon-button-contrast-hover-background-color);
+    color: var(--ams-icon-button-contrast-hover-color);
   }
 
   &:disabled {
     background-color: transparent;
-    color: var(--ams-icon-button-contrast-color-disabled-color);
+    color: var(--ams-icon-button-contrast-disabled-color);
   }
 }
 
-.ams-icon-button--inverse-color {
-  background-color: var(--ams-icon-button-inverse-color-background-color);
-  color: var(--ams-icon-button-inverse-color-color);
+.ams-icon-button--inverse {
+  background-color: var(--ams-icon-button-inverse-background-color);
+  color: var(--ams-icon-button-inverse-color);
 
   &:hover {
-    background-color: var(--ams-icon-button-inverse-color-hover-background-color);
-    color: var(--ams-icon-button-inverse-color-hover-color);
+    background-color: var(--ams-icon-button-inverse-hover-background-color);
+    color: var(--ams-icon-button-inverse-hover-color);
   }
 
   &:disabled {
-    background-color: var(--ams-icon-button-inverse-color-disabled-background-color);
-    color: var(--ams-icon-button-inverse-color-disabled-color);
+    background-color: var(--ams-icon-button-inverse-disabled-background-color);
+    color: var(--ams-icon-button-inverse-disabled-color);
   }
 }