@amsterdam/design-system-css 0.9.0 → 0.11.0

package/src/components/avatar/avatar.scss

@@ -28,16 +28,16 @@
   vertical-align: middle; /* Remove ‘phantom’ white space when image doesn’t load */
 }
 
+.ams-avatar--black {
+  background-color: var(--ams-avatar-black-background-color);
+  color: var(--ams-avatar-black-color);
+}
+
 .ams-avatar--blue {
   background-color: var(--ams-avatar-blue-background-color);
   color: var(--ams-avatar-blue-color);
 }
 
-.ams-avatar--dark-blue {
-  background-color: var(--ams-avatar-dark-blue-background-color);
-  color: var(--ams-avatar-dark-blue-color);
-}
-
 .ams-avatar--dark-green {
   background-color: var(--ams-avatar-dark-green-background-color);
   color: var(--ams-avatar-dark-green-color);
@@ -48,6 +48,26 @@
   color: var(--ams-avatar-green-color);
 }
 
+.ams-avatar--grey-1 {
+  background-color: var(--ams-avatar-grey-1-background-color);
+  color: var(--ams-avatar-grey-1-color);
+}
+
+.ams-avatar--grey-2 {
+  background-color: var(--ams-avatar-grey-2-background-color);
+  color: var(--ams-avatar-grey-2-color);
+}
+
+.ams-avatar--grey-3 {
+  background-color: var(--ams-avatar-grey-3-background-color);
+  color: var(--ams-avatar-grey-3-color);
+}
+
+.ams-avatar--light-blue {
+  background-color: var(--ams-avatar-light-blue-background-color);
+  color: var(--ams-avatar-light-blue-color);
+}
+
 .ams-avatar--magenta {
   background-color: var(--ams-avatar-magenta-background-color);
   color: var(--ams-avatar-magenta-color);
@@ -68,6 +88,11 @@
   color: var(--ams-avatar-red-color);
 }
 
+.ams-avatar--white {
+  background-color: var(--ams-avatar-white-background-color);
+  color: var(--ams-avatar-white-color);
+}
+
 .ams-avatar--yellow {
   background-color: var(--ams-avatar-yellow-background-color);
   color: var(--ams-avatar-yellow-color);

package/src/components/breadcrumb/breadcrumb.scss

@@ -12,7 +12,7 @@
 }
 
 .ams-breadcrumb {
-  font-family: var(--ams-breadcrumb-font-family, inherit);
+  font-family: var(--ams-breadcrumb-font-family);
   font-size: var(--ams-breadcrumb-font-size);
   font-weight: var(--ams-breadcrumb-font-weight);
   line-height: var(--ams-breadcrumb-line-height);
@@ -33,11 +33,11 @@
 .ams-breadcrumb__item:not(:last-child)::after {
   background-image: var(--ams-breadcrumb-separator-background-image);
   background-repeat: no-repeat;
-  block-size: 1ex;
+  block-size: var(--ams-breadcrumb-separator-block-size);
   content: "";
   display: inline-block;
-  inline-size: 1ex;
-  margin-inline: 0.5rem;
+  inline-size: var(--ams-breadcrumb-separator-inline-size);
+  margin-inline: var(--ams-breadcrumb-separator-margin-inline);
 }
 
 .ams-breadcrumb__link {

package/src/components/card/README.md

@@ -19,7 +19,7 @@ The link is mandatory.
   For referencing a thematic page, use a [top task link](/docs/components-navigation-top-task-link--docs).
   You can also use a [regular link](/docs/components-navigation-link--docs).
 
-## Screen Readers
+## Screen readers
 
 With a screen reader, you can navigate using headings and links in a document.
 The title of a card is a link within a heading, allowing you to utilize both navigation methods.

package/src/components/card/card.scss

@@ -5,7 +5,7 @@
 
 .ams-card {
   display: grid;
-  gap: 0.5rem;
+  gap: var(--ams-card-gap);
   outline-offset: var(--ams-card-outline-offset);
   position: relative;
   touch-action: manipulation;
@@ -32,7 +32,8 @@
   a::after {
     content: "";
     display: block;
-    inset: 0;
+    inset-block: 0;
+    inset-inline: 0;
     position: absolute;
   }
 }
@@ -40,7 +41,7 @@
 .ams-card__heading-group {
   display: flex;
   flex-direction: column-reverse;
-  gap: 0.5rem;
+  gap: var(--ams-card-heading-group-gap);
 }
 
 .ams-card__link {

package/src/components/{form-field-character-counter → character-count}/README.md

@@ -1,19 +1,19 @@
 <!-- @license CC0-1.0 -->
 
-# Form Field Character Counter
+# Character Count
 
 Help users know how much text they can enter when there is a limit on the number of characters.
 
 Users will get updates at a pace that works best for the way they interact with the textarea. This means:
 
-- sighted users will see a count message that updates as they type
+- sighted users will see a count message that updates as they type;
 - screen reader users will hear the count announcement when they stop typing.
 
 This component does not restrict the user from entering information. The user can enter more than the character limit, but are told they’ve entered too many characters. This lets them type or copy and paste their full answer, then edit it down.
 
 ## Guidelines
 
-- Only use a character counter when there is a good reason for limiting the number of characters users can enter.
+- Only use a character count when there is a good reason for limiting the number of characters users can enter.
   For example, if there is an indication that users are likely to enter more information than they need to.
   Or when there is a legal or technical reason that means an entry must be no more than a certain number of characters.
-- If your users keep hitting the character limit imposed by the backend of your service then try to increase the limit rather than use a character counter.
+- If your users keep hitting the character limit imposed by the backend of your service then try to increase the limit rather than use a character count.

package/src/components/character-count/character-count.scss

@@ -0,0 +1,20 @@
+/**
+ * @license EUPL-1.2+
+ * Copyright Gemeente Amsterdam
+ */
+
+@import "../../common/text-rendering";
+
+.ams-character-count {
+  color: var(--ams-character-count-color);
+  font-family: var(--ams-character-count-font-family);
+  font-size: var(--ams-character-count-font-size);
+  font-weight: var(--ams-character-count-font-weight);
+  line-height: var(--ams-character-count-line-height);
+
+  @include text-rendering;
+}
+
+.ams-character-count--error {
+  color: var(--ams-character-count-error-color);
+}

package/src/components/checkbox/README.md

@@ -17,14 +17,14 @@ Allows users to make a selection or agree to terms.
 - A list of checkboxes should be in a `fieldset` with a `legend` describing what the list is about.
   For example, if the checkboxes are used to get answers to a question, the `legend` is the question.
 
-## Checkbox Labels
+## Checkbox labels
 
 A label starts with a capital letter.
 It does not have punctuation at the end if it is a single sentence, word, or fragment.
 It is written in the first person when asking the user to agree to the terms and conditions.
 
-## Relevant WCAG Requirements
+## Relevant WCAG requirements
 
 - [WCAG 1.3.5](https://www.w3.org/WAI/WCAG21/Understanding/identify-input-purpose.html): It is clear for both users and programmatically what the purpose of a form field is.
 
-Checkbox is an interactive element; therefore, [the general requirements and guidelines for interactive elements](/docs/docs-design-guidelines-interactive-elements--docs) apply.
+Checkbox is an interactive element; therefore, [the general requirements and guidelines for interactivity](/docs/docs-developer-guide-interactivity--docs) apply.

package/src/components/checkbox/checkbox.scss

@@ -40,7 +40,7 @@
   font-family: var(--ams-checkbox-font-family);
   font-size: var(--ams-checkbox-font-size);
   font-weight: var(--ams-checkbox-font-weight);
-  gap: 0.5rem;
+  gap: var(--ams-checkbox-gap);
   line-height: var(--ams-checkbox-line-height);
   outline-offset: var(--ams-checkbox-outline-offset);
 

package/src/components/column/README.md

@@ -2,4 +2,4 @@
 
 # Column
 
-Stacks its children vertically and adds a vertical gap between them.
+Stacks its children vertically with gaps between them and offers alignment options.

package/src/components/column/column.scss

@@ -6,11 +6,47 @@
 @import "../../common/size";
 
 .ams-column {
-  display: grid;
+  display: flex;
+  flex-direction: column;
+  gap: var(--ams-column-gap-md);
 }
 
 @each $size, $label in $ams-sizes {
-  .ams-column--#{$label} {
-    gap: var(--ams-column-gap-#{$size});
+  @if $size != "md" {
+    .ams-column--gap-#{$label} {
+      gap: var(--ams-column-gap-#{$size});
+    }
   }
 }
+
+.ams-column--align-around {
+  justify-content: space-around;
+}
+
+.ams-column--align-between {
+  justify-content: space-between;
+}
+
+.ams-column--align-center {
+  justify-content: center;
+}
+
+.ams-column--align-end {
+  justify-content: flex-end;
+}
+
+.ams-column--align-evenly {
+  justify-content: space-evenly;
+}
+
+.ams-column--align-horizontal-center {
+  align-items: center;
+}
+
+.ams-column--align-horizontal-end {
+  align-items: flex-end;
+}
+
+.ams-column--align-horizontal-start {
+  align-items: flex-start;
+}

package/src/components/dialog/README.md

@@ -17,7 +17,7 @@ Sighted users will read the primary action first, in line with the natural readi
 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.
 
-## Keyboard Support
+## Keyboard support
 
 | key         | function                                                         |
 | :---------- | :--------------------------------------------------------------- |

package/src/components/dialog/dialog.scss

@@ -3,14 +3,20 @@
  * Copyright Gemeente Amsterdam
  */
 
+@mixin reset-dialog {
+  inset-block: 0;
+  padding-block: 0;
+  padding-inline: 0;
+}
+
 .ams-dialog {
   background-color: var(--ams-dialog-background-color);
   border: var(--ams-dialog-border);
-  inset: 0;
+  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: 0;
-  padding-inline: 0;
-  position: fixed;
+
+  @include reset-dialog;
 
   /* no token because dialog does not inherit from any element */
   &::backdrop {
@@ -21,18 +27,14 @@
 .ams-dialog__form {
   display: grid;
   gap: var(--ams-dialog-form-gap);
-  grid-template-rows: auto 1fr auto;
-  max-block-size: var(--ams-dialog-form-max-block-size);
-
-  // TODO Decide on these widths
   padding-block: var(--ams-dialog-form-padding-block);
   padding-inline: var(--ams-dialog-form-padding-inline);
 }
 
 .ams-dialog__article {
   display: grid;
-  gap: 1.5rem; /* Until we have a consistent way of spacing text elements */
-  max-block-size: 100%; /* safari */
+  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;
 }

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

@@ -8,7 +8,7 @@ A component to group related form inputs.
 
 - 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.
 
-## Relevant WCAG Requirements
+## Relevant WCAG requirements
 
 - [WCAG 1.3.5](https://www.w3.org/WAI/WCAG22/Understanding/identify-input-purpose.html): Field Set labels the purpose of a group of inputs.
 

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

@@ -28,6 +28,10 @@
   float: inline-start; // [1]
   inline-size: 100%; // [1]
   padding-inline: 0;
+
+  + * {
+    clear: both; // Reset the applied float for the legend’s first sibling
+  }
 }
 
 // [1] This combination allows the fieldset border to go around the legend, instead of through it.

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

@@ -21,7 +21,7 @@
   font-weight: var(--ams-file-input-font-weight);
   line-height: var(--ams-file-input-line-height);
   max-inline-size: calc(100% - var(--ams-file-input-padding-inline) * 2);
-  outline-offset: 0.25rem; // Double the default focus outline offset to compensate for the dashed border
+  outline-offset: calc(var(--ams-focus-outline-offset) * 2); // Compensate for the dashed border
   padding-block: var(--ams-file-input-padding-block);
   padding-inline: var(--ams-file-input-padding-inline);
   touch-action: manipulation;

package/src/components/footer/README.md

@@ -2,16 +2,21 @@
 
 # Footer
 
-The footer is the closing section on every web page.
-Its content provides service information.
-A part is prescribed, and a part is filled based on the website’s objectives.
+Provides service information at the bottom of every page.
 
 ## Guidelines
 
-- The footer is mandatory, and there is one on every page.
+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:
+
 - The first column focuses on contact information.
   The information is as specific as possible and tailored to the respective website or page (e.g., including a chat option if available).
 - The second column contains links to relevant (online) sites or sources.
 - The third column refers to newsletters, social media, etc.
-- The last part of the footer is intended for links to privacy policies, cookie statements, explanations about the website, etc.
-  It is not intended for links to contact information, for example.
+
+The menu at the very bottom is intended for links to privacy policies, cookie statements, information about the website itself, etc.
+Contact details should not go here.

package/src/components/form-error-list/README.md

@@ -0,0 +1,47 @@
+<!-- @license CC0-1.0 -->
+
+# Form Error List
+
+Use this component at the top of a page to summarise any errors a user has made.
+When a user makes an error, you must show both a Form Error List and an Error Message above each answer that contains an error.
+
+## Guidelines
+
+- Always show a Form Error List when there is a validation error, even if there’s only one.
+- You must link the errors in the Form Error List to the answer they relate to (see below).
+
+## Linking from the Form Error List to each answer
+
+For questions that require a user to answer using a single field, like a file upload, select, textarea, text input or character count, link to the `id` of that field.
+
+When a user has to enter their answer into multiple fields, such as day, month and year fields, link to the `id` of the first field that contains an error.
+If you do not know which field contains an error, link to the `id` of the first field.
+
+For questions that require a user to select one or more options from a list using Radios or Checkboxes, link to the `id` of the first Radio or Checkbox.
+
+## Where to put the Form Error List
+
+Put the Form Error List directly above the first question on the page. Place it outside of the `<form>`-tag, [to make sure screen readers do not skip it](https://nldesignsystem.nl/richtlijnen/formulieren/meerdere-stappen/#plaats-de-informatie-over-waar-de-gebruiker-is-in-de-stappen-boven-het-formulier).
+
+## Error count in document title
+
+This component adds the error count to the document title,
+in line with [GOV.UK guidelines for informing users about validation errors](https://design-system.service.gov.uk/patterns/validation/#how-to-tell-the-user-about-validation-errors).
+
+## Focus on initial render
+
+This component receives focus the first time it gets displayed on a page.
+This allows keyboard users to quickly navigate to the errors in the form.
+It also scrolls the component into view if it isn't already.
+Note: this functionality has been disabled on this page, to prevent unexpected focus behaviour.
+
+## Relevant WCAG requirements
+
+Pay extra attention to these parts:
+
+- [WCAG requirement 1.3.1](https://www.w3.org/TR/WCAG21/#info-and-relationships): the heading level of the Form Error List depends on where in the page it is placed, this may differ per page.
+
+## References
+
+- [Show an error summary above the form - NL Design System](https://www.nldesignsystem.nl/richtlijnen/formulieren/foutmeldingen#zet-een-samenvatting-van-de-foutmeldingen-boven-het-formulier)
+- [Error Summary component - Gov.uk](https://design-system.service.gov.uk/components/error-summary/)

package/src/components/form-error-list/form-error-list.scss

@@ -0,0 +1,14 @@
+.ams-form-error-list {
+  outline-offset: var(--ams-form-error-list-outline-offset);
+
+  // In Chromium browsers, the outline overlaps with the border in this component.
+  // We're not sure why, but to fix this we double the offset for Chromium browsers here.
+  @supports (contain: paint) and (not (-moz-appearance: none)) {
+    outline-offset: calc(var(--ams-form-error-list-outline-offset) * 2);
+
+    // Reset for Safari
+    @supports (font: -apple-system-body) {
+      outline-offset: var(--ams-form-error-list-outline-offset);
+    }
+  }
+}

package/src/components/gap/README.md

@@ -2,4 +2,25 @@
 
 # Gap
 
-Use these utility classes to add consistent white space between a set of elements.
+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    | Preview                                                                                   |
+| ------------- | ----------------------------------------------------------------------------------------- |
+| `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);" /> |
+
+## 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.
+  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.
+  This may be preferable because it doesn’t change the parent’s display mode.

package/src/components/gap/gap.scss

@@ -10,7 +10,9 @@
 }
 
 @each $size in map-keys($ams-sizes) {
-  .ams-gap--#{$size} {
-    gap: var(--ams-gap-#{$size}) !important;
+  @if $size != "no" {
+    .ams-gap--#{$size} {
+      grid-gap: var(--ams-gap-#{$size}) !important;
+    }
   }
 }

package/src/components/grid/README.md

@@ -19,4 +19,4 @@ A cell often spans multiple columns of the grid.
 
 ## Design
 
-The [design choices](/docs/docs-design-guidelines-grid--docs) are described in the design guidelines.
+The [design choices](/docs/brand-design-tokens-grid--docs) are described in the general documentation.

package/src/components/header/README.md

@@ -2,13 +2,22 @@
 
 # Header
 
-Arranges the City’s logo, the title of the website, and a page menu.
+Displays the City’s logo at the top of every page, and optionally a navigation menu.
+Includes the name of the application if it is not the general website.
 
 ## Guidelines
 
-- Use the Header when the site is hosted on amsterdam.nl or one of its subdomains.
-- The page menu can contain a maximum of 5 items, including menu and search.
-- When you have a long subsite title, use no or as few page menu items as possible.
+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

@@ -47,14 +47,14 @@
   }
 }
 
-.ams-header__title {
+.ams-header__app-name {
   flex: 1 1 100%;
 
   @media screen and (min-width: $ams-breakpoint-wide) {
     min-inline-size: 0;
     order: 2;
 
-    .ams-header__title-heading {
+    .ams-header__app-name-heading {
       display: block;
       inline-size: 100%;
       line-height: 1;

package/src/components/heading/README.md

@@ -2,17 +2,18 @@
 
 # Heading
 
-A heading conveys information about the content below it.
-Use headings to allow the user to grasp the structure of the page quickly.
+Describes the content that follows it.
+Use Headings to allow the user to grasp the structure of the page quickly.
 
 ## Guidelines
 
 - A heading describes the content beneath it.
-- Do not use a heading for formatting and styling. Use it to represent the page’s structure.
-- Use headings hierarchically, and do not skip heading levels.
-  So, an `h1` heading should be followed by an `h2`, not an `h3`.
+- 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.
 
-## Relevant WCAG Requirements
+## Relevant WCAG requirements
 
 - [WCAG 1.3.1](https://www.w3.org/WAI/WCAG21/quickref/#qr-content-structure-separation-programmatic):
   Text that looks like a heading is also recognized as a heading by a computer.

package/src/components/heading/heading.scss

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

package/src/components/icon/README.md

@@ -6,7 +6,7 @@ Icons are visual symbols used to represent ideas, themes, or actions.
 They communicate the message at a glance and draw attention to important (interactive) information.
 Always use an `Icon` component to encapsulate an SVG icon for proper styling and sizing.
 
-## Interactive Elements
+## Interactive elements
 
 Use an icon to support textual interactive elements like buttons and links.
 Always try to provide accompanying text for an icon.
@@ -28,4 +28,8 @@ Icons are aligned to the left of the text by default and vertically centred to t
 
 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/docs-design-guidelines-typography--docs).
+[Refer to the typography documentation for more information](/docs/brand-design-tokens-text--docs).
+
+## Overview
+
+[You can find an overview of the available icons here](/docs/brand-assets-icons--docs).

package/src/components/icon-button/README.md

@@ -11,6 +11,6 @@ A button containing only an icon.
   Only use universally recognized icons, such as a close icon or a play icon.
 - Provide a label text that describes what the button does for screen reader users.
 
-## Relevant WCAG Requirements
+## Relevant WCAG requirements
 
 The Icon Button follows [the same requirements and guidelines as a regular button](/docs/components-buttons-button--docs).

package/src/components/image/README.md

@@ -17,7 +17,7 @@ Displays an image.
   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
+## 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.