@amsterdam/design-system-css 0.11.1 → 0.13.0

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

@@ -13,19 +13,33 @@
 
 .ams-description-list {
   color: var(--ams-description-list-color);
+  column-gap: var(--ams-description-list-column-gap);
   display: grid;
   font-family: var(--ams-description-list-font-family);
   font-size: var(--ams-description-list-font-size);
-  font-weight: var(--ams-description-list-font-weight);
-  gap: var(--ams-description-list-gap);
   line-height: var(--ams-description-list-line-height);
+  row-gap: var(--ams-description-list-row-gap);
 
-  @media screen and (min-width: $ams-breakpoint-medium) {
+  @include reset;
+  @include text-rendering;
+}
+
+@media screen and (min-width: $ams-breakpoint-medium) {
+  .ams-description-list {
+    grid-template-columns: auto 1fr;
+  }
+
+  .ams-description-list--terms-width-sm {
+    grid-template-columns: 1fr 4fr;
+  }
+
+  .ams-description-list--terms-width-md {
     grid-template-columns: 1fr 2fr;
   }
 
-  @include reset;
-  @include text-rendering;
+  .ams-description-list--terms-width-lg {
+    grid-template-columns: 1fr 1fr;
+  }
 }
 
 .ams-description-list--inverse-color {
@@ -33,23 +47,25 @@
 }
 
 .ams-description-list__term {
+  font-weight: var(--ams-description-list-term-font-weight);
+
   @media screen and (min-width: $ams-breakpoint-medium) {
     grid-column-start: 1;
   }
 }
 
-@mixin reset-details {
+@mixin reset-description {
   margin-inline: 0;
 }
 
-.ams-description-list__details {
-  font-weight: var(--ams-description-list-details-font-weight);
-  padding-inline-start: var(--ams-description-list-details-padding-inline-start);
+.ams-description-list__description {
+  font-weight: var(--ams-description-list-description-font-weight);
+  padding-inline-start: var(--ams-description-list-description-padding-inline-start);
+
+  @include reset-description;
 
   @media screen and (min-width: $ams-breakpoint-medium) {
     grid-column-start: 2;
     padding-inline-start: 0;
   }
-
-  @include reset-details;
 }

package/src/components/dialog/README.md

@@ -9,13 +9,7 @@ A Dialog allows the user to focus on one task or a piece of information by poppi
 - Use dialogs sparingly because they interrupt the user’s workflow.
 - Use a dialog for short and non-frequent tasks.
   Consider using the main flow for regular tasks.
-
-## The order of buttons
-
-If your Dialog needs more than one button, put the one for the primary action first and the other buttons behind it.
-Sighted users will read the primary action first, in line with the natural reading order.
-The same goes for users of screen readers, who will hear the primary action first, and users of a keyboard, who will focus the primary action first.
-Also, this approach keeps the order of buttons consistent on both narrow and wide screens: if the buttons do not fit next to each other, they get stacked vertically with the primary action on top.
+- Wrap multiple buttons in an [Action Group](https://designsystem.amsterdam/?path=/docs/components-buttons-action-group--docs).
 
 ## Keyboard support
 
@@ -27,8 +21,7 @@ Also, this approach keeps the order of buttons consistent on both narrow and wid
 
 ## Closing Dialog without submit
 
-You can close a Dialog without submitting by using `<button type="button" onClick={closeDialog}>`.
-This uses the `closeDialog` function from the React package.
+You can close a Dialog without submitting by using `<button type="button" onClick={Dialog.close}>`.
 
 ## References
 

package/src/components/dialog/dialog.scss

@@ -4,41 +4,32 @@
  */
 
 @mixin reset-dialog {
+  box-sizing: border-box;
   inset-block: 0;
-  padding-block: 0;
-  padding-inline: 0;
 }
 
-.ams-dialog {
+/* A dialog must have `display: none` until the `open` attribute is set,
+so do not apply these styles without an `open` attribute. */
+.ams-dialog:not(dialog:not([open])) {
   background-color: var(--ams-dialog-background-color);
   border: var(--ams-dialog-border);
+  display: flex; // Using flex here, because grid works strangely in Safari
+  flex-direction: column;
+  gap: var(--ams-dialog-gap);
   inline-size: var(--ams-dialog-inline-size);
   max-block-size: var(--ams-dialog-max-block-size);
   max-inline-size: var(--ams-dialog-max-inline-size);
+  padding-block: var(--ams-dialog-padding-block);
+  padding-inline: var(--ams-dialog-padding-inline);
 
   @include reset-dialog;
 
-  /* no token because dialog does not inherit from any element */
+  /* No token because dialog does not inherit from any element in FireFox and Safari */
   &::backdrop {
     background: #0006;
   }
 }
 
-.ams-dialog__form {
-  display: grid;
-  gap: var(--ams-dialog-form-gap);
-  padding-block: var(--ams-dialog-form-padding-block);
-  padding-inline: var(--ams-dialog-form-padding-inline);
-}
-
-.ams-dialog__article {
-  display: grid;
-  gap: var(--ams-space-md); /* Until we have a consistent way of spacing text elements */
-  max-block-size: 100%; /* Safari */
-  overflow-y: auto;
-  overscroll-behavior-y: contain;
-}
-
 .ams-dialog__header {
   align-items: flex-start;
   display: flex;
@@ -46,15 +37,7 @@
   justify-content: space-between;
 }
 
-.ams-dialog__footer {
-  display: flex;
-  flex-wrap: wrap; // [1]
-  gap: var(--ams-dialog-footer-gap);
-  margin-inline-end: auto; // [1]
-
-  > * {
-    flex: auto; // [1]
-  }
+.ams-dialog__body {
+  overflow-y: auto;
+  overscroll-behavior-y: contain;
 }
-
-// [1] This combination stacks the buttons vertically and stretches them, until they fit next to each other.

package/src/components/field/README.md

@@ -6,4 +6,4 @@ Wraps a single input and its related elements. May indicate that the input has a
 
 ## Guidelines
 
-Only use Field to wrap a single input. Use [Field Set](/docs/components-forms-field-set--docs) to wrap multiple inputs.
+- Only use Field to wrap a single input. Use [Field Set](/docs/components-forms-field-set--docs) to wrap multiple inputs.

package/src/components/field/field.scss

@@ -4,6 +4,7 @@
  */
 
 .ams-field {
+  align-items: start;
   break-inside: avoid;
   display: flex;
   flex-direction: column;

package/src/components/field-set/README.md

@@ -7,6 +7,8 @@ A component to group related form inputs.
 ## Guidelines
 
 - Use Field Set when you need to show a relationship between multiple form inputs. For example, you may need to group a set of text inputs into a single Field Set when asking for an address.
+- Set `optional` to `true` if all inputs in a Field Set are not required.
+- Use `hint` to show a custom hint text.
 
 ## Relevant WCAG requirements
 

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

@@ -48,13 +48,13 @@
   padding-block: var(--ams-file-input-file-selector-button-padding-block);
   padding-inline: var(--ams-file-input-file-selector-button-padding-inline);
 
+  @include reset-button;
+
   @media screen and (-ms-high-contrast: active), screen and (forced-colors: active) {
     border: var(
       --ams-file-input-file-selector-button-forced-color-mode-border
     ); // add border because forced colors changes box-shadow to none
   }
-
-  @include reset-button;
 }
 
 .ams-file-input:disabled::file-selector-button {

package/src/components/footer/README.md

@@ -6,10 +6,10 @@ Provides service information at the bottom of every page.
 
 ## Guidelines
 
-The Footer consists of a dark blue [Spotlight](/docs/components-containers-spotlight--docs) and a [Page Menu](/docs/components-navigation-page-menu--docs).
-It must be used on all websites for the City of Amsterdam.
-For applications, only the Page Menu can be sufficient.
-The Footer is the same on every page of the application.
+- The Footer consists of a dark blue [Spotlight](/docs/components-containers-spotlight--docs) and a [Page Menu](/docs/components-navigation-page-menu--docs).
+  It must be used on all websites for the City of Amsterdam.
+- For applications, only the Page Menu can be sufficient.
+- The Footer is the same on every page of the application.
 
 The Spotlight offers space for various practical links:
 

package/src/components/gap/README.md

@@ -8,18 +8,20 @@ Adds white space between a set of elements.
 
 The five sizes of [Component Space](/docs/brand-design-tokens-space--docs) are available for the width or height of the gap.
 
-| Class name    | Preview                                                                                   |
+| Class name    | Example                                                                                   |
 | ------------- | ----------------------------------------------------------------------------------------- |
-| `ams-gap--xs` | <div className="ams-docs-token-preview--space" style="inline-size: var(--ams-gap-xs);" /> |
-| `ams-gap--sm` | <div className="ams-docs-token-preview--space" style="inline-size: var(--ams-gap-sm);" /> |
-| `ams-gap--md` | <div className="ams-docs-token-preview--space" style="inline-size: var(--ams-gap-md);" /> |
-| `ams-gap--lg` | <div className="ams-docs-token-preview--space" style="inline-size: var(--ams-gap-lg);" /> |
-| `ams-gap--xl` | <div className="ams-docs-token-preview--space" style="inline-size: var(--ams-gap-xl);" /> |
+| `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);" /> |
 
 ## Guidelines
 
 - Use this utility class to vertically separate the children of a parent element from each other.
-- It can be used on any element and sets the `gap` CSS property.
+- Do not use it on the Grid component.
+  Grid is responsible for its own gaps.
+- It can be used on any other element and sets the `gap` CSS property.
   It also makes the element a grid container; the gap would be ignored otherwise.
   These declarations are marked with the `!important` flag to ensure they override any other gaps and display modes.
 - To add a gap between 2 siblings, the first one can be given a [Margin Bottom](/docs/utilities-css-margin--docs) instead.

package/src/components/grid/README.md

@@ -4,18 +4,17 @@
 
 Divides the screen into columns to align the elements of a page.
 
-## Usage
-
-Every page should use the grid as the foundation for its layout.
-It is placed directly within the [Screen](/docs/components-layout-screen--docs).
-
-A [Footer](/docs/components-containers-footer--docs) and a [Spotlight](/docs/components-containers-spotlight--docs) are slightly wider than the grid.
-You close one instance of the grid before these components.
-Inside and optionally after them, you start a new one.
-Multiple instances of the grid component are possible on a page, but the columns of all grids must align precisely.
-
-Within the grid, you create cells containing the desired content.
-A cell often spans multiple columns of the grid.
+## Guidelines
+
+- Every page should use the grid as the foundation for its layout.
+  It is placed directly within the [Screen](/docs/components-layout-screen--docs).
+- A [Footer](/docs/components-containers-footer--docs) and a [Spotlight](/docs/components-containers-spotlight--docs) are slightly wider than the grid.
+  You close one instance of the grid before these components.
+  Inside and optionally after them, you start a new one.
+  Multiple instances of the grid component are possible on a page, but the columns of all grids must align precisely.
+- Within the grid, you create cells containing the desired content.
+  A cell often spans multiple columns of the grid.
+- The Gap utility classes must not be used on the Grid component.
 
 ## Design
 

package/src/components/grid/_mixins.scss

@@ -0,0 +1,110 @@
+/**
+ * @license EUPL-1.2+
+ * Copyright Gemeente Amsterdam
+ */
+
+@mixin ams-grid {
+  column-gap: var(--ams-grid-column-gap);
+  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);
+
+  @media screen and (min-width: $ams-breakpoint-medium) {
+    grid-template-columns: repeat(var(--ams-grid-medium-column-count), 1fr);
+  }
+
+  @media screen and (min-width: $ams-breakpoint-wide) {
+    grid-template-columns: repeat(var(--ams-grid-wide-column-count), 1fr);
+  }
+}
+
+// Grid gap
+
+@mixin ams-grid--gap-vertical--none {
+  row-gap: initial;
+}
+
+@mixin ams-grid--gap-vertical--small {
+  row-gap: var(--ams-grid-row-gap-sm);
+}
+
+@mixin ams-grid--gap-vertical--large {
+  row-gap: var(--ams-grid-row-gap-lg);
+}
+
+// Grid padding
+
+@mixin ams-grid--padding-bottom--small {
+  padding-block-end: var(--ams-grid-padding-block-sm);
+}
+
+@mixin ams-grid--padding-bottom--medium {
+  padding-block-end: var(--ams-grid-padding-block-md);
+}
+
+@mixin ams-grid--padding-bottom--large {
+  padding-block-end: var(--ams-grid-padding-block-lg);
+}
+
+@mixin ams-grid--padding-top--small {
+  padding-block-start: var(--ams-grid-padding-block-sm);
+}
+
+@mixin ams-grid--padding-top--medium {
+  padding-block-start: var(--ams-grid-padding-block-md);
+}
+
+@mixin ams-grid--padding-top--large {
+  padding-block-start: var(--ams-grid-padding-block-lg);
+}
+
+@mixin ams-grid--padding-vertical--small {
+  padding-block: var(--ams-grid-padding-block-sm);
+}
+
+@mixin ams-grid--padding-vertical--medium {
+  padding-block: var(--ams-grid-padding-block-md);
+}
+
+@mixin ams-grid--padding-vertical--large {
+  padding-block: var(--ams-grid-padding-block-lg);
+}
+
+@mixin ams-grid__cell--span-all {
+  grid-column: 1 / -1;
+}
+
+// Column span
+
+@mixin ams-grid__cell--span($i) {
+  grid-column-end: span $i;
+}
+
+@mixin ams-grid__cell--start($i) {
+  grid-column-start: $i;
+}
+
+@mixin ams-grid__cell--span-medium($i) {
+  @media screen and (min-width: $ams-breakpoint-medium) {
+    grid-column-end: span $i;
+  }
+}
+
+@mixin ams-grid__cell--start-medium($i) {
+  @media screen and (min-width: $ams-breakpoint-medium) {
+    grid-column-start: $i;
+  }
+}
+
+@mixin ams-grid__cell--span-wide($i) {
+  @media screen and (min-width: $ams-breakpoint-wide) {
+    grid-column-end: span $i;
+  }
+}
+
+@mixin ams-grid__cell--start-wide($i) {
+  @media screen and (min-width: $ams-breakpoint-wide) {
+    grid-column-start: $i;
+  }
+}

package/src/components/grid/grid.scss

@@ -4,107 +4,103 @@
  */
 
 @import "../../common/breakpoint";
+@import "mixins";
 
-.ams-grid {
-  column-gap: var(--ams-grid-column-gap);
-  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);
-
-  @media screen and (min-width: $ams-breakpoint-medium) {
-    grid-template-columns: repeat(var(--ams-grid-medium-column-count), 1fr);
-  }
+$ams-grid-column-count: 12;
 
-  @media screen and (min-width: $ams-breakpoint-wide) {
-    grid-template-columns: repeat(var(--ams-grid-wide-column-count), 1fr);
-  }
+.ams-grid {
+  @include ams-grid;
 }
 
+// Grid gap
+
 .ams-grid--gap-vertical--none {
-  row-gap: initial;
+  @include ams-grid--gap-vertical--none;
 }
 
 .ams-grid--gap-vertical--small {
-  row-gap: var(--ams-grid-row-gap-sm);
+  @include ams-grid--gap-vertical--small;
 }
 
 .ams-grid--gap-vertical--large {
-  row-gap: var(--ams-grid-row-gap-lg);
+  @include ams-grid--gap-vertical--large;
 }
 
+// Grid padding
+
 .ams-grid--padding-bottom--small {
-  padding-block-end: var(--ams-grid-padding-block-sm);
+  @include ams-grid--padding-bottom--small;
 }
 
 .ams-grid--padding-bottom--medium {
-  padding-block-end: var(--ams-grid-padding-block-md);
+  @include ams-grid--padding-bottom--medium;
 }
 
 .ams-grid--padding-bottom--large {
-  padding-block-end: var(--ams-grid-padding-block-lg);
+  @include ams-grid--padding-bottom--large;
 }
 
 .ams-grid--padding-top--small {
-  padding-block-start: var(--ams-grid-padding-block-sm);
+  @include ams-grid--padding-top--small;
 }
 
 .ams-grid--padding-top--medium {
-  padding-block-start: var(--ams-grid-padding-block-md);
+  @include ams-grid--padding-top--medium;
 }
 
 .ams-grid--padding-top--large {
-  padding-block-start: var(--ams-grid-padding-block-lg);
+  @include ams-grid--padding-top--large;
 }
 
 .ams-grid--padding-vertical--small {
-  padding-block: var(--ams-grid-padding-block-sm);
+  @include ams-grid--padding-vertical--small;
 }
 
 .ams-grid--padding-vertical--medium {
-  padding-block: var(--ams-grid-padding-block-md);
+  @include ams-grid--padding-vertical--medium;
 }
 
 .ams-grid--padding-vertical--large {
-  padding-block: var(--ams-grid-padding-block-lg);
+  @include ams-grid--padding-vertical--large;
 }
 
+// Column span
+// The order of these declaration blocks ensures the intended specificity.
+
 .ams-grid__cell--span-all {
-  grid-column: 1 / -1;
+  @include ams-grid__cell--span-all;
 }
 
-// The order of the following declaration blocks ensures the intended specificity.
-
-@for $i from 1 through 12 {
+@for $i from 1 through $ams-grid-column-count {
   .ams-grid__cell--span-#{$i} {
-    grid-column-end: span $i;
+    @include ams-grid__cell--span($i);
   }
 
   .ams-grid__cell--start-#{$i} {
-    grid-column-start: $i;
+    @include ams-grid__cell--start($i);
   }
 }
 
 @media screen and (min-width: $ams-breakpoint-medium) {
-  @for $i from 1 through 12 {
+  @for $i from 1 through $ams-grid-column-count {
     .ams-grid__cell--span-#{$i}-medium {
-      grid-column-end: span $i;
+      @include ams-grid__cell--span-medium($i);
     }
 
     .ams-grid__cell--start-#{$i}-medium {
-      grid-column-start: $i;
+      @include ams-grid__cell--start-medium($i);
     }
   }
 }
 
 @media screen and (min-width: $ams-breakpoint-wide) {
-  @for $i from 1 through 12 {
+  @for $i from 1 through $ams-grid-column-count {
     .ams-grid__cell--span-#{$i}-wide {
-      grid-column-end: span $i;
+      @include ams-grid__cell--span-wide($i);
     }
 
     .ams-grid__cell--start-#{$i}-wide {
-      grid-column-start: $i;
+      @include ams-grid__cell--start-wide($i);
     }
   }
 }

package/src/components/header/README.md

@@ -7,17 +7,15 @@ Includes the name of the application if it is not the general website.
 
 ## Guidelines
 
-The Header must be used on all websites and applications 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 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.
-It is the same on every page of the application.
-
-The page menu can contain a maximum of 5 items.
-The last two will often be ‘Search’ and ‘Menu’.
-Labels should be short to ensure the menu fits on one line, even on medium-wide screens.
-An icon can be added to the end of a link to make its function easier to find.
+- The Header must be used on all websites and applications 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 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.
+- It is the same on every page of the application.
+- The page menu can contain a maximum of 5 items.
+  The last two will often be ‘Search’ and ‘Menu’.
+- Labels should be short to ensure the menu fits on one line, even on medium-wide screens.
+- An icon can be added to the end of a link to make its function easier to find.
 
 ## References
 

package/src/components/header/header.scss

@@ -79,6 +79,7 @@
   font-weight: var(--ams-page-menu-item-font-weight);
   line-height: var(--ams-page-menu-item-line-height);
   margin-block: 0;
+  margin-inline: 0;
   padding-inline: 0 1.875rem;
   text-align: center;
   touch-action: manipulation;

package/src/components/hint/README.md

@@ -0,0 +1,9 @@
+<!-- @license CC0-1.0 -->
+
+# Hint
+
+Shows a hint text. Only used internally by Label and Field Set.
+
+## Class name
+
+`ams-hint`

package/src/components/hint/hint.scss

@@ -0,0 +1,9 @@
+/**
+ * @license EUPL-1.2+
+ * Copyright Gemeente Amsterdam
+ */
+
+.ams-hint {
+  color: var(--ams-hint-color);
+  display: inline-block;
+}

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

@@ -5,8 +5,12 @@
 
 @mixin reset {
   border: 0;
+  margin-block: 0; // [1]
+  margin-inline: 0; // [1]
   padding-block: 0;
   padding-inline: 0;
+
+  // [1] Remove the margin in older Safari.
 }
 
 .ams-icon-button {
@@ -16,6 +20,8 @@
   outline-offset: var(--ams-icon-button-outline-offset);
   touch-action: manipulation;
 
+  @include reset;
+
   &:hover {
     background-color: var(--ams-icon-button-hover-background-color);
     color: var(--ams-icon-button-hover-color);
@@ -26,35 +32,33 @@
     color: var(--ams-icon-button-disabled-color);
     cursor: not-allowed;
   }
-
-  @include reset;
 }
 
-.ams-icon-button--on-background-light {
-  color: var(--ams-icon-button-on-background-light-color);
+.ams-icon-button--contrast-color {
+  color: var(--ams-icon-button-contrast-color-color);
 
   &:hover {
-    background-color: var(--ams-icon-button-on-background-light-hover-background-color);
-    color: var(--ams-icon-button-on-background-light-hover-color);
+    background-color: var(--ams-icon-button-contrast-color-hover-background-color);
+    color: var(--ams-icon-button-contrast-color-hover-color);
   }
 
   &:disabled {
     background-color: transparent;
-    color: var(--ams-icon-button-on-background-light-disabled-color);
+    color: var(--ams-icon-button-contrast-color-disabled-color);
   }
 }
 
-.ams-icon-button--on-background-dark {
-  background-color: var(--ams-icon-button-on-background-dark-background-color);
-  color: var(--ams-icon-button-on-background-dark-color);
+.ams-icon-button--inverse-color {
+  background-color: var(--ams-icon-button-inverse-color-background-color);
+  color: var(--ams-icon-button-inverse-color-color);
 
   &:hover {
-    background-color: var(--ams-icon-button-on-background-dark-hover-background-color);
-    color: var(--ams-icon-button-on-background-dark-hover-color);
+    background-color: var(--ams-icon-button-inverse-color-hover-background-color);
+    color: var(--ams-icon-button-inverse-color-hover-color);
   }
 
   &:disabled {
-    background-color: var(--ams-icon-button-on-background-dark-disabled-background-color);
-    color: var(--ams-icon-button-on-background-dark-disabled-color);
+    background-color: var(--ams-icon-button-inverse-color-disabled-background-color);
+    color: var(--ams-icon-button-inverse-color-disabled-color);
   }
 }