Merge branch 'develop' into feature/DES-882-1-iterate-heading-props

# Conflicts:
#	packages/react/src/FormErrorList/FormErrorList.tsx

NOTICE.md

@@ -1,6 +1,6 @@
 <!-- @license CC0-1.0 -->
 
-# Terms of Use
+# Copyright
 
 ## Branding, logo and authors’ rights
 
@@ -9,11 +9,12 @@ Authors’ rights and trademark rights apply to the logo.
 If you intend to use a modified version of the software for other purposes, you are not allowed to use the City of Amsterdam’s logo.
 Instead, you should design your own branding.
 
-## Fonts
+## Typefaces
+
+Not all typefaces used in the branding are free and open source.
+Please note that you must arrange a (paid) license if you use the provided typefaces.
+Alternatively, adjust the configuration to use fewer or different typefaces.
 
-Not all fonts used in the branding are free and open source.
-Please note that you must arrange a (paid) license if you use the provided fonts.
-Alternatively, adjust the configuration to use fewer or different fonts.
 Amsterdam Sans is licensed exclusively to the City of Amsterdam and amsterdam&partners.
 
 ## Permission

README.md

@@ -13,19 +13,19 @@ We aim to create libraries for, or support otherwise, Figma, CSS, React, React N
 
 ## Related resources
 
-[A Storybook portal](https://amsterdam.github.io/design-system/) demonstrates our components and documentation.
+[A Storybook portal](https://designsystem.amsterdam/) demonstrates our components and documentation.
 
 [Our Figma file](https://www.figma.com/file/9IGm6IdPUYizBNGsUnueBd/Amsterdam-Design-System?type=design&node-id=741-19633&mode=design&t=N8P3h3W67O0KNdga-0) contains the design of our components and patterns.
 
 ## Getting started
 
-See the [getting started documentation for developers](https://designsystem.amsterdam/?path=/docs/docs-getting-started-developers--docs) on how to use our React components.
+See the [getting started documentation for developers](https://designsystem.amsterdam/?path=/docs/docs-developer-guide-getting-started--docs) on how to use our React components.
 
 ## Contributing
 
 See the [documentation for contributors](./CONTRIBUTING.md).
 
-## Code of Conduct
+## Code of conduct
 
 We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
 Read [our Code of Conduct](https://github.com/Amsterdam/.github/blob/main/CODE_OF_CONDUCT.md) if you haven’t already.

documentation/storybook.md

@@ -4,7 +4,7 @@
 
 We use Storybook to display all components and allow interaction with them.
 
-We publish each merge to the `main` branch to [amsterdam.github.io/design-system](https://amsterdam.github.io/design-system/).
+We publish each merge to the `main` branch to [designsystem.amsterdam](https://designsystem.amsterdam/).
 
 ## Structure
 

packages/css/src/common/size.scss

@@ -5,9 +5,9 @@
 
 /** The set of available options for sizing. */
 $ams-sizes: (
+  "no": "none",
   "xs": "extra-small",
   "sm": "small",
-  "md": "medium",
   "lg": "large",
   "xl": "extra-large",
 );

packages/css/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.

packages/css/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.

packages/css/src/components/column/column.scss

@@ -8,10 +8,11 @@
 .ams-column {
   display: flex;
   flex-direction: column;
+  gap: var(--ams-column-gap-md);
 }
 
 @each $size, $label in $ams-sizes {
-  .ams-column--#{$label} {
+  .ams-column--gap-#{$label} {
     gap: var(--ams-column-gap-#{$size});
   }
 }

packages/css/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                                                         |
 | :---------- | :--------------------------------------------------------------- |

packages/css/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.
 

packages/css/src/components/form-error-list/README.md

@@ -28,6 +28,13 @@ Put the Form Error List directly above the first question on the page. Place it
 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:

packages/css/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);
+    }
+  }
+}

packages/css/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/foundation-design-tokens-grid--docs) are described in the general documentation.

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

@@ -13,7 +13,7 @@ Use Headings to allow the user to grasp the structure of the page quickly.
 - 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.

packages/css/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).

packages/css/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,8 +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/foundation-design-tokens-text--docs).
 
 ## Overview
 
-[You can find an overview of the available icons here](/docs/docs-assets-icons--docs).
+[You can find an overview of the available icons here](/docs/foundation-assets-icons--docs).

packages/css/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.

packages/css/src/components/index.scss

@@ -4,6 +4,7 @@
  */
 
 /* Append here */
+@import "./form-error-list/form-error-list";
 @import "./table-of-contents/table-of-contents";
 @import "./error-message/error-message";
 @import "./file-input/file-input";

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

@@ -30,7 +30,7 @@ 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.
 
-## Relevant WCAG Requirements
+## Relevant WCAG requirements
 
 - [WCAG 1.4.3](https://www.w3.org/TR/WCAG21/#contrast-minimum)
 - [WCAG 2.4.4](https://www.w3.org/TR/WCAG21/#link-purpose-in-context)

packages/css/src/components/page-heading/README.md

@@ -11,7 +11,7 @@ Use this component for a name, title, or motto.
 - Only use this component once per page, typically only on the homepage.
 - Avoid using it if you need to display long pieces of text; the text should be short and precise.
 
-## Relevant WCAG Requirements
+## Relevant WCAG requirements
 
 The page heading component is a variant of a heading level 1 with a distinct style.
 When using this component, ensure that the heading hierarchy of the page remains logical.

packages/css/src/components/page-menu/README.md

@@ -13,8 +13,8 @@ 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.
 
-## Relevant WCAG Requirements
+## 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 interactive elements](/docs/docs-design-guidelines-interactive-elements--docs) apply.
+PageMenu is an interactive element, and the [general requirements and guidelines for interactivity](/docs/docs-developer-guide-interactivity--docs) apply.

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

@@ -17,6 +17,6 @@ Pagination indicates the current page and allows users to navigate to other page
 - Start a page with an overview list at the top after changing the page.
 - Make sure that the visible and accessible labels for the ‘previous’ and ‘next’ buttons convey the same meaning at all times – e.g. don’t update one and forget the other.
 
-## Relevant WCAG Rules
+## Relevant WCAG rules
 
-Pagination is an interactive element, and the [general requirements and guidelines for interactive elements](/docs/docs-design-guidelines-interactive-elements--docs) apply.
+Pagination is an interactive element, and the [general requirements and guidelines for interactivity](/docs/docs-developer-guide-interactivity--docs) apply.

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

@@ -11,7 +11,7 @@ Represents a paragraph of running text, form instructions, and other standalone
 - Consider whether a paragraph with more than 7 sentences or 140 words would be clearer if you divide the text into two paragraphs.
   Texts with not overly long paragraphs are easier to understand, and grouping makes information quicker to locate.
 
-## Relevant WCAG Rules
+## Relevant WCAG rules
 
 - [WCAG 1.3.1](https://www.w3.org/TR/WCAG21/#info-and-relationships): Blocks that look like a paragraph are also recognized by a computer as a paragraph.
 - [WCAG 1.4.3](https://www.w3.org/TR/WCAG21/#contrast-minimum): The contrast of black text on a white background is high enough.

packages/css/src/components/row/row.scss

@@ -8,14 +8,51 @@
 .ams-row {
   display: flex;
   flex-direction: row;
+  gap: var(--ams-row-gap-md);
 }
 
 @each $size, $label in $ams-sizes {
-  .ams-row--#{$label} {
+  .ams-row--gap-#{$label} {
     gap: var(--ams-row-gap-#{$size});
   }
 }
 
 .ams-row--wrap {
   flex-wrap: wrap;
 }
+
+.ams-row--align-around {
+  justify-content: space-around;
+}
+
+.ams-row--align-between {
+  justify-content: space-between;
+}
+
+.ams-row--align-center {
+  justify-content: center;
+}
+
+.ams-row--align-end {
+  justify-content: flex-end;
+}
+
+.ams-row--align-evenly {
+  justify-content: space-evenly;
+}
+
+.ams-row--align-vertical-baseline {
+  align-items: baseline;
+}
+
+.ams-row--align-vertical-center {
+  align-items: center;
+}
+
+.ams-row--align-vertical-end {
+  align-items: flex-end;
+}
+
+.ams-row--align-vertical-start {
+  align-items: flex-start;
+}

packages/css/src/components/search-field/README.md

@@ -32,4 +32,4 @@ These features can be disruptive for a user searching for part of a word, and `a
 - [WCAG 1.3.5](https://www.w3.org/TR/WCAG22/#identify-input-purpose): It is clear both to the user and programmatically what the purpose of a form field is.
 - [WCAG 2.4.6](https://www.w3.org/TR/WCAG22/#headings-and-labels): There is a label describing the purpose of the input.
 
-Search Field is an interactive element; therefore, [the general requirements and guidelines for interactive elements](/docs/docs-design-guidelines-interactive-elements--docs) apply.
+Search Field is an interactive element; therefore, [the general requirements and guidelines for interactivity](/docs/docs-developer-guide-interactivity--docs) apply.

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

@@ -8,7 +8,7 @@ Emphasizes a section on a page through a distinctive background colour.
 
 Refer to [this overview on Stijlweb](https://amsterdam.nl/stijlweb/basiselementen/kleuren/#PagCls_15671872) to determine whether you can use black or white text on the background colour of your choice.
 
-## Relevant WCAG Requirements
+## Relevant WCAG requirements
 
 - [WCAG 1.4.3](https://www.w3.org/TR/WCAG21/#contrast-minimum): Large-scale text and images of large-scale text have a contrast ratio of at least 3:1;
 

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

@@ -12,11 +12,11 @@ A switch applies to a page or the entire system, such as an on/off switch.
 - Use labels with a switch to make the action clear.
 - The action takes place immediately when the user operates the switch.
 
-## Relevant WCAG Requirements
+## Relevant WCAG requirements
 
 - [WCAG 1.3.5](https://www.w3.org/WAI/WCAG21/Understanding/identify-input-purpose.html): it is both clear for a user and programmatically what the purpose of a form field is.
 
-The Switch is an interactive element; general requirements and guidelines for interactive elements apply [here](/docs/docs-design-guidelines-interactive-elements--docs).
+Switch is an interactive element; general requirements and guidelines for interactivity apply [here](/docs/docs-developer-guide-interactivity--docs).
 
 ## References
 

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

@@ -4,7 +4,7 @@
 
 Tabs are used to bundle related content in a compact overview within a page. Each tab has a short name, and these names indicate the relationship between the information displayed in each tab.
 
-## How to Use
+## How to use
 
 - The content of each tab is viewable independently, not in the context of one another.
 - The content within each tab should have a similar structure.

packages/react/documentation/coding-conventions.md

@@ -36,7 +36,7 @@ Subcomponents (e.g. `Grid.Cell`) are kept in separate files (e.g. `GridCell.tsx`
 
 ## Text for screen readers only
 
-Use [Visually Hidden](https://amsterdam.github.io/design-system/?path=/docs/react_containers-visually-hidden--docs) or the `ams-visually-hidden` utility class to hide content from sighted users but keep it accessible to non-visual user agents, such as screen readers.
+Use [Visually Hidden](https://designsystem.amsterdam/?path=/docs/components-containers-visually-hidden--docs) or the `ams-visually-hidden` utility class to hide content from sighted users but keep it accessible to non-visual user agents, such as screen readers.
 
 Do not use `aria-label`. Tools for automatic translation often [do not translate its value](https://adrianroselli.com/2019/11/aria-label-does-not-translate.html), and it may get overlooked when doing manual translation.
 

packages/react/package.json

@@ -22,7 +22,7 @@
     "build:watch": "rollup -c --watch",
     "clean": "rimraf dist/",
     "lint": "tsc --project ./tsconfig.json --noEmit && tsc --noEmit --project ./tsconfig.test.json",
-    "test": "jest --verbose",
+    "test": "jest --verbose --coverage",
     "watch:test": "jest --verbose --watch"
   },
   "main": "./dist/index.cjs.js",

packages/react/src/Column/Column.test.tsx

@@ -18,7 +18,7 @@ describe('Column', () => {
 
     const component = container.querySelector(':only-child')
 
-    expect(component).toHaveClass('ams-column--medium')
+    expect(component).toHaveClass('ams-column')
   })
 
   columnGapSizes.map((size) =>
@@ -27,7 +27,7 @@ describe('Column', () => {
 
       const component = container.querySelector(':only-child')
 
-      expect(component).toHaveClass(`ams-column--${size}`)
+      expect(component).toHaveClass(`ams-column--gap-${size}`)
     }),
   )
 
@@ -36,7 +36,7 @@ describe('Column', () => {
 
     const component = container.querySelector(':only-child')
 
-    expect(component).toHaveClass('ams-column--medium extra')
+    expect(component).toHaveClass('ams-column extra')
   })
 
   it('renders with an article tag', () => {