@amsterdam/design-system-css 0.2.0 → 0.4.0

package/src/components/dialog/dialog.scss

@@ -68,26 +68,9 @@
   display: flex;
   flex-direction: column;
   grid-gap: var(--amsterdam-dialog-footer-gap);
-  padding-block: var(--amsterdam-dialog-footer-padding-block);
 
   @media screen and (min-width: $amsterdam-breakpoint-medium) {
     flex-direction: row;
     justify-content: end;
   }
 }
-
-.amsterdam-dialog__close {
-  background-color: var(--amsterdam-dialog-close-background-color);
-  border: 0;
-  cursor: pointer;
-  padding-block: 0;
-  padding-inline: 0;
-}
-
-.amsterdam-dialog__close svg {
-  fill: var(--amsterdam-dialog-close-fill);
-}
-
-.amsterdam-dialog__close:hover svg {
-  fill: var(--amsterdam-dialog-close-hover-fill);
-}

package/src/components/footer/README.md

@@ -1,11 +1,15 @@
 # Footer
 
-De footer (in het Nederlands: voettekst) sluit iedere webpagina af. De inhoud is service-informatie. Een gedeelte is voorgeschreven en een deel wordt ingevuld vanuit de doelstelling van de website.
+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.
 
-## Richtlijnen
+## Guidelines
 
-- De voettekst is verplicht, er staat er 1 op elke pagina.
-- De eerste kolom richt zich op contactinformatie. De informatie is zo specifiek mogelijk gebonden aan de betreffende website of pagina (bijvoorbeeld een chatmogelijkheid indien aanwezig).
-- De tweede kolom bevat links naar relevante (online) sites of bronnen.
-- De derde kolom verwijst naar nieuwsbrieven, socials enz.
-- Het laatste deel van de voettekst is bedoeld voor koppelingen naar privacy, cookieverklaring, uitleg over de website e.d. Het is niet bedoeld voor koppelingen naar bijvoorbeeld contactinformatie.
+- The footer is mandatory, and there is one on every page.
+- 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.

package/src/components/form-label/README.md

@@ -1,3 +1,7 @@
 # Form Label
 
-Een label element gebruik je om een formulierelement te beschrijven. Koppel een formulierelement (zoals een `input` of `textarea`) altijd aan een label.
+Describes a form control.
+
+## Guidelines
+
+Always associate a form element (such as an `input` or `textarea`) with a label.

package/src/components/grid/README.md

@@ -0,0 +1,20 @@
+# Grid
+
+Divides the screen into columns to align the elements of a page.
+
+## Usage
+
+Every page should use the grid as the foundation for its layout.
+It is placed directly within the [Screen](?path=/docs/layout-screen--docs).
+
+A [Footer](?path=/docs/react_containers-footer--docs) and a [Spotlight](?path=/docs/react_containers-spotlight--docs) are slightly wider than the grid.
+You close one instance of the grid before these components.
+Inside and optionally after them, you start a new one.
+Multiple instances of the grid component are possible on a page, but the columns of all grids must align precisely.
+
+Within the grid, you create cells containing the desired content.
+A cell often spans multiple columns of the grid.
+
+## Design
+
+The [design choices](?path=/docs/docs-designrichtlijnen-grid--docs) are described in the design guidelines.

package/src/components/grid/grid.scss

@@ -28,6 +28,10 @@
   --amsterdam-grid-padding-inline: var(--amsterdam-grid-compact-padding-inline);
 }
 
+.amsterdam-grid--gap-vertical--none {
+  row-gap: initial;
+}
+
 .amsterdam-grid--gap-vertical--small {
   row-gap: calc(var(--amsterdam-grid-gap) / 2);
 }
@@ -71,3 +75,43 @@
 .amsterdam-grid--padding-vertical--large {
   padding-block: calc(var(--amsterdam-grid-gap) * 2);
 }
+
+.amsterdam-grid__cell--span-all {
+  grid-column: 1 / -1;
+}
+
+// The order of the following declaration blocks ensures the intended specificity.
+
+@for $i from 1 through 12 {
+  .amsterdam-grid__cell--span-#{$i} {
+    grid-column-end: span $i;
+  }
+
+  .amsterdam-grid__cell--start-#{$i} {
+    grid-column-start: $i;
+  }
+}
+
+@media screen and (min-width: $amsterdam-breakpoint-medium) {
+  @for $i from 1 through 12 {
+    .amsterdam-grid__cell--span-#{$i}-medium {
+      grid-column-end: span $i;
+    }
+
+    .amsterdam-grid__cell--start-#{$i}-medium {
+      grid-column-start: $i;
+    }
+  }
+}
+
+@media screen and (min-width: $amsterdam-breakpoint-wide) {
+  @for $i from 1 through 12 {
+    .amsterdam-grid__cell--span-#{$i}-wide {
+      grid-column-end: span $i;
+    }
+
+    .amsterdam-grid__cell--start-#{$i}-wide {
+      grid-column-start: $i;
+    }
+  }
+}

package/src/components/header/README.md

@@ -0,0 +1,14 @@
+# Header
+
+Arranges the City’s logo, the title of the website, and a page menu.
+
+## 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.
+
+## References
+
+- A Header is a [landmark](https://www.w3.org/TR/wai-aria-practices-1.1/#aria_landmark_roles) and can be use to group navigation elements.
+- [WCAG 3.2.3](https://wcag.com/designers/3-2-3-consistent-navigation/) Consistent Navigation: Navigation menus that appear on multiple pages are consistent.

package/src/components/header/header.scss

@@ -0,0 +1,85 @@
+/**
+ * @license EUPL-1.2+
+ * Copyright (c) 2023 Gemeente Amsterdam
+ */
+
+@import "../../common/breakpoint";
+
+.amsterdam-header {
+  align-items: center;
+  display: flex;
+  flex-wrap: wrap;
+  padding-block: 1rem;
+  row-gap: 1.5rem;
+
+  @media screen and (min-width: $amsterdam-breakpoint-wide) {
+    column-gap: var(--amsterdam-header-column-gap);
+    flex-wrap: nowrap;
+  }
+}
+
+.amsterdam-header__logo {
+  flex: none;
+  outline-offset: var(--amsterdam-link-outline-offset);
+}
+
+.amsterdam-header__links {
+  display: none;
+
+  @media screen and (min-width: $amsterdam-breakpoint-medium) {
+    display: block;
+    flex: 10 0 auto;
+  }
+
+  @media screen and (min-width: $amsterdam-breakpoint-wide) {
+    order: 3;
+  }
+}
+
+.amsterdam-header__menu {
+  flex: 1;
+  padding-inline-start: var(--amsterdam-page-menu-column-gap);
+  text-align: end;
+
+  @media screen and (min-width: $amsterdam-breakpoint-wide) {
+    order: 4;
+    padding-inline-start: 0;
+  }
+}
+
+.amsterdam-header__title {
+  flex: 1 1 100%;
+
+  @media screen and (min-width: $amsterdam-breakpoint-wide) {
+    min-width: 0;
+    order: 2;
+
+    .amsterdam-header__title-heading {
+      display: block;
+      line-height: 1;
+      overflow: hidden;
+      text-overflow: ellipsis;
+      white-space: nowrap;
+      width: 100%;
+    }
+  }
+}
+
+// Temporary, will move to megamenu (and/or iconButton)
+.amsterdam-header__menu-button {
+  background-color: transparent;
+  background-image: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'><path fill='%23004699' fill-rule='evenodd' d='M0 3.238h32V7.81H0V3.238zm0 10.476h32v4.572H0v-4.572zM0 24.19h32v4.572H0V24.19z'/></svg>");
+  background-position: center right;
+  background-repeat: no-repeat;
+  background-size: 19px 19px;
+  border: 0;
+  color: var(--amsterdam-page-menu-item-color);
+  font-family: var(--amsterdam-page-menu-item-font-family);
+  font-size: var(--amsterdam-page-menu-item-spacious-font-size);
+  font-weight: var(--amsterdam-page-menu-item-font-weight);
+  line-height: var(--amsterdam-page-menu-item-spacious-line-height);
+  margin-block: 0;
+  padding-inline: 0 30px;
+  text-align: center;
+  touch-action: manipulation;
+}

package/src/components/heading/README.md

@@ -1,22 +1,25 @@
 # Heading
 
-Een heading zegt iets over de onderstaande content. Met behulp van headings kan de gebruiker snel een overzicht krijgen van de structuur van de webpagina.
+A heading conveys information about the content below it.
+Use headings to allow the user to grasp the structure of the page quickly.
 
-## Richtlijnen
+## Guidelines
 
-- Een heading omschrijft de content eronder.
-- Gebruik een heading niet voor opmaak en styling, maar om de structuur van de pagina weer te geven.
-- Gebruik headings hierarchisch en sla geen heading niveaus over. Dus na een `h1` volgt een `h2` en dus niet een `h3`.
+- 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`.
 
-## Relevante WCAG eisen
+## Relevant WCAG Requirements
 
 - [WCAG 1.3.1](https://www.w3.org/WAI/WCAG21/quickref/#qr-content-structure-separation-programmatic):
-  Tekst die er uit ziet als een heading wordt ook door een computer herkend als een heading. Door gebruik te maken van het juiste heading niveau is voor alle gebruikers duidelijk hoe de pagina is gestructeerd.
-- [WCAG 2.4.1](https://www.w3.org/WAI/WCAG21/quickref/#qr-navigation-mechanisms-skip): Headings kunnen gebruikt worden om naar een volgende sectie te navigeren met het toetsenbord
-- [WCAG 2.4.6](https://www.w3.org/WAI/WCAG21/quickref/#headings-and-labels): Beschrijf met headings het doel of het onderwerp van de onderliggende content
-- [WCAG 2.4.10](https://www.w3.org/WAI/WCAG21/quickref/#qr-navigation-mechanisms-headings): Gebruik headings om de content te structureren
+  Text that looks like a heading is also recognized as a heading by a computer.
+  Using the correct heading level makes the page structure clear for all users.
+- [WCAG 2.4.1](https://www.w3.org/WAI/WCAG21/quickref/#qr-navigation-mechanisms-skip): Headings can be used to navigate to the next section with the keyboard.
+- [WCAG 2.4.6](https://www.w3.org/WAI/WCAG21/quickref/#headings-and-labels): Use headings to describe the purpose or subject of the underlying content.
+- [WCAG 2.4.10](https://www.w3.org/WAI/WCAG21/quickref/#qr-navigation-mechanisms-headings): Use headings to structure the content.
 
-## Referenties
+## References
 
 - [W3C - Headings](https://www.w3.org/WAI/tutorials/page-structure/headings/)
 - [W3C - Headings & labels](https://www.w3.org/TR/WCAG21/#headings-and-labels)

package/src/components/heading/heading.scss

@@ -59,6 +59,26 @@
   }
 }
 
+.amsterdam-heading--5 {
+  font-size: var(--amsterdam-heading-spacious-level-5-font-size);
+  line-height: var(--amsterdam-heading-spacious-level-5-line-height);
+
+  .amsterdam-theme--compact & {
+    font-size: var(--amsterdam-heading-compact-level-5-font-size);
+    line-height: var(--amsterdam-heading-compact-level-5-line-height);
+  }
+}
+
+.amsterdam-heading--6 {
+  font-size: var(--amsterdam-heading-spacious-level-6-font-size);
+  line-height: var(--amsterdam-heading-spacious-level-6-line-height);
+
+  .amsterdam-theme--compact & {
+    font-size: var(--amsterdam-heading-compact-level-6-font-size);
+    line-height: var(--amsterdam-heading-compact-level-6-line-height);
+  }
+}
+
 .amsterdam-heading--inverse-color {
   color: var(--amsterdam-heading-inverse-color);
 }

package/src/components/icon/README.md

@@ -1,19 +1,29 @@
 # Icon
 
-Iconen zijn visuele symbolen die worden gebruikt om ideeën, thema’s of acties weer te geven. Ze communiceren in één oogopslag de boodschap en vestigen de aandacht op belangrijke (interactieve) informatie. Gebruik altijd een `Icon` component om een SVG icoon heen voor de juiste vormgeving en maatvoering.
+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.
 
-## Interactieve elementen
+## Interactive Elements
 
-Ter ondersteuning van tekstuele interactie-elementen, zoals knoppen en links, kunnen iconen gebruikt worden. Probeer altijd een icoon te voorzien van begeleidende tekst. Iconen zonder begeleidende tekst mogen alleen gebruikt worden als ze aan internationale standaarden voldoen, zoals menu (hamburger icoon), zoek (vergrootglas), volgende, vorige, play, pauze, enz.
+Use an icon to support textual interactive elements like buttons and links.
+Always try to provide accompanying text for an icon.
+Only use icons without accompanying text if they adhere to international standards, such as menu (hamburger icon), search (magnifying glass), next, previous, play, pause, etc.
 
-## Kleur
+## Color
 
-Iconen zijn zwart of wit. Bij interactie zijn ze donkerblauw. Uitgeschakeld zijn ze grijs. En ze moeten voldoen aan dezelfde contrastverhouding voor toegankelijkheid als typografie bij een achtergrondkleur. Het icoon neemt standaard de kleur van de _container_ waar deze in zit over.
+Icons are black or white.
+When used as part of an interactive element, they are dark blue.
+When disabled, they are grey.
+They must adhere to the same contrast ratio for accessibility as typography against a background colour.
+The icon defaults to the colour of the container it is in.
 
-## Uitlijning
+## Alignment
 
-Iconen staan standaard links van de tekst en zijn verticaal in het midden van de eerste regel tekst uitgelijnd.
+Icons are aligned to the left of the text by default and vertically centred to the middle of the first line of text.
 
-## Grootte
+## Size
 
-De iconen gebruiken dezelfde tekstniveaus als alle typografische componenten om hun grootte te bepalen. Hierdoor zijn icoon en tekst makkelijk op elkaar af te stemmen. [Bekijk de documentatie over typografie voor meer informatie](/docs/docs-designrichtlijnen-typografie--docs#tekstniveaus).
+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-designrichtlijnen-typografie--docs#tekstniveaus).

package/src/components/icon/icon.scss

@@ -12,6 +12,11 @@
   fill: currentColor;
 }
 
+.amsterdam-icon--square {
+  aspect-ratio: 1 / 1;
+  justify-content: center;
+}
+
 .amsterdam-icon--size-3 {
   height: calc(var(--amsterdam-icon-spacious-size-3-font-size) * var(--amsterdam-icon-spacious-size-3-line-height));
 }
@@ -48,15 +53,6 @@
   width: var(--amsterdam-icon-spacious-size-6-font-size);
 }
 
-.amsterdam-icon--size-7 {
-  height: calc(var(--amsterdam-icon-spacious-size-7-font-size) * var(--amsterdam-icon-spacious-size-7-line-height));
-}
-
-.amsterdam-icon--size-7 svg {
-  height: var(--amsterdam-icon-spacious-size-7-font-size);
-  width: var(--amsterdam-icon-spacious-size-7-font-size);
-}
-
 .amsterdam-theme--compact {
   .amsterdam-icon--size-3 {
     height: calc(var(--amsterdam-icon-compact-size-3-font-size) * var(--amsterdam-icon-compact-size-3-line-height));
@@ -93,13 +89,4 @@
     height: var(--amsterdam-icon-compact-size-6-font-size);
     width: var(--amsterdam-icon-compact-size-6-font-size);
   }
-
-  .amsterdam-icon--size-7 {
-    height: calc(var(--amsterdam-icon-compact-size-7-font-size) * var(--amsterdam-icon-compact-size-7-line-height));
-  }
-
-  .amsterdam-icon--size-7 svg {
-    height: var(--amsterdam-icon-compact-size-7-font-size);
-    width: var(--amsterdam-icon-compact-size-7-font-size);
-  }
 }

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

@@ -0,0 +1,14 @@
+# Icon Button
+
+A button containing only an icon.
+
+## Guidelines
+
+- Use this button only if the icon is entirely clear and understandable.
+  Many icons are interpreted differently by different users.
+  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
+
+The Icon Button follows [the same requirements and guidelines as a regular button](https://amsterdam.github.io/design-system/?path=/docs/react_buttons-button--docs).

package/src/components/icon-button/icon-button.scss

@@ -0,0 +1,60 @@
+/**
+ * @license EUPL-1.2+
+ * Copyright (c) 2023 Gemeente Amsterdam
+ */
+
+@mixin reset {
+  border: 0;
+  padding-block: 0;
+  padding-inline: 0;
+}
+
+.amsterdam-icon-button {
+  background-color: transparent;
+  color: var(--amsterdam-icon-button-color);
+  cursor: pointer;
+  outline-offset: var(--amsterdam-icon-button-outline-offset);
+  touch-action: manipulation;
+
+  &:hover {
+    background-color: var(--amsterdam-icon-button-hover-background-color);
+    color: var(--amsterdam-icon-button-hover-color);
+  }
+
+  &:disabled {
+    background-color: transparent;
+    color: var(--amsterdam-icon-button-disabled-color);
+    cursor: not-allowed;
+  }
+
+  @include reset;
+}
+
+.amsterdam-icon-button--on-background-light {
+  color: var(--amsterdam-icon-button-on-background-light-color);
+
+  &:hover {
+    background-color: var(--amsterdam-icon-button-on-background-light-hover-background-color);
+    color: var(--amsterdam-icon-button-on-background-light-hover-color);
+  }
+
+  &:disabled {
+    background-color: transparent;
+    color: var(--amsterdam-icon-button-on-background-light-disabled-color);
+  }
+}
+
+.amsterdam-icon-button--on-background-dark {
+  background-color: var(--amsterdam-icon-button-on-background-dark-background-color);
+  color: var(--amsterdam-icon-button-on-background-dark-color);
+
+  &:hover {
+    background-color: var(--amsterdam-icon-button-on-background-dark-hover-background-color);
+    color: var(--amsterdam-icon-button-on-background-dark-hover-color);
+  }
+
+  &:disabled {
+    background-color: var(--amsterdam-icon-button-on-background-dark-disabled-background-color);
+    color: var(--amsterdam-icon-button-on-background-dark-disabled-color);
+  }
+}

package/src/components/image/README.md

@@ -1,18 +1,22 @@
 # Image
 
-Toont een afbeelding.
+Displays an image.
 
-## Richtlijnen
+## Guidelines
 
-- Vergeet niet om een beschrijving van de afbeelding op te nemen in het `alt`-attribuut.
-  Dit zorgt ervoor dat gebruikers van schermlezers deze informatie ook tot zich kunnen nemen.
-  Daarnaast kan het helpen bij zoekmachineoptimalisatie.
-- Alleen voor decoratieve afbeeldingen is zo’n beschrijving niet nodig. Gebruik in dit geval `alt=""`.
-  Denk aan afbeeldingen die weinig toevoegen aan de nabije tekst of afbeeldingen die louter bijdragen aan het ontwerp of de sfeer van de pagina (bron: [W3C Web Accessibility Initiative](https://www.w3.org/WAI/tutorials/images/decorative/)).
-- Zorg ervoor dat de afbeelding een beeldverhouding heeft die ondersteund wordt door het [Aspect Ratio](?path=/docs/layout-aspect-ratio--docs) component.
+- Do not forget to include a description of the image in the `alt` attribute.
+  This ensures that screen reader users can also access this information.
+  Additionally, it can aid in search engine optimization.
+- A description is unnecessary for decorative images; use `alt=""` for these.
+  Examples are images that add little to the nearby text or pictures that purely contribute to the design or atmosphere of the page (source: [W3C Web Accessibility Initiative](https://www.w3.org/WAI/tutorials/images/decorative/)).
+- Optionally specify multiple candidates for the image through the `srcSet` attribute.
+  For example, provide small, medium, and large variants for various screen sizes.
+  This prevents unnecessary downloading of large files.
+  Do this especially for the main image of a page, where the difference between sizes on a narrow and wide screen is most significant.
+- Ensure that the aspect ratio of the image is supported by the [Aspect Ratio](?path=/docs/layout-aspect-ratio--docs) component.
 
-## Relevante WCAG-eisen
+## Relevant WCAG Requirements
 
-- [WCAG 1.1.1](https://www.w3.org/TR/WCAG22/#non-text-content): niet-tekstuele content heeft een tekstueel alternatief
-- [WCAG 1.4.5](https://www.w3.org/TR/WCAG22/#images-of-text): gebruik tekst in plaats van afbeeldingen van tekst
-- [WCAG 1.4.9](https://www.w3.org/TR/WCAG22/#images-of-text-no-exception): gebruik afbeeldingen van tekst alleen als er geen alternatief is
+- [WCAG 1.1.1](https://www.w3.org/TR/WCAG22/#non-text-content): Non-text content must have a text alternative.
+- [WCAG 1.4.5](https://www.w3.org/TR/WCAG22/#images-of-text): Use text instead of images of text.
+- [WCAG 1.4.9](https://www.w3.org/TR/WCAG22/#images-of-text-no-exception): Use images of text only when there is no alternative.

package/src/components/image/image.scss

@@ -8,6 +8,10 @@
   height: auto; /* [1] */
   max-width: 100%; /* [1] */
   vertical-align: middle; /* [2] */
+
+  &--cover {
+    object-fit: cover;
+  }
 }
 
 // [1] Allow for fluid image sizing while maintaining aspect ratio governed by width/height attributes

package/src/components/index.scss

@@ -4,6 +4,17 @@
  */
 
 /* Append here */
+@import "./link-list/link-list";
+@import "./badge/badge";
+@import "./table/table";
+@import "./mega-menu/mega-menu";
+@import "./icon-button/icon-button";
+@import "./skip-link/skip-link";
+@import "./overlap/overlap";
+@import "./header/header";
+@import "./mark/mark";
+@import "./text-input/text-input";
+@import "./search-field/search-field";
 @import "./logo/logo";
 @import "./dialog/dialog";
 @import "./image/image";
@@ -18,9 +29,8 @@
 @import "./checkbox/checkbox";
 @import "./form-label/form-label";
 @import "./grid/grid";
-@import "./grid/grid-cell";
 @import "./heading/heading";
-@import "./highlight/highlight";
+@import "./spotlight/spotlight";
 @import "./icon/icon";
 @import "./link/link";
 @import "./ordered-list/ordered-list";

package/src/components/link/README.md

@@ -1,42 +1,44 @@
 # Link
 
-Een link (in het Nederlands: koppeling) wordt gebruikt als navigatie-element en kan op zichzelf of inline met tekst worden gebruikt. Het is de lichtgewicht variant voor navigatie.
+A link is a navigation element and can be used independently or inline with text.
+It is the lightweight variant for navigation.
 
-## Richtlijnen
+## Guidelines
 
-Gebruik een link in de volgende gevallen:
+Use a link in the following cases:
 
-- Navigatie naar een andere pagina binnen de website of applicatie
-- Navigatie naar een andere website (zie [Externe links](#externe-links))
-- Navigatie naar een element op dezelfde pagina
-- Koppeling naar e-mails of telefoonnummers (begin de link met `mailto:` of `tel:`)
+- To navigate to another page within the website or application
+- 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:`)
 
-Een link is een navigatie component. Gebruik een knop in plaats van een link als er een actie gewenst is.
+A link is a navigation component.
+Use a button instead of a link when an action is desired.
 
-<!--
-  TODO: According to the spec, you should use a link for downloads as well. Last time I checked, different browsers handled this differently,
-  which led to unexpected results. Maybe that changed in the meantime. Do we want to figure this out and describe this in the docs as well?
--->
+### External links
 
-### Externe links
+Always include `rel="external"` for an external link.
+Avoid `target="_blank"`, but use `rel="external noopener"` if necessary.
+For more information: [Links to cross-origin destinations are unsafe](https://developer.chrome.com/docs/lighthouse/best-practices/external-anchors-use-rel-noopener/)
 
-Geef een externe link altijd `rel="external"` mee. Vermijd `target="_blank"`, maar gebruik in ieder geval `rel="external noopener"` als het moet. Voor meer informatie: [Links to cross-origin destinations are unsafe](https://developer.chrome.com/docs/lighthouse/best-practices/external-anchors-use-rel-noopener/)
+### Visited style
 
-### Bezochte stijl
+Visited links indicate that a user has already opened the link.
+We discourage using styles for visited links because they often make the page less clear and navigation more challenging.
+The inline link does have a visited style.
+It is not part of navigation elements that are frequently scanned.
 
-Bezochte koppelingen geven aan dat een gebruiker de koppeling al heeft geopend. Gebruikte stijlen raden we af bij koppelingen, omdat ze de pagina vaak onoverzichtelijk maken. Het maakt navigeren door een pagina moeilijker. De inline koppeling heeft wel een bezochte stijl. Het vormt geen onderdeel van navigatie elementen die veel gescand worden.
-
-## Relevante WCAG eisen
+## 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)
 - [WCAG 2.5.3](https://www.w3.org/TR/WCAG21/#label-in-name)
 - [WCAG 3.1.2](https://www.w3.org/TR/WCAG21/#language-of-parts)
 
-## Referenties
+## References
 
-- [Links to cross-origin destinations are unsafe](https://developer.chrome.com/docs/lighthouse/best-practices/external-anchors-use-rel-noopener/): Vermijd `target="_blank"` of gebruik `rel="external noopener"` als het moet.
-- [_A comprehensive guide to designing perfect links in UX_, op Prototypr](https://blog.prototypr.io/a-guide-to-designing-perfect-links-in-ux-414558f35730): best practices rondom links.
-- [_Writing Hyperlinks: Salient, Descriptive, Start with Keyword_ door Norman Nielsen Group](https://www.nngroup.com/articles/writing-links/): hoe schrijf je goede links? Een uitgebreid artikel over links.
-- [_Hover, focus, active_, door Wunder](https://wunder.io/wunderpedia/accessibility/accessible-uis/hover-focus-active/): goede uitleg over de states die elementen zoals de link en button hebben in browsers.
-- [MDN: `<a>`: The Anchor element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a): uitgebreid overzicht van alle mogelijkheden van links in HTML.
+- [Links to cross-origin destinations are unsafe](https://developer.chrome.com/docs/lighthouse/best-practices/external-anchors-use-rel-noopener/): Avoid `target="_blank"` or use `rel="external noopener"` if necessary.
+- [_A comprehensive guide to designing perfect links in UX_, on Prototypr](https://blog.prototypr.io/a-guide-to-designing-perfect-links-in-ux-414558f35730): Best practices for links.
+- [_Writing Hyperlinks: Salient, Descriptive, Start with Keyword_ by Norman Nielsen Group](https://www.nngroup.com/articles/writing-links/): How to write good links? An extensive article on links.
+- [_Hover, focus, active_, by Wunder](https://wunder.io/wunderpedia/accessibility/accessible-uis/hover-focus-active/): A good explanation of the states that elements like links and buttons have in browsers.
+- [MDN: `<a>`: The Anchor element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a): Comprehensive overview of all possibilities of links in HTML.

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

@@ -0,0 +1,16 @@
+# Link List
+
+A collection of related links.
+
+## Design
+
+Every list item starts with a chevron.
+It emphasizes the list structure and thematic coherence.
+The chevron is part of the link.
+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](?path=/docs/navigation-link--docs) component.