@amsterdam/design-system-css 0.2.0 → 0.4.0

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.2.0",
+  "version": "0.4.0",
   "author": "Community for NL Design System",
   "description": "CSS files for components for the City of Amsterdam based on the NL Design System architecture",
   "license": "EUPL-1.2",
@@ -19,11 +19,11 @@
     "clean": "rimraf dist/"
   },
   "devDependencies": {
-    "@amsterdam/design-system-tokens": "0.2.0",
-    "sass": "1.69.5"
+    "@amsterdam/design-system-tokens": "0.4.0",
+    "sass": "1.70.0"
   },
   "dependencies": {
-    "@utrecht/components": "2.0.0"
+    "@utrecht/components": "3.0.0"
   },
-  "gitHead": "de071558a849af9c0f7b1a442b255a1a42d78f2f"
+  "gitHead": "3bc9765e9de9553db5b643d2ed79735837d4d7b6"
 }

package/src/components/accordion/README.md

@@ -1,42 +1,49 @@
 # Accordion
 
-Het accordion component is een klikbare (verticaal gestapelde) lijst van koppen om bijbehorende inhoud te verbergen of te tonen. Met een accordion toon je inhoud op een progressieve manier aan gebruikers.
-
-## Richtlijnen
-
-- Gebruik een accordion op een volle pagina met zowel essentiële als niet-essentiële inhoud. Door niet-essentiële inhoud te verbergen, komen gebruikers sneller bij de essentiële inhoud.
-- Gebruik een accordion niet om te veel essentiële inhoud op 1 pagina te voorkomen. Herschrijf de pagina compacter, verdeel de inhoud over meerdere pagina's of gebruik het (nog te maken) inhoudsopgave-component in plaats van een accordion voor dat doel. Verberg essentiële informatie niet in een accordion.
-- Een accordion bestaat uit meerdere accordionsecties. Gebruik minimaal 3 en maximaal 10 secties onder elkaar.
-- Het is belangrijk dat accordionsecties duidelijke koppen hebben, omdat de gebruiker de verborgen inhoud niet kan "scannen" om relevante informatie te vinden.
-- De inhoud verbergen heeft als nadeel dat "zoeken in pagina" geen resultaten oplevert voor de inhoud die verborgen is. Als je weet op welke zoekterm de gebruiker heeft gezocht om op de pagina met accordion te komen, dan kun je de secties die de zoekterm bevatten automatisch uitklappen.
-- De inhoud van de accordeon kan opmaak bevatten (bijvoorbeeld headings, lijsten, links en knoppen).
-
-Je kunt door een accordion navigeren met je toetsenbord:
-
-| key                  | element                                                                                                                      |
-| :------------------- | :--------------------------------------------------------------------------------------------------------------------------- |
-| Enter of Space       | Open of sluit de accordionsectie die de focus heeft                                                                          |
-| Tab                  | Ga naar het volgende element dat focus kan hebben                                                                            |
-| Shift + Tab          | Ga naar het volgende element dat focus kan hebben                                                                            |
-| Pijltje naar beneden | Als een accordionsectie focus heeft: ga naar de volgende sectie. Als de laatste sectie focus heeft, ga naar de eerste sectie |
-| Pijltje omhoog       | Als een accordionsectie focus heeft: ga naar de vorige sectie. Als de eerste sectie focus heeft, ga naar de laatste sectie   |
-| Home                 | Als een accordionsectie focus heeft: ga naar de eerste sectie                                                                |
-| End                  | Als een accordionsectie focus heeft: ga naar de laatste sectie                                                               |
-
-## Relevante WCAG eisen
-
-De WCAG eisen voor het Button component en het Heading component gelden ook voor de accordion header.
-
-Let extra op voor deze onderdelen:
-
-- [WCAG eis 1.3.1](https://www.w3.org/TR/WCAG21/#info-and-relationships): de _heading level_ van de accordionsecties is afhankelijk van waar in de pagina de accordion is geplaatst, dit kan per pagina verschillen.
-- [WCAG eis 1.3.6](https://www.w3.org/TR/WCAG21/#identify-purpose): gebruik `aria-controls` voor de button, en gebruik een `region` landmark voor de _expandable region_ (gebruik daarvoor het HTML-element `<section>`)
-- [WCAG eis 1.4.3](https://www.w3.org/TR/WCAG21/#contrast-minimum): contrast tussen tekst en achtergrond en tussen icoon en achtergrond is voldoende in alle varianten, alle interactieve statussen en alle mogelijke combinaties.
-- [WCAG eis 3.2.1](https://www.w3.org/TR/WCAG21/#on-focus): maak de accordion niet automatisch _expanded_ als de button focus krijgt.
-- [WCAG eis 2.1.3](https://www.w3.org/TR/WCAG21/#keyboard-no-exception): ondersteun ook de optionele toetsen: `Down Arrow`, `Up Arrow`, `Home` en `End`. `Space` moet de button activeren, niet de pagina scrollen (gebruik `keypressEvt.preventDefault()`).
-- [WCAG eis 2.4.6](https://www.w3.org/TR/WCAG21/#headings-and-labels): de tekst die zowel wordt gebruikt als heading en als label voor de button moet duidelijk zijn, omdat de inhoud niet altijd zichtbaar is.
-- [WCAG eis 2.4.10](https://www.w3.org/TR/WCAG21/#section-headings): accordions die onderdeel vormen van de lopende tekst moeten section headings gebruiken.
-
-## Referenties
+The accordion component is a clickable (vertically stacked) list of headings to hide or show associated content.
+With an accordion, you offer content to users progressively.
+
+## Guidelines
+
+- Use an accordion on a full page with essential and non-essential content.
+- Hiding non-essential content helps users get to important content more quickly.
+- Avoid using an accordion to avoid too much essential content on 1 page.
+- Rewrite the page more compactly or divide the content over multiple pages instead of using the accordion in the first place.
+- Don’t hide essential information in an accordion.
+- An accordion consists of several accordion sections.
+- Use a minimum of 3 and a maximum of 10 sections underneath each other.
+- It is essential for accordion sections to have clear headings, as the user cannot "scan" the hidden content to find relevant information.
+- Hiding the content has the disadvantage that "search in page" does not yield any hidden content results.
+- If you know the search term the user used to get to the accordion page, you can automatically expand the sections that contain the search term.
+- The accordion’s content may contain formatting (e.g. headings, lists, links and buttons).
+
+You can navigate an accordion with your keyboard:
+
+| key            | element                                                                                                               |
+| :------------- | :-------------------------------------------------------------------------------------------------------------------- |
+| Enter or Space | Open or close the accordion section that has the focus                                                                |
+| Tab            | Go to the next element that can have focus                                                                            |
+| Shift + Tab    | Go to the next element that can have focus                                                                            |
+| Down arrow     | If an accordion section has focus, go to the next section; if the last section has focus, go to the first section     |
+| Up arrow       | If an accordion section has focus, go to the previous section; if the first section has focus, go to the last section |
+| Home           | If an accordion section has focus: go to the first section                                                            |
+| End            | If an accordion section has focus, go to the last section                                                             |
+
+## Relevant WCAG requirements
+
+The WCAG requirements for the Button and Heading components also apply to the accordion header.
+
+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 accordion sections depends on where in the page the accordion is placed, this may differ per page.
+- [WCAG requirement 1.3.6](https://www.w3.org/TR/WCAG21/#identify-purpose): use `aria-controls` for the button, and use a `region` landmark for the expandable region (use the HTML element `<section>` for this)
+- [WCAG requirement 1.4.3](https://www.w3.org/TR/WCAG21/#contrast-minimum): contrast between text and background and between icon and background is sufficient in all variants, all interactive statuses and all possible combinations.
+- [WCAG requirement 3.2.1](https://www.w3.org/TR/WCAG21/#on-focus): do not automatically make the accordion expanded when the button gets focus.
+- [WCAG requirement 2.1.3](https://www.w3.org/TR/WCAG21/#keyboard-no-exception): Support the optional keys: `Down Arrow`, `Up Arrow`, `Home` and `End`.
+- `Space` should activate the button, not scroll the page (use `keypressEvt.preventDefault()`).
+- [WCAG requirement 2.4.6](https://www.w3.org/TR/WCAG21/#headings-and-labels): The text used both as a heading and as a label for the button must be clear because the content is not always visible.
+- [WCAG requirement 2.4.10](https://www.w3.org/TR/WCAG21/#section-headings): accordions that are part of the running text must use section headings.
+
+## References
 
 - [W3C - Accordion Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/)

package/src/components/alert/README.md

@@ -1,18 +1,22 @@
 # Alert
 
-Met een Alert breng je de gebruiker op de hoogte van een belangrijke of tijdgevoelige boodschap. De taak van de gebruiker wordt niet onderbroken.
+An Alert informs the user of a significant or time-sensitive message without interrupting their task.
 
-## Specificaties
+## Specifications
 
-### Kleurdefinities
+There are four types of notifications:
 
-- Geel: informatie
-- Rood: fout
-- Groen: goed
+- **Warning** (orange) when action is needed to prevent damage.
+- **Error** (red) indicates an error has occurred.
+- **Confirmation** (green) to reassure that a process is complete.
+- **Notification** (blue) to bring attention to a message.
 
-## Richtlijnen
+## Guidelines
 
-- Standaard heeft het element geen sluiten knop. Optioneel kan deze toegevoegd worden.
-- Optioneel kan een icoon worden weggelaten. Een geel Alert heeft nooit een icoon.
-- Optioneel kan een titel worden weggelaten.
-- Aangeraden wordt om een Alert in ieder geval van een paragraaf text te voorzien en deze eventueel te ondersteunen met een link, opsomming of knop.
+- Place an orange Alert directly below the Header for important and urgent information.
+  Examples: system outage or changes in the opening hours of a City Office.
+- Ensure sufficient whitespace around the Alert.
+  The grid’s whitespace is a good reference – place the Alert in its own cell.
+- By default, the Alert cannot be closed.
+  This functionality can be added optionally.
+- Optionally, the title can be omitted.

package/src/components/alert/alert.scss

@@ -5,8 +5,8 @@
 
 .amsterdam-alert {
   align-items: flex-start;
-  background-color: var(--amsterdam-alert-background-color);
-  border: var(--amsterdam-alert-border);
+  border-style: var(--amsterdam-alert-border-style);
+  border-width: var(--amsterdam-alert-border-width);
   display: flex;
   flex-direction: row;
   gap: var(--amsterdam-alert-gap);
@@ -21,48 +21,18 @@
   flex: auto;
 }
 
-@mixin reset {
-  -webkit-text-size-adjust: 100%;
-}
-
-.amsterdam-alert__title {
-  color: var(--amsterdam-alert-title-color);
-  font-family: var(--amsterdam-alert-title-font-family);
-  font-size: var(--amsterdam-alert-title-spacious-font-size);
-  font-weight: var(--amsterdam-alert-title-font-weight);
-  line-height: var(--amsterdam-alert-title-spacious-line-height);
-
-  .amsterdam-theme--compact & {
-    font-size: var(--amsterdam-alert-title-compact-font-size);
-    line-height: var(--amsterdam-alert-title-compact-line-height);
-  }
-
-  @include reset;
-}
-
 .amsterdam-alert--error {
-  background-color: var(--amsterdam-alert-error-background-color);
   border-color: var(--amsterdam-alert-error-border-color);
 }
 
-.amsterdam-alert--success {
-  background-color: var(--amsterdam-alert-success-background-color);
-  border-color: var(--amsterdam-alert-success-border-color);
-}
-
-/* todo: move to action button component */
-.amsterdam-alert__close {
-  background-color: var(--amsterdam-alert-close-background-color);
-  border: 0;
-  cursor: pointer;
-  padding-block: 0;
-  padding-inline: 0;
+.amsterdam-alert--info {
+  border-color: var(--amsterdam-alert-info-border-color);
 }
 
-.amsterdam-alert__close svg {
-  fill: var(--amsterdam-alert-close-fill);
+.amsterdam-alert--success {
+  border-color: var(--amsterdam-alert-success-border-color);
 }
 
-.amsterdam-alert__close:hover svg {
-  fill: var(--amsterdam-alert-close-hover-fill);
+.amsterdam-alert--warning {
+  border-color: var(--amsterdam-alert-warning-border-color);
 }

package/src/components/aspect-ratio/README.md

@@ -1,18 +1,18 @@
 # Aspect Ratio
 
-Aspect Ratio (in het Nederlands: beeldverhouding) koppelt de hoogte van een element aan de breedte.
+Aspect Ratio updates the height of an element with its width.
 
-Om de vormgeving consistent te houden gebruiken we een vaste set verhoudingen (breedte:hoogte):
+These are the proportions we use:
 
-| _keyword_ | verhouding |
-| :-------- | ---------: |
-| `2x-wide` |       32:9 |
-| `x-wide`  |       16:9 |
-| `wide`    |        5:4 |
-| `square`  |        1:1 |
-| `tall`    |        4:5 |
-| `x-tall`  |       9:16 |
+| keyword   | ratio |
+| :-------- | ----: |
+| `2x-wide` |  32:9 |
+| `x-wide`  |  16:9 |
+| `wide`    |   5:4 |
+| `square`  |   1:1 |
+| `tall`    |   4:5 |
+| `x-tall`  |  9:16 |
 
-## Richtlijnen
+## Guidelines
 
-- Gebruik dit component om plaatjes, videos en andere elementen een vaste beeldverhouding te geven, zodat ze consistent schalen.
+- Use this component to constrain images, videos and other elements to one of the available aspect ratios.

package/src/components/badge/README.md

@@ -0,0 +1,10 @@
+# Badge
+
+A prominently coloured box containing 1 or 2 words.
+Guides the user in taking a specific action or describes its surrounding content.
+
+## Design
+
+The badge can contain a short text or a number.
+The default background colour is dark green.
+Suggestions on when to use the other colours will follow soon.

package/src/components/badge/badge.scss

@@ -0,0 +1,58 @@
+/**
+ * @license EUPL-1.2+
+ * Copyright (c) 2024 Gemeente Amsterdam
+ */
+
+.amsterdam-badge {
+  display: inline-block;
+  font-family: var(--amsterdam-badge-font-family);
+  font-size: var(--amsterdam-badge-spacious-font-size);
+  font-weight: var(--amsterdam-badge-font-weight);
+  line-height: var(--amsterdam-badge-spacious-line-height);
+  padding-inline: var(--amsterdam-badge-padding-inline);
+
+  .amsterdam-theme--compact & {
+    font-size: var(--amsterdam-badge-compact-font-size);
+    line-height: var(--amsterdam-badge-compact-line-height);
+  }
+}
+
+.amsterdam-badge--blue {
+  background-color: var(--amsterdam-badge-blue-background-color);
+  color: var(--amsterdam-badge-blue-color);
+}
+
+.amsterdam-badge--dark-blue {
+  background-color: var(--amsterdam-badge-dark-blue-background-color);
+  color: var(--amsterdam-badge-dark-blue-color);
+}
+
+.amsterdam-badge--dark-green {
+  background-color: var(--amsterdam-badge-dark-green-background-color);
+  color: var(--amsterdam-badge-dark-green-color);
+}
+
+.amsterdam-badge--green {
+  background-color: var(--amsterdam-badge-green-background-color);
+  color: var(--amsterdam-badge-green-color);
+}
+
+.amsterdam-badge--magenta {
+  background-color: var(--amsterdam-badge-magenta-background-color);
+  color: var(--amsterdam-badge-magenta-color);
+}
+
+.amsterdam-badge--orange {
+  background-color: var(--amsterdam-badge-orange-background-color);
+  color: var(--amsterdam-badge-orange-color);
+}
+
+.amsterdam-badge--purple {
+  background-color: var(--amsterdam-badge-purple-background-color);
+  color: var(--amsterdam-badge-purple-color);
+}
+
+.amsterdam-badge--yellow {
+  background-color: var(--amsterdam-badge-yellow-background-color);
+  color: var(--amsterdam-badge-yellow-color);
+}

package/src/components/blockquote/README.md

@@ -1,14 +1,14 @@
 # Blockquote
 
-De blockquote (in het Nederlands: citaat) wordt gebruikt om uitspraken te accentueren. Een citaat is anders vormgegeven dan de broodtekst, zodat deze opvalt.
+We use blockquotes to emphasize citations.
+A quote appears differently from the main text to make it stand out.
 
-Let op: dit component voegt automatisch aanhalingstekens aan de tekst toe, dat hoef je niet zelf te doen.
+## Guidelines
 
-## Richtlijnen
+- Quote someone’s literal written or oral text.
+- A quote has a width of half or a whole column of text.
+- The component adds the correct quotation marks.
 
-- Bij een citaat haal je letterlijk een schriftelijke of mondelinge tekst van iemand aan.
-- Een citaat heeft een breedte van een halve of hele tekstkolom.
+## Relevant WCAG requirements
 
-## Relevante WCAG eisen
-
-- [WCAG 3.1.2](https://www.w3.org/WAI/WCAG21/Understanding/language-of-parts.html): wanneer het citaat in een andere taal is geschreven dan de pagina, dan moet het `lang` attribuut gebruikt worden om de taal duidelijk te maken.
+- [WCAG 3.1.2](https://www.w3.org/WAI/WCAG21/Understanding/language-of-parts.html): if the citation is in a language other than that of the surrounding content, indicate so through the `lang` attribute.

package/src/components/breadcrumb/README.md

@@ -1,15 +1,18 @@
 # Breadcrumb
 
-De breadcrumb (in het Nederlands: kruimelpad) is een secundair navigatiepatroon dat een gebruiker helpt de structuur tussen niveaus in de website tot de huidige pagina te begrijpen. Gebruikers kunnen het gebruiken om door de structuur te navigeren.
+The breadcrumb is a secondary navigation pattern that helps a user understand the structure between levels in the website up to the current page.
+Users can use it to navigate.
 
-## Richtlijnen
+## Guidelines
 
-### Zo gebruiken
+### Use like this
 
-Gebruik het kruimelpad alleen als het functioneel iets toevoegt voor de gebruiker en als de structuur ‘statisch’ is.
+Only use the breadcrumb trail if it adds something functional for the user and the structure is ‘static’.
 
-### Dit vermijden
+### Avoid this
 
-Het kruimelpad wordt niet ingezet op een formulierpagina. Het leidt af van de taak van de gebruiker of kan per ongeluk als Progress Indicator gezien worden.
+Do not display the breadcrumb trail on a form page.
+It distracts the user from their task, or one can accidentally interpret it as a Progress Indicator.
 
-Het is een secundair navigatiepatroon. Het mag nooit de hoofdnavigatie vervangen.
+It is a secondary navigation pattern.
+It can’t replace the main navigation.

package/src/components/breadcrumb/breadcrumb.scss

@@ -25,27 +25,22 @@
 .amsterdam-breadcrumb__list {
   break-after: avoid;
   break-inside: avoid;
-  display: flex;
-  flex-wrap: wrap;
-  gap: 0.5rem;
-  list-style: none;
 
   @include reset;
 }
 
 .amsterdam-breadcrumb__item {
-  align-items: center;
-  display: flex;
+  display: inline;
 }
 
 .amsterdam-breadcrumb__item:not(:last-child)::after {
-  background-color: var(--amsterdam-breadcrumb-separator-background-color);
-  clip-path: path("M 4.725,16 3.275,14.545 9.815,8 3.275,1.455 4.725,0 l 8,8 z");
+  background-image: var(--amsterdam-breadcrumb-separator-background-image);
+  background-repeat: no-repeat;
   content: "";
   display: inline-block;
-  height: 1rem;
-  margin-inline-start: 1rem;
-  width: 1rem;
+  height: 1ex;
+  margin-inline: 0.5rem;
+  width: 1ex;
 }
 
 .amsterdam-breadcrumb__link {
@@ -55,10 +50,6 @@
   text-decoration-thickness: var(--amsterdam-breadcrumb-item-link-text-decoration-thickness);
   text-underline-offset: var(--amsterdam-breadcrumb-item-link-text-underline-offset);
 
-  &::first-letter {
-    text-transform: capitalize;
-  }
-
   &:hover {
     color: var(--amsterdam-breadcrumb-item-link-hover-color);
     text-decoration-line: var(--amsterdam-breadcrumb-item-link-hover-text-decoration-line);

package/src/components/button/README.md

@@ -1,24 +1,27 @@
 # Button
 
-De button gebruik je zodat de gebruiker acties kan uit te voeren en de user interface kan bedienen.
+Allows the user to perform actions and operate the user interface.
 
-## Richtlijnen
+## Guidelines
 
-- Een label tekst die beschrijft wat de functie van de button is.
-- Een duidelijke constrasterende kleurstelling zodat deze goed te herkennen is en snel te lokaliseren valt.
-- Gebruik het juiste type button voor de daarbijhorende toepassing. Bijvoorbeeld een button binnen een formulier moet altijd het het type `submit` zijn.
-- Zorg dat een button ook met een keyboard te bedienen is.
+- A label text that describes the function of the button.
+- A clear contrasting colour scheme so that it is easy to recognize and quickly locate.
+- Use the correct type of button for the corresponding application.
+  For example, a button within a form must always be of the type `submit`.
+- Make sure one can operate a button through a keyboard.
 
-## Relevante WCAG eisen
+## Relevant WCAG requirements
 
-- [WCAG eis 2.1.3](https://www.w3.org/TR/WCAG21/#keyboard-no-exception): je kan de button activeren met `Enter` of `Space`, en het is mogelijk met `Tab` de button te focussen. `Space` gebruiken heeft dan niet het effect dat de pagina scrollt.
-- [WCAG eis 2.4.6](https://www.w3.org/TR/WCAG21/#headings-and-labels): de label van de button moet duidelijk zijn
-- [WCAG eis 2.5.2](https://www.w3.org/TR/WCAG21/#pointer-cancellation):
-  - gebruik niet de `mousedown` event om de button te activeren, gebruik liever de `click` event
-  - `mousedown` mag alleen gebruikt worden als `mouseup` het effect weer ongedaan maakt, bijvoorbeeld een "_fast foward_" button om audio of video door te spoelen.
-- [WCAG eis 2.5.5](https://www.w3.org/TR/WCAG21/#target-size): de button moet groot genoeg zijn om aan te klikken, en kleine buttons moeten niet te dicht op een andere button staan.
+- [WCAG requirement 2.1.3](https://www.w3.org/TR/WCAG21/#keyboard-no-exception):
+  You can activate the button with `Enter` or `Space`, and it is possible with ‘Tab’ the button to focus.
+  Using `Space` does not result in scrolling the page.
+- [WCAG requirement 2.4.6](https://www.w3.org/TR/WCAG21/#headings-and-labels): the label of the button must be clear
+- [WCAG requirement 2.5.2](https://www.w3.org/TR/WCAG21/#pointer-cancellation):
+  - do not use the `mousedown` event to activate the button, instead use the `click` event
+  - `mousedown` may only be used if `mouseup` undoes the effect, for example, a “fast forward” button to fast-forward audio or video.
+- [WCAG requirement 2.5.5](https://www.w3.org/TR/WCAG21/#target-size): The button must be large enough to click, and small buttons should not be too close to another button.
 
-## Referenties
+## References
 
 - [W3C - Focus Visible](https://www.w3.org/WAI/WCAG21/Understanding/focus-visible.html)
 - [W3C - Headings & labels](https://www.w3.org/TR/WCAG21/#headings-and-labels)

package/src/components/card/README.md

@@ -1,12 +1,24 @@
 # Card
 
-Gebruik een card op een overzichtspagina om te verwijzen naar een detailpagina, zoals een nieuwsbericht, een vacature of een zoekresultaat. De card bevat meestal de titel, introductie en afbeelding van de content. De link is verplicht.
+Use a card on an overview page to link to an article page, such as a news article, a job vacancy, or a search result.
+The card typically includes the title, introduction, and an image of the content.
+The link is mandatory.
 
-## Schermlezers
+## Guidelines
 
-Met een schermlezer kun je onder andere navigeren via headings en links in een document. De titel van een card is een link in een heading, zodat je van beide navigatiemanieren gebruik kunt maken. Een schermlezer leest eerst de titel op, daarna de rest van de inhoud.
+- The title of a card is a link within a heading.
+  The same guidelines as for regular [links](?path=/docs/react_navigation-link--docs) and [headings](?path=/docs/react_text-heading--docs) apply here.
+  The link is active across the entire area of the card.
+- A card needs more content than just a title.
+  Supplement this with textual and/or visual content.
+- Place the text in a regular paragraph.
+  Only use the smallest text size for a tagline or date.
+- This component may not be the best option if the content does not represent a detailed page.
+  For referencing a thematic page, use a [top task link](?path=/docs/react_navigation-top-task-link--docs).
+  You can also use a [regular link](?path=/docs/react_navigation-link--docs).
 
-## Richtlijnen
+## Screen Readers
 
-- De titel van een card is een link in een heading. Hier gelden dezelfde richtlijnen voor als voor reguliere [links](https://amsterdam.github.io/design-system/?path=/docs/react_navigation-link--docs) en [headings](https://amsterdam.github.io/design-system/?path=/docs/react_text-heading--docs).
-- Een card heeft meer inhoud nodig dan alleen een titel. Vul dit aan met tekstuele en/of visuele inhoud. Als dit lastig is, kijk dan of een [top task link](https://amsterdam.github.io/design-system/?path=/docs/react_navigation-top-task-link--docs) of [reguliere link](https://amsterdam.github.io/design-system/?path=/docs/react_navigation-link--docs) beter past.
+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.
+A screen reader reads the title first, followed by the rest of the content.

package/src/components/checkbox/README.md

@@ -1,27 +1,28 @@
 # Checkbox
 
-De checkbox (in het Nederlands: selectievakje) wordt gebruikt om gebruikers een selectie te laten maken. Hij wordt ook gebruikt om gebruikers te laten weten dat ze akkoord gaan met specifieke voorwaarden.
+Allows users to make a selection or agree to terms.
 
-## Richtlijnen
+## Guidelines
 
-- Selectievakjes worden gebruikt voor 1 of meerdere keuzes die elkaar niet uitsluiten.
-- Elk selectievakje werkt onafhankelijk van andere selectievakjes in een lijst op hetzelfde hiërarchische niveau. Het aanvinken van een extra vakje heeft geen invloed op andere selecties in die lijst.
-- Je kunt een selectievakje wel gebruiken voor een bulkselectie of –deselectie van een hele lijst met selectievakjes, maar dan moet duidelijk zijn dat het bulkselectievakje op een ander hiërarchisch niveau zit dan de lijst die volledig wordt geselecteerd of gedeselecteerd.
-- Een groep selectievakjes kan worden gebruikt om gegevens op een pagina, in een menu of binnen een component te filteren.
-- Een selectievakje kan een antwoord op een gesloten vraag zijn, als er meerdere antwoorden mogelijk zijn.
-- Een lijst van selectievakjes is verticaal gestapeld om leesbaarheid en bruikbaarheid te bevorderen.
-- Een lijst van selectievakjes moet in een `fieldset` zitten, met een `legend` die beschrijft waar de lijst over gaat. Als de selectievakjes bijvoorbeeld worden gebruikt om antwoord op een vraag te krijgen, dan is de `legend` de vraag.
+- Checkboxes are used for one or multiple choices that do not exclude each other.
+- Each checkbox operates independently of other checkboxes in a list at the same hierarchical level.
+  Checking an additional checkbox does not affect other selections in that list.
+- You can use a checkbox for bulk selection or deselection of an entire list of checkboxes.
+  Still, it should be clear that the bulk selection checkbox is at a different hierarchical level than the list being fully selected or deselected.
+- Use a group of checkboxes to filter data on a page, in a menu, or within a component.
+- A checkbox can answer a closed question if multiple answers are possible.
+- A list of checkboxes is vertically stacked to enhance readability and usability.
+- 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
 
-Een label:
+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.
 
-- ... begint met een hoofdletter
-- ... heeft geen interpunctie aan het einde als het een enkele zin, woord of fragment is.
-- ... is in de eerste persoon geschreven als het gaat om de vraag of de gebruiker akkoord gaat met de algemene voorwaarden
+## Relevant WCAG Requirements
 
-## Relevante WCAG eisen
+- [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.
 
-- [WCAG 1.3.5](https://www.w3.org/WAI/WCAG21/Understanding/identify-input-purpose.html): het is zowel voor een gebruiker als programmatisch duidelijk wat het doel van een formulierveld is.
-
-Checkbox is een interactief element, hier gelden [de algemene eisen en richtlijnen voor interactieve elementen](https://amsterdam.github.io/design-system/?path=/docs/docs-designrichtlijnen-interactieve-elementen--docs) voor.
+Checkbox is an interactive element; therefore, [the general requirements and guidelines for interactive elements](https://amsterdam.github.io/design-system/?path=/docs/docs-designrichtlijnen-interactieve-elementen--docs) apply.

package/src/components/checkbox/checkbox.scss

@@ -53,9 +53,9 @@
 
   &:hover {
     color: var(--amsterdam-checkbox-hover-color);
-    text-decoration: underline;
-    text-decoration-thickness: 2px;
-    text-underline-offset: 3px;
+    text-decoration-line: underline;
+    text-decoration-thickness: 0.125rem;
+    text-underline-offset: 0.375rem;
 
     .amsterdam-checkbox__checkmark::after {
       border-color: var(--amsterdam-checkbox-checkmark-hover-border-color);

package/src/components/dialog/README.md

@@ -1,19 +1,20 @@
 # Dialog
 
-A Dialog allows the user to focus on one task or a piece of information, by popping-up and blocking the page content until the modal task is completed, or until the user dismisses the action.
+A Dialog allows the user to focus on one task or a piece of information by popping up and blocking the page content until the modal task is completed or until the user dismisses the action.
 
 ## Guidelines
 
-- Use Dialog sparingly, because it interrupts the user's workflow.
-- Use Dialog for short and non-frequent tasks. For common tasks consider using the main flow.
+- Use dialogs sparingly because they interrupt the user’s workflow.
+- Use a dialog for short and non-frequent tasks.
+  Consider using the main flow for regular tasks.
 
 ## Keyboard Support
 
-| key         | function                                                     |
-| :---------- | :----------------------------------------------------------- |
-| Tab         | Moves focus to next focusable element inside the dialog.     |
-| Shift + Tab | Moves focus to previous focusable element inside the dialog. |
-| Escape      | Closes the dialog.                                           |
+| key         | function                                                         |
+| :---------- | :--------------------------------------------------------------- |
+| Tab         | Moves focus to the next focusable element inside the dialog.     |
+| Shift + Tab | Moves focus to the previous focusable element inside the dialog. |
+| Escape      | Closes the dialog.                                               |
 
 ## References