@amsterdam/design-system-css 0.3.0 → 0.4.0

package/src/components/card/README.md

@@ -1,25 +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.
 
-## Richtlijnen
+## Guidelines
 
-- De titel van een card is een link in een heading.
-  Hier gelden dezelfde richtlijnen voor als voor reguliere [links](?path=/docs/react_navigation-link--docs) en [headings](?path=/docs/react_text-heading--docs).
-  De link is actief op het hele gebied van de card.
-- Een card heeft meer inhoud nodig dan alleen een titel.
-  Vul dit aan met tekstuele en/of visuele inhoud.
-- De tekst zet je in een reguliere paragraaf.
-  Alleen voor een tagline of datum gebruik je de kleinste tekstgrootte.
-- Als de inhoud geen detailpagina vertegenwoordigt is dit component niet de beste optie.
-  Om te verwijzen naar een thematische pagina gebruik je een [top task link](?path=/docs/react_navigation-top-task-link--docs).
-  Ook kun je een [reguliere link](?path=/docs/react_navigation-link--docs) inzetten.
+- 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).
 
-## Schermlezers
+## Screen Readers
 
-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.
+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/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
 

package/src/components/dialog/dialog.scss

@@ -74,19 +74,3 @@
     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

@@ -1,21 +1,20 @@
 # Grid
 
-Verdeelt de breedte van het scherm in kolommen waarop de elementen van een pagina worden uitgelijnd.
+Divides the screen into columns to align the elements of a page.
 
-## Gebruik
+## Usage
 
-Elke pagina moet het grid gebruiken als basis voor de layout.
-Het staat dus direct binnen [Screen](?path=/docs/layout-screen--docs).
+Every page should use the grid as the foundation for its layout.
+It is placed directly within the [Screen](?path=/docs/layout-screen--docs).
 
-Een [Footer](?path=/docs/react_containers-footer--docs) en een [Highlight](?path=/docs/react_containers-highlight--docs) zijn iets breder dan het grid.
-Vóór deze componenten sluit je een instantie van het grid af.
-Erbinnen en eventueel erna start je een nieuwe.
-Meerdere instanties van het grid component zijn dus mogelijk op een pagina.
-De kolommen van alle grids moeten wel precies op elkaar aansluiten.
+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.
 
-Binnen het grid maak je cellen die de gewenste inhoud bevatten.
-Een cel beslaat vaak meerdere kolommen van het grid.
+Within the grid, you create cells containing the desired content.
+A cell often spans multiple columns of the grid.
 
-## Ontwerp
+## Design
 
-De [ontwerpkeuzes](?path=/docs/docs-designrichtlijnen-grid--docs) staan beschreven onder de designrichtlijnen.
+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);
 }

package/src/components/header/README.md

@@ -1,12 +1,12 @@
 # Header
 
-A Header offers a container to display a City of Amsterdam logo, subsite title and page menu.
+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 little page menu items as possible.
+- When you have a long subsite title, use no or as few page menu items as possible.
 
 ## References
 

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

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,23 +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/)).
-- Specificeer eventueel meerdere kandidaten voor de afbeelding via het `srcSet`-attribuut.
-  Bijvoorbeeld een kleine, middelgrote en grote variant voor de diverse schermformaten.
-  Zo voorkom je het onnodige downloaden van grote bestanden.
-  Doe dit vooral voor de hoofdafbeelding van een pagina,
-  daar is het verschil tussen de formaten op een smal en breed scherm het grootst.
-- 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/index.scss

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

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.