Merge branch 'develop' into feature/DES-974-storybook-screen-decorator

packages/css/documentation/coding-conventions.md

@@ -39,9 +39,13 @@ Still, we define its thickness and offset for the initial state.
 ## Use mixins for patterns and resets
 
 We use Sass mixins to extract common patterns, especially if they need more than 1 declaration.
-We collect reset styles in mixins as well.
 Both the name of the mixins and their documentation help explain the approach.
 
+We collect reset styles in mixins as well.
+These are named after the element they reset, e.g. `@mixin reset-ul`.
+This helps reusing reset styles per element, and reminds to update the mixin if the element type changes.
+The declarations in the mixin must override default user agent styling; otherwise it is not a reset.
+
 ## Form validation styling
 
 We style both the native invalid state (`:invalid`) as the invalid state you can set manually, using `aria-invalid`.

packages/css/src/components/blockquote/blockquote.scss

@@ -6,13 +6,13 @@
 @import "../../common/hyphenation";
 @import "../../common/text-rendering";
 
-@mixin reset {
-  box-sizing: border-box;
+@mixin reset-blockquote {
   margin-block: 0;
   margin-inline: 0;
 }
 
 .ams-blockquote {
+  box-sizing: border-box;
   break-inside: avoid;
   color: var(--ams-blockquote-color);
   font-family: var(--ams-blockquote-font-family);
@@ -23,7 +23,7 @@
 
   @include hyphenation;
   @include text-rendering;
-  @include reset;
+  @include reset-blockquote;
 
   &::before {
     content: open-quote;

packages/css/src/components/breadcrumb/breadcrumb.scss

@@ -5,8 +5,7 @@
 
 @import "../../common/text-rendering";
 
-@mixin reset {
-  box-sizing: border-box;
+@mixin reset-ol {
   margin-block: 0;
   padding-inline: 0;
 }
@@ -19,11 +18,12 @@
 }
 
 .ams-breadcrumb__list {
+  box-sizing: border-box;
   break-after: avoid;
   break-inside: avoid;
 
   @include text-rendering;
-  @include reset;
+  @include reset-ol;
 }
 
 .ams-breadcrumb__item {

packages/css/src/components/date-input/date-input.scss

@@ -5,18 +5,18 @@
 
 @import "../../common/text-rendering";
 
-@mixin reset {
+@mixin reset-input {
   -webkit-appearance: none; // Reset appearance for Safari < 15.4
   appearance: none; // Reset native appearance, this causes issues on iOS and Android devices
   border: 0;
   border-radius: 0; // Reset rounded borders on iOS devices
-  box-sizing: border-box;
   margin-block: 0;
 }
 
 .ams-date-input {
   background-color: var(--ams-date-input-background-color);
   box-shadow: var(--ams-date-input-box-shadow);
+  box-sizing: border-box;
   color: var(--ams-date-input-color);
   font-family: var(--ams-date-input-font-family);
   font-size: var(--ams-date-input-font-size);
@@ -36,7 +36,7 @@
   touch-action: manipulation;
 
   @include text-rendering;
-  @include reset;
+  @include reset-input;
 
   &:hover {
     box-shadow: var(--ams-date-input-hover-box-shadow);

packages/css/src/components/description-list/description-list.scss

@@ -6,12 +6,12 @@
 @import "../../common/breakpoint";
 @import "../../common/text-rendering";
 
-@mixin reset {
-  box-sizing: border-box;
+@mixin reset-dl {
   margin-block: 0;
 }
 
 .ams-description-list {
+  box-sizing: border-box;
   color: var(--ams-description-list-color);
   column-gap: var(--ams-description-list-column-gap);
   display: grid;
@@ -20,7 +20,7 @@
   line-height: var(--ams-description-list-line-height);
   row-gap: var(--ams-description-list-row-gap);
 
-  @include reset;
+  @include reset-dl;
   @include text-rendering;
 }
 
@@ -54,15 +54,15 @@
   }
 }
 
-@mixin reset-description {
+@mixin reset-dd {
   margin-inline: 0;
 }
 
 .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;
+  @include reset-dd;
 
   @media screen and (min-width: $ams-breakpoint-medium) {
     grid-column-start: 2;

packages/css/src/components/dialog/dialog.scss

@@ -4,7 +4,6 @@
  */
 
 @mixin reset-dialog {
-  box-sizing: border-box;
   inset-block: 0;
 }
 
@@ -13,6 +12,7 @@ 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);
+  box-sizing: border-box;
   display: flex; // Using flex here, because grid works strangely in Safari
   flex-direction: column;
   gap: var(--ams-dialog-gap);

packages/css/src/components/error-message/error-message.scss

@@ -5,12 +5,12 @@
 
 @import "../../common/text-rendering";
 
-@mixin reset {
-  box-sizing: border-box;
+@mixin reset-p {
   margin-block: 0;
 }
 
 .ams-error-message {
+  box-sizing: border-box;
   color: var(--ams-error-message-color);
   display: inline-flex;
   font-family: var(--ams-error-message-font-family);
@@ -20,5 +20,5 @@
   line-height: var(--ams-error-message-line-height);
 
   @include text-rendering;
-  @include reset;
+  @include reset-p;
 }

packages/css/src/components/field-set/field-set.scss

@@ -6,7 +6,7 @@
 @import "../../common/hyphenation";
 @import "../../common/text-rendering";
 
-@mixin reset {
+@mixin reset-fieldset {
   border: 0;
   margin-inline: 0;
   padding-block: 0;
@@ -16,7 +16,7 @@
 .ams-field-set {
   break-inside: avoid;
 
-  @include reset;
+  @include reset-fieldset;
 }
 
 .ams-field-set--invalid {

packages/css/src/components/file-input/file-input.scss

@@ -8,7 +8,6 @@
 @mixin reset-button {
   border: 0;
   border-radius: 0; // Reset rounded borders on iOS devices
-  box-sizing: border-box;
 }
 
 .ams-file-input {
@@ -39,6 +38,7 @@
   appearance: none; // Reset native appearance, this causes issues on iOS and Android devices
   background-color: var(--ams-file-input-file-selector-button-background-color);
   box-shadow: var(--ams-file-input-file-selector-button-box-shadow);
+  box-sizing: border-box;
   color: var(--ams-file-input-file-selector-button-color);
   cursor: var(--ams-file-input-file-selector-button-cursor);
   font-family: inherit;

packages/css/src/components/heading/heading.scss

@@ -6,12 +6,12 @@
 @import "../../common/hyphenation";
 @import "../../common/text-rendering";
 
-@mixin reset {
-  box-sizing: border-box;
+@mixin reset-hx {
   margin-block: 0;
 }
 
 .ams-heading {
+  box-sizing: border-box;
   break-after: avoid;
   break-inside: avoid;
   color: var(--ams-heading-color);
@@ -20,7 +20,7 @@
 
   @include hyphenation;
   @include text-rendering;
-  @include reset;
+  @include reset-hx;
 }
 
 .ams-heading--level-1 {

packages/css/src/components/icon-button/icon-button.scss

@@ -3,7 +3,7 @@
  * Copyright Gemeente Amsterdam
  */
 
-@mixin reset {
+@mixin reset-button {
   border: 0;
   margin-block: 0; // [1]
   margin-inline: 0; // [1]
@@ -20,7 +20,7 @@
   outline-offset: var(--ams-icon-button-outline-offset);
   touch-action: manipulation;
 
-  @include reset;
+  @include reset-button;
 
   &:hover {
     background-color: var(--ams-icon-button-hover-background-color);

packages/css/src/components/image/README.md

@@ -12,11 +12,16 @@ If the intrinsic dimensions of the source do not match an aspect ratio, the imag
 
 ## Guidelines
 
-- Do not forget to include a description of the image in the `alt` attribute.
-  This ensures that screen reader users can also access this information.
-  Additionally, it can aid in search engine optimization.
+- The `alt` attribute is required, but can be empty.
 - A description is unnecessary for decorative images; use `alt=""` for these.
-  Examples are images that add little to the nearby text or pictures that purely contribute to the design or atmosphere of the page (source: [W3C Web Accessibility Initiative](https://www.w3.org/WAI/tutorials/images/decorative/)).
+  Non-visual browsers will then hide the image from the user.
+  Examples are images that add little to the nearby text, and pictures that purely contribute to the design or atmosphere of the page (source: [W3C Web Accessibility Initiative](https://www.w3.org/WAI/tutorials/images/decorative/)).
+- Do describe the content of the image if the image isn’t only decorative.
+  When choosing a description for your images, imagine what you would say when reading the page to someone over the phone without mentioning that there’s an image on the page (source: [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/alt)).
+- Every image’s alternate text should be able to replace the image without altering the meaning of the page.
+  You should never use `alt` for text that could be construed as a caption or title (source: [MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/alt)).
+- The alternate text will also display if the image is not (yet) loaded.
+  Additionally, it can be helpful for search engine optimization.
 - Optionally specify multiple candidates for the image through the `srcSet` attribute.
   For example, provide small, medium, and large variants for various screen sizes.
   This prevents unnecessary downloading of large files.

packages/css/src/components/link-list/link-list.scss

@@ -6,19 +6,19 @@
 @import "../../common/hyphenation";
 @import "../../common/text-rendering";
 
-@mixin reset-list {
-  box-sizing: border-box;
+@mixin reset-ul {
   list-style: none;
   margin-block: 0;
   padding-inline-start: 0;
 }
 
 .ams-link-list {
+  box-sizing: border-box;
   display: grid;
   gap: var(--ams-link-list-gap);
 
   @include text-rendering;
-  @include reset-list;
+  @include reset-ul;
 }
 
 .ams-link-list__link {

packages/css/src/components/ordered-list/ordered-list.scss

@@ -5,19 +5,19 @@
 
 @import "../../common/text-rendering";
 
-@mixin reset {
-  box-sizing: border-box;
+@mixin reset-ol {
   list-style-type: none;
   margin-block: 0;
   padding-inline-start: 0;
 }
 
 .ams-ordered-list {
+  box-sizing: border-box;
   display: grid;
   gap: var(--ams-ordered-list-gap);
 
   @include text-rendering;
-  @include reset;
+  @include reset-ol;
 }
 
 .ams-ordered-list:not(.ams-ordered-list--no-markers) {

packages/css/src/components/page-heading/page-heading.scss

@@ -6,12 +6,12 @@
 @import "../../common/hyphenation";
 @import "../../common/text-rendering";
 
-@mixin reset {
-  box-sizing: border-box;
+@mixin reset-h1 {
   margin-block: 0;
 }
 
 .ams-page-heading {
+  box-sizing: border-box;
   break-after: avoid;
   break-inside: avoid;
   color: var(--ams-page-heading-color);
@@ -22,7 +22,7 @@
 
   @include hyphenation;
   @include text-rendering;
-  @include reset;
+  @include reset-h1;
 }
 
 .ams-page-heading--inverse-color {

packages/css/src/components/page-menu/page-menu.scss

@@ -5,26 +5,22 @@
 
 @import "../../common/text-rendering";
 
-@mixin reset-list {
-  box-sizing: border-box;
+@mixin reset-ul {
   margin-block: 0;
   padding-inline: 0;
 }
 
-@mixin reset-item {
-  box-sizing: border-box;
-}
-
 .ams-page-menu {
   align-items: center;
+  box-sizing: border-box;
   column-gap: var(--ams-page-menu-column-gap);
   display: flex;
   flex-direction: row;
   flex-wrap: wrap;
   list-style: none;
   row-gap: var(--ams-page-menu-row-gap);
 
-  @include reset-list;
+  @include reset-ul;
 }
 
 .ams-page-menu--align-end {
@@ -54,9 +50,10 @@
 }
 
 .ams-page-menu__link {
+  box-sizing: border-box;
+
   @include page-menu-item;
   @include text-rendering;
-  @include reset-item;
 }
 
 .ams-page-menu__link:hover,