Merge branch 'main' of https://github.com/Amsterdam/design-system int…

…o feature/DES-492-logo-component

.github/workflows/feature-branch-cleanup.yml

@@ -23,7 +23,7 @@ jobs:
         with:
           ref: gh-pages
 
-      - uses: actions/setup-node@v3
+      - uses: actions/setup-node@v4
         with:
           node-version: 18
 

.github/workflows/feature-branch-deploy.yml

@@ -31,7 +31,7 @@ jobs:
           token: ${{ secrets.GITHUB_TOKEN }}
           env: demo-${{ env.BRANCH_NAME }}
 
-      - uses: actions/setup-node@v3
+      - uses: actions/setup-node@v4
         with:
           node-version: 18
 

.github/workflows/lint-test.yml

@@ -14,7 +14,7 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Set up Node.js version
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
           node-version: "18.17.1"
 
@@ -52,7 +52,7 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Set up Node.js version
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
           node-version: "18.17.1"
 

CONTRIBUTING.md

@@ -107,7 +107,7 @@ Package versioning and publishing is done through Lerna, by the maintainers of t
 
 ## Adding a new component
 
-Scaffold all necessary files for a new component at once through `npm plop`.
+Scaffold all necessary files for a new component at once through `npx plop`.
 Enter the name of your component when prompted.
 This will create files for the design tokens, CSS and React components, and React Stories.
 

documentation/git.md

@@ -32,7 +32,10 @@ We work with small, short-lived branches (aim for 2 working days) directly on a
 
 The approach is called ‘[trunk-based development](https://trunkbaseddevelopment.com/)’ and differs from the well-known ‘Git Flow’.
 
-Branches are automatically deployed to their own environment. To get the address of a branch deployment, go to the repository on GitHub.com and click on [Deployments](https://github.com/Amsterdam/design-system/deployments). Find the branch in the list and click on the external website icon.
+Branches are automatically deployed to their own environment. There are 2 ways to get the address of a branch deployment:
+
+- If the branch has a pull request, you can find the address there using the 'View deployment'-button. You might need to click 'Show environments' to see this button.
+- Otherwise, go to the repository on GitHub.com and click on [Deployments](https://github.com/Amsterdam/design-system/deployments). Find the branch in the list and click on the external website icon.
 
 ## Create a branch
 
@@ -74,19 +77,6 @@ All together, good branch names look like this:
 - `refactor/DES-368-use-singular-for-enums`
 - `task/DES-104-add-initial-git-guidelines`
 
-### Forbidden branch names
-
-There are a couple of forbidden branch names, owing to the way we have currently set up feature branch deployments.
-
-These are:
-
-- `assets`
-- `sb-addons`
-- `sb-common-assets`
-- `sb-manager`
-- `sb-preview`
-- `storybook-react`
-
 ## Describe each commit
 
 Take some time to determine a good description for your commit. Try to describe the goal of the change. Don’t describe what also be deduced from the diff.

packages/css/src/aspect-ratio/README.md

@@ -4,13 +4,13 @@ Aspect Ratio (in het Nederlands: beeldverhouding) koppelt de hoogte van een elem
 
 Om de vormgeving consistent te houden gebruiken we een vaste set verhoudingen (breedte:hoogte):
 
-| _keyword_    | verhouding |
-| :----------- | ---------: |
-| `extra-wide` |       16:9 |
-| `wide`       |        5:4 |
-| `square`     |        1:1 |
-| `tall`       |        4:5 |
-| `extra-tall` |       9:16 |
+| _keyword_ | verhouding |
+| :-------- | ---------: |
+| `x-wide`  |       16:9 |
+| `wide`    |        5:4 |
+| `square`  |        1:1 |
+| `tall`    |        4:5 |
+| `x-tall`  |       9:16 |
 
 ## Richtlijnen
 

packages/css/src/aspect-ratio/aspect-ratio.scss

@@ -8,8 +8,8 @@
   position: relative;
 }
 
-.amsterdam-aspect-ratio--extra-tall {
-  aspect-ratio: var(--amsterdam-aspect-ratio-extra-tall);
+.amsterdam-aspect-ratio--x-tall {
+  aspect-ratio: var(--amsterdam-aspect-ratio-x-tall);
 }
 
 .amsterdam-aspect-ratio--tall {
@@ -24,6 +24,6 @@
   aspect-ratio: var(--amsterdam-aspect-ratio-wide);
 }
 
-.amsterdam-aspect-ratio--extra-wide {
-  aspect-ratio: var(--amsterdam-aspect-ratio-extra-wide);
+.amsterdam-aspect-ratio--x-wide {
+  aspect-ratio: var(--amsterdam-aspect-ratio-x-wide);
 }

packages/css/src/image/README.md

@@ -0,0 +1,18 @@
+# Image
+
+Toont een afbeelding.
+
+## Richtlijnen
+
+- 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.
+
+## Relevante WCAG-eisen
+
+- [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

packages/css/src/image/image.scss

@@ -0,0 +1,16 @@
+/**
+ * @license EUPL-1.2+
+ * Copyright (c) 2023 Gemeente Amsterdam
+ */
+
+.amsterdam-image {
+  font-style: italic; /* [3] */
+  height: auto; /* [1] */
+  max-width: 100%; /* [1] */
+  vertical-align: middle; /* [2] */
+}
+
+// [1] Allow for fluid image sizing while maintaining aspect ratio governed by width/height attributes
+// [2] Remove ‘phantom’ whitespace
+// [3] Italicise alt text to visually offset it from surrounding copy
+// Source: https://x.com/csswizardry/status/1717841334462005661

packages/css/src/index.scss

@@ -5,6 +5,7 @@
 
 /* Append here */
 @import "./logo/logo";
+@import "./image/image";
 @import "./pagination/pagination";
 @import "./accordion/accordion";
 @import "./alert/alert";

packages/css/src/screen/screen.scss

@@ -17,6 +17,6 @@
   max-width: var(--amsterdam-screen-wide-max-width);
 }
 
-.amsterdam-screen--extra-wide {
-  max-width: var(--amsterdam-screen-extra-wide-max-width);
+.amsterdam-screen--x-wide {
+  max-width: var(--amsterdam-screen-x-wide-max-width);
 }

packages/css/src/top-task-link/README.md

@@ -1,14 +1,19 @@
 # Top Task Link
 
-De Top Task Link is een navigatie-element dat opvallender is dan een link, om de aandacht te trekken voor de meest belangrijke informatie.
-Zet de Top Task Link in zodat de gebruiker snel de juiste informatie vindt én een bijbehorende taak makkelijk kan uitvoeren.
+Via dit opvallende navigatie-element vindt de Amsterdammer snel de weg naar veel voorkomende taken.
 
 ## Richtlijnen
 
-- Een Top Task Link moet een titel hebben. Hou deze titel zo kort mogelijk, hij mag maximaal over 2 regels lopen.
-- Een Top Task Link kan een omschrijving hebben, maar dat is niet verplicht. De omschrijving staat onder de titel en is ook maximaal 2 regels.
-- Plaats voor brede vensters 3 of 4 Top Task Links naast elkaar. Als je meer Top Task Links hebt, zet ze dan op de volgende rij.
-- Probeer het aantal links op brede vensters te verdelen over rijen van 3 of 4 links. Als dit niet lukt, laat de laatste cellen van het grid dan leeg.
+- Een Top Task Link heeft zowel een titel als een beschrijving.
+- De titel beschrijft de essentie van de pagina waarnaar wordt verwezen.
+  Deze trekt de aandacht bij het scannen van de pagina.
+- De beschrijving geeft meer context.
+  Dit helpt de Amsterdammer bevestigen dat die zijn doel op de vervolgpagina inderdaad kan bereiken.
+- Houd beide teksten bondig. Een titel bestaat uit een paar woorden, de beschrijving uit 1 of 2 korte zinnen. De beschrijving eindigt dan ook op een punt of ander geschikt leesteken.
+- Plaats voor brede vensters 3 of 4 Top Task Links naast elkaar op het [Grid](?path=/docs/react_layout-grid--docs).
+  Als je meer Top Task Links hebt, zet ze dan op de volgende rij.
+  Probeer het aantal links op brede vensters te verdelen over rijen van 3 of 4 links. Als dit niet lukt, laat de laatste cellen van het grid dan leeg.
+- Heb je een groep verwijzingen waarvoor een beschrijving niet nodig of logisch is, gebruik dan een [Link List](?path=/docs/react_navigation-link--docs).
 
 ## Relevante WCAG eisen
 

packages/react/src/AspectRatio/AspectRatio.test.tsx

@@ -28,17 +28,17 @@ describe('Aspect ratio', () => {
   })
 
   it('renders the right size classes', () => {
-    const { container: extraTall } = render(<AspectRatio ratio="extra-tall" />)
+    const { container: xTall } = render(<AspectRatio ratio="x-tall" />)
     const { container: tall } = render(<AspectRatio ratio="tall" />)
     const { container: square } = render(<AspectRatio ratio="square" />)
     const { container: wide } = render(<AspectRatio ratio="wide" />)
-    const { container: extraWide } = render(<AspectRatio ratio="extra-wide" />)
+    const { container: xWide } = render(<AspectRatio ratio="x-wide" />)
 
-    expect(extraTall.firstChild).toHaveClass('amsterdam-aspect-ratio--extra-tall')
+    expect(xTall.firstChild).toHaveClass('amsterdam-aspect-ratio--x-tall')
     expect(tall.firstChild).toHaveClass('amsterdam-aspect-ratio--tall')
     expect(square.firstChild).toHaveClass('amsterdam-aspect-ratio--square')
     expect(wide.firstChild).toHaveClass('amsterdam-aspect-ratio--wide')
-    expect(extraWide.firstChild).toHaveClass('amsterdam-aspect-ratio--extra-wide')
+    expect(xWide.firstChild).toHaveClass('amsterdam-aspect-ratio--x-wide')
   })
 
   it('renders an additional class name', () => {

packages/react/src/AspectRatio/AspectRatio.tsx

@@ -6,7 +6,7 @@
 import clsx from 'clsx'
 import { ForwardedRef, forwardRef, HTMLAttributes, PropsWithChildren } from 'react'
 
-export type Ratio = 'extra-tall' | 'tall' | 'square' | 'wide' | 'extra-wide'
+export type Ratio = 'x-tall' | 'tall' | 'square' | 'wide' | 'x-wide'
 
 export interface AspectRatioProps extends PropsWithChildren<HTMLAttributes<HTMLDivElement>> {
   ratio?: Ratio

packages/react/src/Image/Image.test.tsx

@@ -0,0 +1,33 @@
+import { render } from '@testing-library/react'
+import { createRef } from 'react'
+import { Image } from './Image'
+import '@testing-library/jest-dom'
+
+describe('Image', () => {
+  it('renders', () => {
+    const { container } = render(<Image />)
+    const component = container.querySelector(':only-child')
+    expect(component).toBeInTheDocument()
+    expect(component).toBeVisible()
+  })
+
+  it('renders a design system BEM class name', () => {
+    const { container } = render(<Image />)
+    const component = container.querySelector(':only-child')
+    expect(component).toHaveClass('amsterdam-image')
+  })
+
+  it('renders an additional class name', () => {
+    const { container } = render(<Image className="extra" />)
+    const component = container.querySelector(':only-child')
+    expect(component).toHaveClass('extra')
+    expect(component).toHaveClass('amsterdam-image')
+  })
+
+  it('supports ForwardRef in React', () => {
+    const ref = createRef<HTMLImageElement>()
+    const { container } = render(<Image ref={ref} />)
+    const component = container.querySelector(':only-child')
+    expect(ref.current).toBe(component)
+  })
+})

packages/react/src/Image/Image.tsx

@@ -0,0 +1,15 @@
+/**
+ * @license EUPL-1.2+
+ * Copyright (c) 2023 Gemeente Amsterdam
+ */
+
+import clsx from 'clsx'
+import { ForwardedRef, forwardRef, ImgHTMLAttributes } from 'react'
+
+export interface ImageProps extends ImgHTMLAttributes<HTMLImageElement> {}
+
+export const Image = forwardRef(({ className, ...restProps }: ImageProps, ref: ForwardedRef<HTMLImageElement>) => (
+  <img {...restProps} ref={ref} className={clsx('amsterdam-image', className)} />
+))
+
+Image.displayName = 'Image'

packages/react/src/Image/README.md

@@ -0,0 +1,3 @@
+# React Image component
+
+[Image documentation](../../../css/src/image/README.md)

packages/react/src/Image/index.ts

@@ -0,0 +1,2 @@
+export { Image } from './Image'
+export type { ImageProps } from './Image'

packages/react/src/Screen/Screen.test.tsx

@@ -22,11 +22,11 @@ describe('Screen', () => {
   })
 
   it('renders the max-width class name', () => {
-    const { container } = render(<Screen maxWidth="extra-wide" />)
+    const { container } = render(<Screen maxWidth="x-wide" />)
 
     const component = container.querySelector(':only-child')
 
-    expect(component).toHaveClass('amsterdam-screen--extra-wide')
+    expect(component).toHaveClass('amsterdam-screen--x-wide')
   })
 
   it('renders an additional class name', () => {

packages/react/src/Screen/Screen.tsx

@@ -6,7 +6,7 @@
 import clsx from 'clsx'
 import { ForwardedRef, forwardRef, HTMLAttributes, PropsWithChildren } from 'react'
 
-type ScreenMaxWidth = 'wide' | 'extra-wide'
+type ScreenMaxWidth = 'wide' | 'x-wide'
 
 export interface ScreenProps extends PropsWithChildren<HTMLAttributes<HTMLDivElement>> {
   maxWidth?: ScreenMaxWidth

packages/react/src/TopTaskLink/TopTaskLink.test.tsx

@@ -5,18 +5,18 @@ import '@testing-library/jest-dom'
 
 describe('Top task link', () => {
   it('renders a link role element', () => {
-    render(<TopTaskLink label="Label" href="/" />)
+    render(<TopTaskLink href="/" label="Label" description="Description" />)
 
     const link = screen.getByRole('link', {
-      name: 'Label',
+      name: 'Label, Description',
     })
 
     expect(link).toBeInTheDocument()
     expect(link).toBeVisible()
   })
 
   it('renders a design system BEM class name', () => {
-    render(<TopTaskLink label="Label" description="Description" href="/" />)
+    render(<TopTaskLink href="/" label="Label" description="Description" />)
 
     const link = screen.getByRole('link', {
       name: 'Label, Description',
@@ -30,10 +30,10 @@ describe('Top task link', () => {
   })
 
   it('renders an additional class name', () => {
-    render(<TopTaskLink href="/" label="Label" className="extra" />)
+    render(<TopTaskLink href="/" label="Label" description="Description" className="extra" />)
 
     const link = screen.getByRole('link', {
-      name: 'Label',
+      name: 'Label, Description',
     })
 
     expect(link).toHaveClass('extra')
@@ -43,10 +43,10 @@ describe('Top task link', () => {
   it('supports ForwardRef in React', () => {
     const ref = createRef<HTMLAnchorElement>()
 
-    render(<TopTaskLink href="/" ref={ref} label="Label" />)
+    render(<TopTaskLink href="/" label="Label" description="Description" ref={ref} />)
 
     const link = screen.getByRole('link', {
-      name: 'Label',
+      name: 'Label, Description',
     })
 
     expect(ref.current).toBe(link)

packages/react/src/TopTaskLink/TopTaskLink.tsx

@@ -8,7 +8,7 @@ import { AnchorHTMLAttributes, ForwardedRef, forwardRef } from 'react'
 
 export interface TopTaskLinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
   label: string
-  description?: string
+  description: string
 }
 
 export const TopTaskLink = forwardRef(
@@ -17,11 +17,11 @@ export const TopTaskLink = forwardRef(
       {...restProps}
       ref={ref}
       className={clsx('amsterdam-top-task-link', className)}
-      // Add an aria-label with a comma between label and description, so screenreaders have a slight pause between the two.
-      aria-label={`${label}${description ? `, ${description}` : ''}`}
+      // The comma makes screen readers add a slight pause between the label and the description.
+      aria-label={`${label}, ${description}`}
     >
       <span className="amsterdam-top-task-link__label">{label}</span>
-      {description && <span className="amsterdam-top-task-link__description">{description}</span>}
+      <span className="amsterdam-top-task-link__description">{description}</span>
     </a>
   ),
 )

packages/react/src/index.ts

@@ -5,6 +5,7 @@
 
 /* Append here */
 export * from './Logo'
+export * from './Image'
 export * from './Pagination'
 export * from './Screen'
 export * from './Switch'