@amsterdam/design-system-css 0.11.0 → 0.12.0

package/src/components/image-slider/README.md

@@ -0,0 +1,25 @@
+<!-- @license CC0-1.0 -->
+
+# Image Slider
+
+Displays a small set of images in a limited space.
+
+## Design
+
+The first or selected image shows at its maximum size.
+Every image displays a thumbnail at about 20% of its width.
+Users can use buttons, thumbnails or swiping to navigate between the images.
+The buttons re not displayed on a narrow touch device.
+The images do not slide automatically.
+
+## How to use
+
+- Use this for a series of images that belong together.
+- Provide at least 2 images and at most 5.
+- Feature the most essential image first.
+- Assume that some or many users will not navigate between the slides and only see the first image.
+  Display all images separately if you want each of them to receive attention.
+- A full-width Image Slider should run from one edge of the Screen to the other;
+  position it next to a Grid, not in a Cell spanning all columns.
+  Smaller sliders are fine in a Grid Cell.
+- Consult the [Image](/docs/components-media-image--docs) docs for guidelines on the individual images.

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

@@ -0,0 +1,89 @@
+/**
+ * @license EUPL-1.2+
+ * Copyright Gemeente Amsterdam
+ */
+@import "../../common/breakpoint";
+
+.ams-image-slider {
+  display: grid;
+  gap: var(--ams-image-slider-gap);
+  grid-template-rows: 1fr auto;
+}
+
+.ams-image-slider__item {
+  scroll-snap-align: center;
+  scroll-snap-stop: always;
+
+  /** temporary fix for covering the entire gallery */
+  .ams-image {
+    inline-size: 100%;
+  }
+}
+
+.ams-image-slider__scroller {
+  align-items: center;
+  display: grid;
+  gap: var(--ams-image-slider-scroller-gap);
+  grid-auto-columns: 100%;
+  grid-auto-flow: column;
+  grid-column: 1/-1;
+  grid-row: 1;
+  outline-offset: var(--ams-image-slider-scroller-outline-offset);
+  overflow-x: auto;
+  overscroll-behavior-x: contain;
+  scroll-snap-type: x mandatory;
+  scrollbar-width: none;
+
+  &::-webkit-scrollbar {
+    display: none;
+  }
+
+  @media not (prefers-reduced-motion) {
+    scroll-behavior: smooth;
+  }
+}
+
+.ams-image-slider__controls {
+  display: flex;
+  grid-column: 1/-1;
+  grid-row: 1;
+  justify-content: space-between;
+
+  @media (pointer: coarse) and (max-width: $ams-breakpoint-medium) {
+    display: none;
+  }
+}
+
+.ams-image-slider__control {
+  place-self: center;
+  z-index: 1;
+}
+
+.ams-image-slider__thumbnails {
+  display: grid;
+  gap: var(--ams-image-slider-thumbnails-gap);
+  grid-template-columns: repeat(5, 1fr);
+  max-inline-size: 100%;
+}
+
+.ams-image-slider__thumbnail {
+  background-color: var(--ams-image-slider-thumbnails-thumbnail-background-color);
+  background-position: center;
+  background-size: cover;
+  border: none;
+  cursor: var(--ams-image-slider-thumbnails-thumbnail-cursor);
+  opacity: var(--ams-image-slider-thumbnails-thumbnail-opacity);
+  outline-offset: var(--ams-button-outline-offset);
+  padding-block: 0;
+  padding-inline: 0;
+  position: relative;
+  scroll-snap-align: start;
+
+  &:hover {
+    opacity: var(--ams-image-slider-thumbnails-thumbnail-hover-opacity);
+  }
+}
+
+.ams-image-slider__thumbnail--in-view {
+  opacity: var(--ams-image-slider-thumbnails-thumbnail-in-view-opacity);
+}

package/src/components/index.scss

@@ -4,7 +4,12 @@
  */
 
 /* 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";

package/src/components/label/README.md

@@ -6,4 +6,6 @@ Describes a form control.
 
 ## Guidelines
 
-Always associate a form element (such as an `input` or `textarea`) with a label.
+- Always associate a form element (such as an `input` or `textarea`) with a label.
+- Set `optional` to `true` if the input is not required.
+- Use `hint` to show a custom hint text.

package/src/components/link/README.md

@@ -13,6 +13,7 @@ Use a link in the following cases:
 - To navigate to another website (see [External links](#external-links))
 - To navigate to an element on the same page
 - To link to emails or phone numbers (start the link with `mailto:` or `tel:`)
+- Wrap 2 or more consecutive buttons and/or links in an [Action Group](https://designsystem.amsterdam/?path=/docs/components-buttons-action-group--docs).
 
 A link is a navigation component.
 Use a button instead of a link when an action is desired.
@@ -30,6 +31,10 @@ We discourage using styles for visited links because they often make the page le
 The inline link does have a visited style.
 It is not part of navigation elements that are frequently scanned.
 
+### Using links with routing libraries
+
+Check out the [developer guide](/docs/docs-developer-guide-routing-libraries--docs) on how to integrate links with external routing libraries.
+
 ## Relevant WCAG requirements
 
 - [WCAG 1.4.3](https://www.w3.org/TR/WCAG21/#contrast-minimum)

package/src/components/link/link.scss

@@ -11,11 +11,11 @@
   font-weight: var(--ams-link-font-weight);
   outline-offset: var(--ams-link-outline-offset);
 
+  @include text-rendering;
+
   &:hover {
     color: var(--ams-link-hover-color);
   }
-
-  @include text-rendering;
 }
 
 .ams-link--standalone {
@@ -50,26 +50,26 @@
   }
 }
 
-.ams-link--on-background-dark {
-  color: var(--ams-link-on-background-dark-color);
+.ams-link--contrast-color {
+  color: var(--ams-link-contrast-color-color);
 
   &:hover {
-    color: var(--ams-link-on-background-dark-hover-color);
+    color: var(--ams-link-contrast-color-hover-color);
   }
 
   &:visited {
-    color: var(--ams-link-on-background-dark-visited-color);
+    color: var(--ams-link-contrast-color-visited-color);
   }
 }
 
-.ams-link--on-background-light {
-  color: var(--ams-link-on-background-light-color);
+.ams-link--inverse-color {
+  color: var(--ams-link-inverse-color-color);
 
   &:hover {
-    color: var(--ams-link-on-background-light-hover-color);
+    color: var(--ams-link-inverse-color-hover-color);
   }
 
   &:visited {
-    color: var(--ams-link-on-background-light-visited-color);
+    color: var(--ams-link-inverse-color-visited-color);
   }
 }

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

@@ -13,6 +13,5 @@ Therefore, it is blue and clickable.
 
 ## Guidelines
 
-Use a Link List to present multiple links within a theme.
-
-For additional guidelines, refer to the [Link](/docs/components-navigation-link--docs) component.
+- Use a Link List to present multiple links within a theme.
+- For additional guidelines, refer to the [Link](/docs/components-navigation-link--docs) component.

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

@@ -53,18 +53,18 @@
   @include hyphenation;
 }
 
-.ams-link-list__link--on-background-dark {
-  color: var(--ams-link-list-link-on-background-dark-color);
+.ams-link-list__link--contrast-color {
+  color: var(--ams-link-list-link-contrast-color-color);
 
   &:hover {
-    color: var(--ams-link-list-link-on-background-dark-hover-color);
+    color: var(--ams-link-list-link-contrast-color-hover-color);
   }
 }
 
-.ams-link-list__link--on-background-light {
-  color: var(--ams-link-list-link-on-background-light-color);
+.ams-link-list__link--inverse-color {
+  color: var(--ams-link-list-link-inverse-color-color);
 
   &:hover {
-    color: var(--ams-link-list-link-on-background-light-hover-color);
+    color: var(--ams-link-list-link-inverse-color-hover-color);
   }
 }

package/src/components/margin/README.md

@@ -8,13 +8,13 @@ Adds white space below a single element.
 
 The five sizes of [Component Space](/docs/brand-design-tokens-space--docs) are available for the height of the bottom margin.
 
-| Class name   | Preview                                                                                      |
+| Class name   | Example                                                                                      |
 | ------------ | -------------------------------------------------------------------------------------------- |
-| `ams-mb--xs` | <div className="ams-docs-token-preview--space" style="inline-size: var(--ams-margin-xs);" /> |
-| `ams-mb--sm` | <div className="ams-docs-token-preview--space" style="inline-size: var(--ams-margin-sm);" /> |
-| `ams-mb--md` | <div className="ams-docs-token-preview--space" style="inline-size: var(--ams-margin-md);" /> |
-| `ams-mb--lg` | <div className="ams-docs-token-preview--space" style="inline-size: var(--ams-margin-lg);" /> |
-| `ams-mb--xl` | <div className="ams-docs-token-preview--space" style="inline-size: var(--ams-margin-xl);" /> |
+| `ams-mb--xs` | <div className="ams-docs-token-example--space" style="inline-size: var(--ams-margin-xs);" /> |
+| `ams-mb--sm` | <div className="ams-docs-token-example--space" style="inline-size: var(--ams-margin-sm);" /> |
+| `ams-mb--md` | <div className="ams-docs-token-example--space" style="inline-size: var(--ams-margin-md);" /> |
+| `ams-mb--lg` | <div className="ams-docs-token-example--space" style="inline-size: var(--ams-margin-lg);" /> |
+| `ams-mb--xl` | <div className="ams-docs-token-example--space" style="inline-size: var(--ams-margin-xl);" /> |
 
 ## Guidelines
 

package/src/components/mark/README.md

@@ -7,13 +7,8 @@ Provides strong emphasis on the text and draws attention to it.
 
 ## Guidelines
 
-### How to Use
-
-- Use a maximum of 1 mark per page.
+- Use a maximum of 1 Mark per page.
 - Limit the marked text to 1 sentence.
-
-### Avoid This
-
 - Do not use it in titles and subtitles.
   Use a significant and engaging title if the entire paragraph is important.
 - Do not mark an entire paragraph.

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

@@ -7,3 +7,8 @@ This list can have 2 levels.
 The first level has numbers as list markers.
 The second level uses letters in alphabetical order.
 List items indent their text by a fixed distance.
+
+## Design
+
+The list uses ascending numbers as markers, providing enough space for numbers up to 99.
+Extra white space between items enhances the distinction, mainly when they consist of multiple lines of text.

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

@@ -5,7 +5,6 @@
 
 @import "../../common/text-rendering";
 
-/** Apply border box sizing, reset white space and list styles. */
 @mixin reset {
   box-sizing: border-box;
   list-style-type: none;
@@ -13,7 +12,6 @@
   padding-inline-start: 0;
 }
 
-/** A list is a grid column with a gap between items. */
 .ams-ordered-list {
   display: grid;
   gap: var(--ams-ordered-list-gap);
@@ -22,7 +20,6 @@
   @include reset;
 }
 
-/** A list with markers sets typography for its text content. */
 .ams-ordered-list:not(.ams-ordered-list--no-markers) {
   color: var(--ams-ordered-list-color);
   font-family: var(--ams-ordered-list-font-family);
@@ -31,7 +28,6 @@
   line-height: var(--ams-ordered-list-line-height);
   list-style-type: var(--ams-ordered-list-list-style-type);
 
-  /** List items are responsible for indentation and marker positioning. */
   .ams-ordered-list__item {
     margin-inline-start: var(--ams-ordered-list-item-margin-inline-start);
     padding-inline-start: var(--ams-ordered-list-item-padding-inline-start);
@@ -47,9 +43,11 @@
   line-height: var(--ams-ordered-list-small-line-height);
 }
 
-/** A nested list has a different marker and less indentation for correct alignment. */
 :is(.ams-ordered-list, .ams-unordered-list) .ams-ordered-list {
+  gap: var(--ams-ordered-list-ordered-list-gap);
   list-style-type: var(--ams-ordered-list-ordered-list-list-style-type);
+  padding-block-end: var(--ams-ordered-list-ordered-list-padding-block-end);
+  padding-block-start: var(--ams-ordered-list-ordered-list-padding-block-start);
 
   .ams-ordered-list__item {
     margin-inline-start: var(--ams-ordered-list-ordered-list-item-margin-inline-start);

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

@@ -13,8 +13,12 @@ A small set of links for use in the Header and Footer.
 - The ‘Menu’ button opens the Mega Menu.
 - On narrow screens, menu items other than ‘Search’ and ‘Menu’ move from the Page Menu to the Mega Menu.
 
+### Using links with routing libraries
+
+Check out the [developer guide](/docs/docs-developer-guide-routing-libraries--docs) on how to integrate links with external routing libraries.
+
 ## Relevant WCAG requirements
 
 - [Consistent Navigation (Level AA)](https://www.w3.org/WAI/WCAG21/Understanding/consistent-navigation.html)
 
-PageMenu is an interactive element, and the [general requirements and guidelines for interactivity](/docs/docs-developer-guide-interactivity--docs) apply.
+Page Menu is an interactive element, and the [general requirements and guidelines for interactivity](/docs/docs-developer-guide-interactivity--docs) apply.

package/src/components/pagination/pagination.scss

@@ -45,22 +45,22 @@
   text-underline-offset: var(--ams-pagination-button-text-underline-offset);
   touch-action: manipulation;
 
-  &:hover {
-    color: var(--ams-pagination-button-hover-color);
-    text-decoration-line: var(--ams-pagination-button-hover-text-decoration-line);
-  }
+  @include text-rendering;
 
   &:disabled {
     display: none;
   }
 
+  &:hover {
+    color: var(--ams-pagination-button-hover-color);
+    text-decoration-line: var(--ams-pagination-button-hover-text-decoration-line);
+  }
+
   // Override for icon size
   span.ams-icon svg {
     block-size: 1rem;
     inline-size: 1rem;
   }
-
-  @include text-rendering;
 }
 
 .ams-pagination__button--current {

package/src/components/password-input/README.md

@@ -0,0 +1,29 @@
+<!-- @license CC0-1.0 -->
+
+# Password Input
+
+Helps users enter a password.
+
+## Guidelines
+
+- Use this component when the input requires sensitive information, like passwords or PINs.
+  It ensures that the input is not readable by others who might be looking at the screen.
+- The characters entered are hidden, represented by squares.
+
+This component sets `autocorrect="off"` and `spellcheck="false"` to stop browsers automatically changing user input.
+Passwords shouldn’t be checked for spelling or grammar.
+This may also prevent posting the password to third-party plugins.
+These props cannot be overridden.
+
+Consider setting the following attributes:
+
+1. Allow the user’s password manager to automatically fill the password through `autocomplete="current-password"`.
+   When asking for a new password, use `autocomplete="new-password"` instead.
+2. Do not add a `minlength` attribute to ensure passwords meet a minimum length requirement.
+   This would prematurely indicate an error to the user – while they are still typing.
+3. Do not add a `maxlength` attribute either.
+   Users will not get any feedback when their text input has been truncated, e.g. after pasting from a password manager.
+4. If the password is a numeric PIN, add `inputmode="numeric"`.
+   Devices with virtual keyboards then switch to a numeric keypad layout which makes entering the password easier.
+
+Follow the [guidelines for asking for passwords](https://design-system.service.gov.uk/patterns/passwords/) of the GOV.UK Design System.

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

@@ -0,0 +1,59 @@
+/**
+ * @license EUPL-1.2+
+ * Copyright Gemeente Amsterdam
+ */
+
+@import "../../common/text-rendering";
+
+@mixin reset {
+  -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);
+  color: var(--ams-password-input-color);
+  font-family: var(--ams-password-input-font-family);
+  font-size: var(--ams-password-input-font-size);
+  font-weight: var(--ams-password-input-font-weight);
+  inline-size: 100%;
+  line-height: var(--ams-password-input-line-height);
+  outline-offset: var(--ams-password-input-outline-offset);
+  padding-block: var(--ams-password-input-padding-block);
+  padding-inline: var(--ams-password-input-padding-inline);
+  touch-action: manipulation;
+
+  @include text-rendering;
+  @include reset;
+
+  &:hover {
+    box-shadow: var(--ams-password-input-hover-box-shadow);
+  }
+}
+
+.ams-password-input::placeholder {
+  color: var(--ams-password-input-placeholder-color);
+  opacity: 100%; // This resets the lower opacity set by Firefox
+}
+
+.ams-password-input:disabled {
+  background-color: var(--ams-password-input-disabled-background-color);
+  box-shadow: var(--ams-password-input-disabled-box-shadow);
+  color: var(--ams-password-input-disabled-color);
+  cursor: not-allowed;
+}
+
+.ams-password-input:invalid,
+.ams-password-input[aria-invalid="true"] {
+  box-shadow: var(--ams-password-input-invalid-box-shadow);
+
+  &:hover {
+    // TODO: this should be the (currently non-existent) dark red hover color
+    box-shadow: var(--ams-password-input-invalid-hover-box-shadow);
+  }
+}

package/src/components/radio/README.md

@@ -6,9 +6,9 @@ Allows users to select one option from a list.
 
 ## Guidelines
 
-- Do not assume that users will know how many options they can select based on the visual difference between radios and checkboxes alone.
+- Do not assume that users will know how many options they can select based on the visual difference between Radios and Checkboxes alone.
   If needed, add a hint explaining this, for example, ‘Select one option’.
-- Order radio options alphabetically by default.
+- Order Radios alphabetically by default.
   In some cases, it can be helpful to order them from most-to-least common options.
   For example, you could order options for ‘Where do you live?’ based on population size.
   However you should do this with extreme caution as it can reinforce bias.