@amsterdam/design-system-css 0.13.0 → 0.14.0

package/src/components/heading/heading.scss

@@ -3,15 +3,15 @@
  * Copyright Gemeente Amsterdam
  */
 
-@import "../../common/hyphenation";
-@import "../../common/text-rendering";
+@use "../../common/hyphenation" as *;
+@use "../../common/text-rendering" as *;
 
-@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 {

package/src/components/icon/icon.scss

@@ -12,6 +12,10 @@
   fill: currentColor;
 }
 
+.ams-icon--inverse-color {
+  color: var(--ams-icon-inverse-color);
+}
+
 .ams-icon--square {
   aspect-ratio: 1 / 1;
   justify-content: center;

package/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);

package/src/components/image/README.md

@@ -4,21 +4,43 @@
 
 Displays an image.
 
+## Design
+
+Every Image should be shown in one of the [available aspect ratios](https://designsystem.amsterdam/?path=/docs/brand-design-tokens-aspect-ratio--docs).
+The default is 16:9.
+If the intrinsic dimensions of the source do not match an aspect ratio, the image will get cropped to cover the intended area.
+
 ## 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.
   Do this especially for the main image of a page, where the difference between sizes on a narrow and wide screen is most significant.
-- Ensure that the aspect ratio of the image is supported by the [Aspect Ratio](/docs/components-layout-aspect-ratio--docs) component.
 
 ## Relevant WCAG requirements
 
 - [WCAG 1.1.1](https://www.w3.org/TR/WCAG22/#non-text-content): Non-text content must have a text alternative.
 - [WCAG 1.4.5](https://www.w3.org/TR/WCAG22/#images-of-text): Use text instead of images of text.
 - [WCAG 1.4.9](https://www.w3.org/TR/WCAG22/#images-of-text-no-exception): Use images of text only when there is no alternative.
+
+## Further reading
+
+- [Alt Text: Not Always Needed](https://www.nngroup.com/articles/alt-text-usability/)
+  (Nielsen Norman Group)
+  “Adding alt text to every image does not automatically make webpage content easy to navigate and consume.
+  Screen-reader users [...] do not rely on visual information,
+  which means they are not interested in designers’ attempts to recreate visual experiences for them.”
+- [How to Write Good Alt Text](https://www.w3.org/WAI/tutorials/images/decision-tree/)
+  (Web Accessibility Initiative)
+  Four questions help you decide whether an image needs describing and how to do so.
+  “This decision tree describes how to use the alt attribute of the image element in various situations.”

package/src/components/image/image.scss

@@ -4,17 +4,17 @@
  */
 
 .ams-image {
+  aspect-ratio: var(--ams-image-aspect-ratio);
   block-size: auto; /* [1] */
   font-style: italic; /* [3] */
+  inline-size: fit-content;
   max-inline-size: 100%; /* [1] */
+  object-fit: cover; /* [4] */
   vertical-align: middle; /* [2] */
-
-  &--cover {
-    object-fit: cover;
-  }
 }
 
 // [1] Allow for fluid image sizing while maintaining aspect ratio governed by inline/block size attributes
 // [2] Remove ‘phantom’ white space
 // [3] Italicise alt text to visually offset it from surrounding copy
 // Source: https://x.com/csswizardry/status/1717841334462005661
+// [4] Crop the image to maintain a supported aspect ratio

package/src/components/image-slider/image-slider.scss

@@ -2,7 +2,7 @@
  * @license EUPL-1.2+
  * Copyright Gemeente Amsterdam
  */
-@import "../../common/breakpoint";
+@use "../../common/breakpoint" as *;
 
 .ams-image-slider {
   display: grid;

package/src/components/index.scss

@@ -4,66 +4,69 @@
  */
 
 /* Append here */
-@import "./action-group/action-group";
-@import "./breakout/breakout";
-@import "./hint/hint";
-@import "./password-input/password-input";
-@import "./form-error-list/form-error-list";
-@import "./image-slider/image-slider";
-@import "./table-of-contents/table-of-contents";
-@import "./error-message/error-message";
-@import "./file-input/file-input";
-@import "./field/field";
-@import "./select/select";
-@import "./time-input/time-input";
-@import "./date-input/date-input";
-@import "./document/document";
-@import "./avatar/avatar";
-@import "./character-count/character-count";
-@import "./description-list/description-list";
-@import "./row/row";
-@import "./radio/radio";
-@import "./tabs/tabs";
-@import "./text-area/text-area";
-@import "./column/column";
-@import "./margin/margin";
-@import "./gap/gap";
-@import "./field-set/field-set";
-@import "./link-list/link-list";
-@import "./badge/badge";
-@import "./table/table";
-@import "./mega-menu/mega-menu";
-@import "./icon-button/icon-button";
-@import "./skip-link/skip-link";
-@import "./overlap/overlap";
-@import "./header/header";
-@import "./mark/mark";
-@import "./text-input/text-input";
-@import "./search-field/search-field";
-@import "./logo/logo";
-@import "./dialog/dialog";
-@import "./image/image";
-@import "./pagination/pagination";
-@import "./accordion/accordion";
-@import "./alert/alert";
-@import "./aspect-ratio/aspect-ratio";
-@import "./blockquote/blockquote";
-@import "./breadcrumb/breadcrumb";
-@import "./button/button";
-@import "./card/card";
-@import "./checkbox/checkbox";
-@import "./label/label";
-@import "./grid/grid";
-@import "./heading/heading";
-@import "./spotlight/spotlight";
-@import "./icon/icon";
-@import "./link/link";
-@import "./ordered-list/ordered-list";
-@import "./page-heading/page-heading";
-@import "./page-menu/page-menu";
-@import "./paragraph/paragraph";
-@import "./screen/screen";
-@import "./switch/switch";
-@import "./top-task-link/top-task-link";
-@import "./unordered-list/unordered-list";
-@import "./visually-hidden/visually-hidden";
+@use "accordion/accordion";
+@use "action-group/action-group";
+@use "alert/alert";
+@use "aspect-ratio/aspect-ratio";
+@use "avatar/avatar";
+@use "badge/badge";
+@use "blockquote/blockquote";
+@use "breadcrumb/breadcrumb";
+@use "breakout/breakout";
+@use "button/button";
+@use "card/card";
+@use "character-count/character-count";
+@use "checkbox/checkbox";
+@use "column/column";
+@use "date-input/date-input";
+@use "description-list/description-list";
+@use "dialog/dialog";
+@use "document/document";
+@use "error-message/error-message";
+@use "field-set/field-set";
+@use "field/field";
+@use "figure/figure";
+@use "file-input/file-input";
+@use "file-list/file-list";
+@use "footer/footer";
+@use "form-error-list/form-error-list";
+@use "gap/gap";
+@use "grid/grid";
+@use "header/header";
+@use "heading/heading";
+@use "hint/hint";
+@use "icon-button/icon-button";
+@use "icon/icon";
+@use "image-slider/image-slider";
+@use "image/image";
+@use "label/label";
+@use "link-list/link-list";
+@use "link/link";
+@use "logo/logo";
+@use "margin/margin";
+@use "mark/mark";
+@use "mega-menu/mega-menu";
+@use "ordered-list/ordered-list";
+@use "overlap/overlap";
+@use "page-heading/page-heading";
+@use "page-menu/page-menu";
+@use "pagination/pagination";
+@use "paragraph/paragraph";
+@use "password-input/password-input";
+@use "radio/radio";
+@use "row/row";
+@use "screen/screen";
+@use "search-field/search-field";
+@use "select/select";
+@use "skip-link/skip-link";
+@use "spotlight/spotlight";
+@use "switch/switch";
+@use "table-of-contents/table-of-contents";
+@use "table/table";
+@use "tabs/tabs";
+@use "text-area/text-area";
+@use "text-input/text-input";
+@use "time-input/time-input";
+@use "top-task-link/top-task-link";
+@use "unordered-list/unordered-list";
+@use "visually-hidden/visually-hidden";

package/src/components/label/label.scss

@@ -3,8 +3,8 @@
  * Copyright Gemeente Amsterdam
  */
 
-@import "../../common/hyphenation";
-@import "../../common/text-rendering";
+@use "../../common/hyphenation" as *;
+@use "../../common/text-rendering" as *;
 
 .ams-label {
   color: var(--ams-label-color);

package/src/components/link/link.scss

@@ -3,7 +3,7 @@
  * Copyright Gemeente Amsterdam
  */
 
-@import "../../common/text-rendering";
+@use "../../common/text-rendering" as *;
 
 .ams-link {
   color: var(--ams-link-color);

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

@@ -3,22 +3,22 @@
  * Copyright Gemeente Amsterdam
  */
 
-@import "../../common/hyphenation";
-@import "../../common/text-rendering";
+@use "../../common/hyphenation" as *;
+@use "../../common/text-rendering" as *;
 
-@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 {

package/src/components/logo/README.md

@@ -34,7 +34,7 @@ The sub-brands are:
 - The logo links to the homepage of the website or application.
 - If the application is a form, application, or tool without a homepage, the logo links to the page where the form, application, or tool is referred to.
 
-The height of the logo is always 40 pixels.
+The logo is 40 pixels tall at its minimum, growing to 56 pixels in wider windows.
 This also applies to sub-brand logos.
 
 ## Download

package/src/components/logo/logo.scss

@@ -6,6 +6,7 @@
 .ams-logo {
   block-size: var(--ams-logo-block-size);
   display: block;
+  min-block-size: var(--ams-logo-min-block-size);
 }
 
 .ams-logo__emblem {

package/src/components/margin/margin.scss

@@ -3,9 +3,10 @@
  * Copyright Gemeente Amsterdam
  */
 
-@import "../../common/size";
+@use "sass:map";
+@use "../../common/size" as *;
 
-@each $size in map-keys($ams-sizes) {
+@each $size in map.keys($ams-sizes) {
   @if $size != "no" {
     .ams-mb--#{$size} {
       margin-block-end: var(--ams-margin-#{$size}) !important;

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

@@ -3,21 +3,21 @@
  * Copyright Gemeente Amsterdam
  */
 
-@import "../../common/text-rendering";
+@use "../../common/text-rendering" as *;
 
-@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) {

package/src/components/overlap/overlap.scss

@@ -7,6 +7,7 @@
   display: grid;
 
   > * {
-    grid-area: 1 / -1;
+    grid-column: 1 / -1;
+    grid-row: 1 / -1;
   }
 }

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

@@ -3,15 +3,15 @@
  * Copyright Gemeente Amsterdam
  */
 
-@import "../../common/hyphenation";
-@import "../../common/text-rendering";
+@use "../../common/hyphenation" as *;
+@use "../../common/text-rendering" as *;
 
-@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 {

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

@@ -3,20 +3,16 @@
  * Copyright Gemeente Amsterdam
  */
 
-@import "../../common/text-rendering";
+@use "../../common/text-rendering" as *;
 
-@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;
@@ -24,7 +20,7 @@
   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,

package/src/components/pagination/pagination.scss

@@ -3,9 +3,9 @@
  * Copyright Gemeente Amsterdam
  */
 
-@import "../../common/text-rendering";
+@use "../../common/text-rendering" as *;
 
-@mixin reset-list {
+@mixin reset-ol {
   list-style-type: none;
   margin-block: 0;
   padding-inline-start: 0;
@@ -21,12 +21,11 @@
   justify-content: center;
   line-height: var(--ams-pagination-line-height);
 
-  @include reset-list;
+  @include reset-ol;
 }
 
 @mixin reset-button {
   all: unset;
-  box-sizing: border-box;
   outline: revert;
 }
 
@@ -35,6 +34,7 @@
   at the bottom `all: unset` overrides the `gap` property. */
   @include reset-button;
 
+  box-sizing: border-box;
   cursor: pointer;
   display: flex;
   gap: var(--ams-pagination-button-gap);

package/src/components/paragraph/paragraph.scss

@@ -3,14 +3,14 @@
  * Copyright Gemeente Amsterdam
  */
 
-@import "../../common/text-rendering";
+@use "../../common/text-rendering" as *;
 
-@mixin reset {
-  box-sizing: border-box;
+@mixin reset-p {
   margin-block: 0;
 }
 
 .ams-paragraph {
+  box-sizing: border-box;
   color: var(--ams-paragraph-color);
   font-family: var(--ams-paragraph-font-family);
   font-size: var(--ams-paragraph-font-size);
@@ -18,7 +18,7 @@
   line-height: var(--ams-paragraph-line-height);
 
   @include text-rendering;
-  @include reset;
+  @include reset-p;
 }
 
 .ams-paragraph--small {

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

@@ -3,20 +3,20 @@
  * Copyright Gemeente Amsterdam
  */
 
-@import "../../common/text-rendering";
+@use "../../common/text-rendering" as *;
 
-@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-password-input {
   background-color: var(--ams-password-input-background-color);
   box-shadow: var(--ams-password-input-box-shadow);
+  box-sizing: border-box;
   color: var(--ams-password-input-color);
   font-family: var(--ams-password-input-font-family);
   font-size: var(--ams-password-input-font-size);
@@ -29,7 +29,7 @@
   touch-action: manipulation;
 
   @include text-rendering;
-  @include reset;
+  @include reset-input;
 
   &:hover {
     box-shadow: var(--ams-password-input-hover-box-shadow);

package/src/components/radio/radio.scss

@@ -3,9 +3,9 @@
  * Copyright Gemeente Amsterdam
  */
 
-@import "../../common/input-label-focus";
-@import "../../common/hide-input";
-@import "../../common/text-rendering";
+@use "../../common/input-label-focus" as *;
+@use "../../common/hide-input" as *;
+@use "../../common/text-rendering" as *;
 
 .ams-radio__input {
   @include hide-input;
@@ -37,9 +37,15 @@
 }
 
 .ams-radio__circle {
-  fill: none;
+  fill: var(--ams-radio-circle-fill);
   stroke: var(--ams-radio-circle-stroke);
-  stroke-width: 0.125rem;
+  stroke-width: var(--ams-radio-circle-stroke-width);
+}
+
+.ams-radio__hover-indicator {
+  fill: none;
+  stroke: transparent;
+  stroke-width: var(--ams-radio-hover-indicator-stroke-width);
 }
 
 .ams-radio__checked-indicator {
@@ -56,6 +62,10 @@
     stroke: var(--ams-radio-circle-hover-stroke);
   }
 
+  .ams-radio__hover-indicator {
+    stroke: var(--ams-radio-hover-indicator-hover-stroke);
+  }
+
   .ams-radio__checked-indicator {
     fill: var(--ams-radio-checked-indicator-hover-fill);
   }
@@ -108,9 +118,13 @@
 
 // HOVER
 
-// Disabled label hover
+// Disabled hover
 .ams-radio__input:disabled + .ams-radio__label:hover {
   text-decoration: none;
+
+  .ams-radio__hover-indicator {
+    stroke: transparent;
+  }
 }
 
 // Invalid hover
@@ -120,6 +134,11 @@
     stroke: var(--ams-radio-circle-invalid-hover-stroke);
   }
 
+  .ams-radio__hover-indicator {
+    // TODO: this should be the (currently non-existent) dark red hover color
+    stroke: var(--ams-radio-hover-indicator-invalid-hover-stroke);
+  }
+
   .ams-radio__checked-indicator {
     // TODO: this should be the (currently non-existent) dark red hover color
     fill: var(--ams-radio-checked-indicator-invalid-hover-fill);
@@ -133,6 +152,9 @@
     stroke: var(--ams-radio-circle-disabled-invalid-hover-stroke);
   }
 
+  .ams-radio__hover-indicator {
+    stroke: transparent;
+  }
   .ams-radio__checked-indicator {
     // TODO: currently disabled invalid gets the same styling as disabled. This should get its own styling.
     fill: var(--ams-radio-checked-indicator-disabled-invalid-hover-fill);

package/src/components/row/row.scss

@@ -3,7 +3,7 @@
  * Copyright Gemeente Amsterdam
  */
 
-@import "../../common/size";
+@use "../../common/size" as *;
 
 .ams-row {
   display: flex;