From a47075db97e86eac5fd83d86de59992d6adc407b Mon Sep 17 00:00:00 2001
From: Ruben Sibon <r.sibon@amsterdam.nl>
Date: Fri, 20 Sep 2024 13:49:07 +0200
Subject: [PATCH 01/42] =?UTF-8?q?WIP(aspect-ratio):=20=F0=9F=9A=A7=20comp?=
 =?UTF-8?q?=20to=20props?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../css/src/components/aspect-ratio/README.md |   2 +-
 .../components/aspect-ratio/aspect-ratio.scss |   5 +
 packages/css/src/components/image/README.md   |   1 +
 .../src/AspectRatio/AspectRatio.test.tsx      |  62 ----------
 .../react/src/AspectRatio/AspectRatio.tsx     |  18 +--
 packages/react/src/AspectRatio/README.md      |   2 +-
 packages/react/src/AspectRatio/index.ts       |   1 -
 packages/react/src/Image/Image.test.tsx       |   9 ++
 packages/react/src/Image/Image.tsx            |  16 ++-
 .../AspectRatio/AspectRatio.docs.mdx          |  45 --------
 .../AspectRatio/AspectRatio.stories.tsx       | 108 ------------------
 .../src/components/Card/Card.stories.tsx      |   6 +-
 storybook/src/components/Image/Image.docs.mdx |   4 +
 .../src/components/Image/Image.stories.tsx    |   2 +
 .../components/Overlap/Overlap.stories.tsx    |  20 ++--
 .../amsterdam/ArticlePage/ArticleHeader.tsx   |   6 +-
 .../src/pages/amsterdam/HomePage/HomeNews.tsx |  14 +--
 17 files changed, 56 insertions(+), 265 deletions(-)
 delete mode 100644 packages/react/src/AspectRatio/AspectRatio.test.tsx
 delete mode 100644 storybook/src/components/AspectRatio/AspectRatio.docs.mdx
 delete mode 100644 storybook/src/components/AspectRatio/AspectRatio.stories.tsx

diff --git a/packages/css/src/components/aspect-ratio/README.md b/packages/css/src/components/aspect-ratio/README.md
index 128e9799fb..ecbf9a672c 100644
--- a/packages/css/src/components/aspect-ratio/README.md
+++ b/packages/css/src/components/aspect-ratio/README.md
@@ -17,4 +17,4 @@ These are the proportions we use:
 
 ## Guidelines
 
-- Use this component to constrain images, videos and other elements to one of the available aspect ratios.
+- Use this CSS class to constrain images, videos and other elements to one of the available aspect ratios.
diff --git a/packages/css/src/components/aspect-ratio/aspect-ratio.scss b/packages/css/src/components/aspect-ratio/aspect-ratio.scss
index 08fcab0fe0..b4a27f3c20 100644
--- a/packages/css/src/components/aspect-ratio/aspect-ratio.scss
+++ b/packages/css/src/components/aspect-ratio/aspect-ratio.scss
@@ -4,6 +4,11 @@
  */
 
 .ams-aspect-ratio {
+  block-size: auto;
+  inline-size: fit-content;
+}
+
+.ams-aspect-ratio__container {
   overflow: hidden;
   position: relative;
 }
diff --git a/packages/css/src/components/image/README.md b/packages/css/src/components/image/README.md
index da8fbbcfff..a0c96847d3 100644
--- a/packages/css/src/components/image/README.md
+++ b/packages/css/src/components/image/README.md
@@ -15,6 +15,7 @@ Displays an image.
   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.
+  <!-- TODO: document usage of aspectRatio prop -->
 - Ensure that the aspect ratio of the image is supported by the [Aspect Ratio](/docs/components-layout-aspect-ratio--docs) component.
 
 ## Relevant WCAG requirements
diff --git a/packages/react/src/AspectRatio/AspectRatio.test.tsx b/packages/react/src/AspectRatio/AspectRatio.test.tsx
deleted file mode 100644
index bdeb5c497d..0000000000
--- a/packages/react/src/AspectRatio/AspectRatio.test.tsx
+++ /dev/null
@@ -1,62 +0,0 @@
-import { render } from '@testing-library/react'
-import { createRef } from 'react'
-import { AspectRatio } from './AspectRatio'
-import '@testing-library/jest-dom'
-
-describe('Aspect ratio', () => {
-  it('renders', () => {
-    const { container } = render(<AspectRatio />)
-
-    const component = container.querySelector(':only-child')
-
-    expect(component).toBeInTheDocument()
-    expect(component).toBeVisible()
-  })
-
-  it('renders children', () => {
-    const { getByText } = render(<AspectRatio>Child</AspectRatio>)
-
-    expect(getByText(/Child/i)).toBeInTheDocument()
-  })
-
-  it('renders a design system BEM class name', () => {
-    const { container } = render(<AspectRatio />)
-
-    const component = container.querySelector(':only-child')
-
-    expect(component).toHaveClass('ams-aspect-ratio')
-  })
-
-  it('renders the right size classes', () => {
-    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: xWide } = render(<AspectRatio ratio="x-wide" />)
-
-    expect(xTall.firstChild).toHaveClass('ams-aspect-ratio--x-tall')
-    expect(tall.firstChild).toHaveClass('ams-aspect-ratio--tall')
-    expect(square.firstChild).toHaveClass('ams-aspect-ratio--square')
-    expect(wide.firstChild).toHaveClass('ams-aspect-ratio--wide')
-    expect(xWide.firstChild).toHaveClass('ams-aspect-ratio--x-wide')
-  })
-
-  it('renders an additional class name', () => {
-    const { container } = render(<AspectRatio className="extra" />)
-
-    const component = container.querySelector(':only-child')
-
-    expect(component).toHaveClass('extra')
-    expect(component).toHaveClass('ams-aspect-ratio')
-  })
-
-  it('supports ForwardRef in React', () => {
-    const ref = createRef<HTMLDivElement>()
-
-    const { container } = render(<AspectRatio ref={ref} />)
-
-    const component = container.querySelector(':only-child')
-
-    expect(ref.current).toBe(component)
-  })
-})
diff --git a/packages/react/src/AspectRatio/AspectRatio.tsx b/packages/react/src/AspectRatio/AspectRatio.tsx
index 0bcb2aafa1..1198968b22 100644
--- a/packages/react/src/AspectRatio/AspectRatio.tsx
+++ b/packages/react/src/AspectRatio/AspectRatio.tsx
@@ -3,23 +3,9 @@
  * Copyright Gemeente Amsterdam
  */
 
-import clsx from 'clsx'
-import { forwardRef } from 'react'
-import type { ForwardedRef, HTMLAttributes, PropsWithChildren } from 'react'
-
 export type Ratio = 'x-tall' | 'tall' | 'square' | 'wide' | 'x-wide' | '2x-wide'
 
 export type AspectRatioProps = {
   /** The dimensions. */
-  ratio?: Ratio
-} & PropsWithChildren<HTMLAttributes<HTMLDivElement>>
-
-export const AspectRatio = forwardRef(
-  ({ children, className, ratio = 'square', ...restProps }: AspectRatioProps, ref: ForwardedRef<HTMLDivElement>) => (
-    <div {...restProps} ref={ref} className={clsx('ams-aspect-ratio', `ams-aspect-ratio--${ratio}`, className)}>
-      {children}
-    </div>
-  ),
-)
-
-AspectRatio.displayName = 'AspectRatio'
+  aspectRatio?: Ratio
+}
diff --git a/packages/react/src/AspectRatio/README.md b/packages/react/src/AspectRatio/README.md
index 739cdd6cc0..285732e7e3 100644
--- a/packages/react/src/AspectRatio/README.md
+++ b/packages/react/src/AspectRatio/README.md
@@ -1,5 +1,5 @@
 <!-- @license CC0-1.0 -->
 
-# React Aspect Ratio component
+# React Aspect Ratio property
 
 [Aspect ratio documentation](../../../css/src/components/aspect-ratio/README.md)
diff --git a/packages/react/src/AspectRatio/index.ts b/packages/react/src/AspectRatio/index.ts
index d0fbbc74a6..8f3cd26c46 100644
--- a/packages/react/src/AspectRatio/index.ts
+++ b/packages/react/src/AspectRatio/index.ts
@@ -1,2 +1 @@
-export { AspectRatio } from './AspectRatio'
 export type { AspectRatioProps, Ratio } from './AspectRatio'
diff --git a/packages/react/src/Image/Image.test.tsx b/packages/react/src/Image/Image.test.tsx
index dbb18575a1..c3035ca535 100644
--- a/packages/react/src/Image/Image.test.tsx
+++ b/packages/react/src/Image/Image.test.tsx
@@ -38,6 +38,15 @@ describe('Image', () => {
     expect(component).toHaveClass('ams-image--cover')
   })
 
+  it('renders class names to display the image in a given aspect ratio', () => {
+    const { container } = render(<Image aspectRatio="x-tall" />)
+
+    const component = container.querySelector(':only-child')
+
+    expect(component).toHaveClass('ams-aspect-ratio')
+    expect(component).toHaveClass('ams-aspect-ratio--x-tall')
+  })
+
   it('supports ForwardRef in React', () => {
     const ref = createRef<HTMLImageElement>()
 
diff --git a/packages/react/src/Image/Image.tsx b/packages/react/src/Image/Image.tsx
index 38a857e0dd..d94e51bdfb 100644
--- a/packages/react/src/Image/Image.tsx
+++ b/packages/react/src/Image/Image.tsx
@@ -6,15 +6,25 @@
 import clsx from 'clsx'
 import { forwardRef } from 'react'
 import type { ForwardedRef, ImgHTMLAttributes } from 'react'
+import { AspectRatioProps } from '../AspectRatio'
 
-export type ImageProps = {
+export type ImageProps = AspectRatioProps & {
   /** Whether to display the image exactly as large as its container. This will clip the image if necessary. */
   cover?: boolean
 } & ImgHTMLAttributes<HTMLImageElement>
 
 export const Image = forwardRef(
-  ({ className, cover = false, ...restProps }: ImageProps, ref: ForwardedRef<HTMLImageElement>) => (
-    <img {...restProps} ref={ref} className={clsx('ams-image', cover && 'ams-image--cover', className)} />
+  ({ className, cover = false, aspectRatio, ...restProps }: ImageProps, ref: ForwardedRef<HTMLImageElement>) => (
+    <img
+      {...restProps}
+      ref={ref}
+      className={clsx(
+        'ams-image',
+        cover && 'ams-image--cover',
+        aspectRatio && `ams-aspect-ratio ams-aspect-ratio--${aspectRatio}`,
+        className,
+      )}
+    />
   ),
 )
 
diff --git a/storybook/src/components/AspectRatio/AspectRatio.docs.mdx b/storybook/src/components/AspectRatio/AspectRatio.docs.mdx
deleted file mode 100644
index 24a212a64a..0000000000
--- a/storybook/src/components/AspectRatio/AspectRatio.docs.mdx
+++ /dev/null
@@ -1,45 +0,0 @@
-{/* @license CC0-1.0 */}
-
-import { Canvas, Controls, Markdown, Meta, Primary } from "@storybook/blocks";
-import * as AspectRatioStories from "./AspectRatio.stories.tsx";
-import README from "../../../../packages/css/src/components/aspect-ratio/README.md?raw";
-
-<Meta of={AspectRatioStories} />
-
-<Markdown>{README}</Markdown>
-
-<Primary />
-
-<Controls />
-
-## Examples
-
-### Double extra wide
-
-We only use this aspect ratio for a ‘hero’ image across the entire website width.
-
-<Canvas of={AspectRatioStories.DoubleExtraWide} />
-
-### Extra wide
-
-<Canvas of={AspectRatioStories.ExtraWide} />
-
-### Wide
-
-<Canvas of={AspectRatioStories.Wide} />
-
-### Square
-
-<Canvas of={AspectRatioStories.Square} />
-
-### Tall
-
-<Canvas of={AspectRatioStories.Tall} />
-
-### Extra tall
-
-This variant may be suitable for telephones.
-Most devices nowadays have an aspect ratio of 9:19.5.
-Images of 9:16 fill approximately 80% of the screen.
-
-<Canvas of={AspectRatioStories.ExtraTall} />
diff --git a/storybook/src/components/AspectRatio/AspectRatio.stories.tsx b/storybook/src/components/AspectRatio/AspectRatio.stories.tsx
deleted file mode 100644
index d1814cc75a..0000000000
--- a/storybook/src/components/AspectRatio/AspectRatio.stories.tsx
+++ /dev/null
@@ -1,108 +0,0 @@
-/**
- * @license EUPL-1.2+
- * Copyright Gemeente Amsterdam
- */
-
-import { Image } from '@amsterdam/design-system-react'
-import { AspectRatio } from '@amsterdam/design-system-react/src'
-import { Meta, StoryObj } from '@storybook/react'
-
-const meta = {
-  title: 'Components/Layout/Aspect Ratio',
-  component: AspectRatio,
-  args: {
-    ratio: 'square',
-  },
-  argTypes: {
-    ratio: {
-      control: 'radio',
-      options: ['2x-wide', 'x-wide', 'wide', 'square', 'tall', 'x-tall'],
-    },
-  },
-} satisfies Meta<typeof AspectRatio>
-
-export default meta
-
-type Story = StoryObj<typeof meta>
-
-const storyConfig = {
-  '2x-wide': {
-    image: 'https://picsum.photos/1152/360',
-  },
-  'x-wide': {
-    image: 'https://picsum.photos/640/360',
-  },
-  wide: {
-    image: 'https://picsum.photos/480/360',
-  },
-  square: {
-    image: 'https://picsum.photos/360/360',
-  },
-  tall: {
-    image: 'https://picsum.photos/360/480',
-  },
-  'x-tall': {
-    image: 'https://picsum.photos/360/640',
-  },
-}
-
-const StoryTemplate: Story = {
-  decorators: [
-    (Story) => (
-      <div style={{ display: 'flex', justifyContent: 'center' }}>
-        <Story />
-      </div>
-    ),
-  ],
-  render: ({ ratio }) => (
-    <AspectRatio ratio={ratio}>
-      <Image alt="" src={storyConfig[ratio ?? 'square'].image} />
-    </AspectRatio>
-  ),
-}
-
-export const Default: Story = {
-  ...StoryTemplate,
-}
-
-export const DoubleExtraWide: Story = {
-  ...StoryTemplate,
-  args: {
-    ratio: '2x-wide',
-  },
-}
-
-export const ExtraWide: Story = {
-  ...StoryTemplate,
-  args: {
-    ratio: 'x-wide',
-  },
-}
-
-export const Wide: Story = {
-  ...StoryTemplate,
-  args: {
-    ratio: 'wide',
-  },
-}
-
-export const Square: Story = {
-  ...StoryTemplate,
-  args: {
-    ratio: 'square',
-  },
-}
-
-export const Tall: Story = {
-  ...StoryTemplate,
-  args: {
-    ratio: 'tall',
-  },
-}
-
-export const ExtraTall: Story = {
-  ...StoryTemplate,
-  args: {
-    ratio: 'x-tall',
-  },
-}
diff --git a/storybook/src/components/Card/Card.stories.tsx b/storybook/src/components/Card/Card.stories.tsx
index 1ce91605cb..f756b8fd8b 100644
--- a/storybook/src/components/Card/Card.stories.tsx
+++ b/storybook/src/components/Card/Card.stories.tsx
@@ -3,7 +3,7 @@
  * Copyright Gemeente Amsterdam
  */
 
-import { AspectRatio, Heading, Image, Paragraph } from '@amsterdam/design-system-react'
+import { Heading, Image, Paragraph } from '@amsterdam/design-system-react'
 import { Card } from '@amsterdam/design-system-react/src'
 import { Meta, StoryObj } from '@storybook/react'
 import { exampleTopTask } from '../shared/exampleContent'
@@ -62,9 +62,7 @@ export const WithTagline: Story = {
 export const WithImage: Story = {
   args: {
     children: [
-      <AspectRatio key={1} ratio="wide">
-        <Image alt="" src="https://picsum.photos/480/360" />
-      </AspectRatio>,
+      <Image key={1} alt="" aspectRatio="wide" src="https://picsum.photos/480/360" />,
       <Card.HeadingGroup key={2} tagline="Nieuws">
         <Heading size="level-4">
           <Card.Link href="/">Nederlands eerste houten woonwijk komt in Zuidoost</Card.Link>
diff --git a/storybook/src/components/Image/Image.docs.mdx b/storybook/src/components/Image/Image.docs.mdx
index 6c94c47466..a498e1a977 100644
--- a/storybook/src/components/Image/Image.docs.mdx
+++ b/storybook/src/components/Image/Image.docs.mdx
@@ -22,6 +22,10 @@ Don’t forget to still include the required `src` attribute.
 
 <Canvas of={ImageStories.MultipleSources} />
 
+### Provide aspect ratio
+
+{/* TODO: add aspect ratio story */}
+
 ### Prevent unnecessary loading
 
 Set the `loading` attribute (see [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#loading)) to `lazy` and the browser will wait to load the image until it is close to the viewport.
diff --git a/storybook/src/components/Image/Image.stories.tsx b/storybook/src/components/Image/Image.stories.tsx
index 34922db809..e1102bb126 100644
--- a/storybook/src/components/Image/Image.stories.tsx
+++ b/storybook/src/components/Image/Image.stories.tsx
@@ -42,6 +42,8 @@ export const MultipleSources: Story = {
   },
 }
 
+// TODO: add aspect ratio story
+
 export const LazyLoading: Story = {
   args: {
     alt: '',
diff --git a/storybook/src/components/Overlap/Overlap.stories.tsx b/storybook/src/components/Overlap/Overlap.stories.tsx
index 0db19d72ac..b79c5a0bae 100644
--- a/storybook/src/components/Overlap/Overlap.stories.tsx
+++ b/storybook/src/components/Overlap/Overlap.stories.tsx
@@ -3,7 +3,7 @@
  * Copyright Gemeente Amsterdam
  */
 
-import { AspectRatio, Grid, Image, SearchField } from '@amsterdam/design-system-react'
+import { Grid, Image, SearchField } from '@amsterdam/design-system-react'
 import { Overlap } from '@amsterdam/design-system-react/src'
 import { Meta, StoryObj } from '@storybook/react'
 
@@ -19,15 +19,15 @@ type Story = StoryObj<typeof meta>
 export const Default: Story = {
   args: {
     children: [
-      <AspectRatio key={1} ratio="2x-wide">
-        <Image
-          alt=""
-          cover
-          sizes="(max-width: 36rem) 640px, (max-width: 68rem) 1280px, 1600px"
-          src="https://picsum.photos/1600/500"
-          srcSet="https://picsum.photos/640/200 640w, https://picsum.photos/1280/400 1280w, https://picsum.photos/1600/500 1600w"
-        />
-      </AspectRatio>,
+      <Image
+        key={1}
+        alt=""
+        cover
+        aspectRatio="2x-wide"
+        sizes="(max-width: 36rem) 640px, (max-width: 68rem) 1280px, 1600px"
+        src="https://picsum.photos/1600/500"
+        srcSet="https://picsum.photos/640/200 640w, https://picsum.photos/1280/400 1280w, https://picsum.photos/1600/500 1600w"
+      />,
       <Grid key={2} style={{ alignSelf: 'center' }}>
         <Grid.Cell span={{ narrow: 4, medium: 6, wide: 8 }} start={{ narrow: 1, medium: 2, wide: 3 }}>
           <SearchField onSubmit={(e) => e.preventDefault()}>
diff --git a/storybook/src/pages/amsterdam/ArticlePage/ArticleHeader.tsx b/storybook/src/pages/amsterdam/ArticlePage/ArticleHeader.tsx
index 2d009b8389..e36b0ab879 100644
--- a/storybook/src/pages/amsterdam/ArticlePage/ArticleHeader.tsx
+++ b/storybook/src/pages/amsterdam/ArticlePage/ArticleHeader.tsx
@@ -1,4 +1,4 @@
-import { AspectRatio, Grid, Heading, Image, Overlap, Paragraph } from '@amsterdam/design-system-react'
+import { Grid, Heading, Image, Overlap, Paragraph } from '@amsterdam/design-system-react'
 import type { ArticlePageProps } from './ArticlePage'
 
 type ArticleHeaderProps = Pick<ArticlePageProps, 'heading' | 'imageSrc'>
@@ -12,9 +12,7 @@ export const ArticleHeader = ({ heading, imageSrc }: ArticleHeaderProps) => (
       </Grid.Cell>
     </Grid>
     <Overlap>
-      <AspectRatio ratio="2x-wide">
-        <Image alt="" loading="lazy" src={imageSrc} />
-      </AspectRatio>
+      <Image alt="" loading="lazy" aspectRatio="2x-wide" src={imageSrc} />
     </Overlap>
   </header>
 )
diff --git a/storybook/src/pages/amsterdam/HomePage/HomeNews.tsx b/storybook/src/pages/amsterdam/HomePage/HomeNews.tsx
index 6fcdfc09f6..944979e7e8 100644
--- a/storybook/src/pages/amsterdam/HomePage/HomeNews.tsx
+++ b/storybook/src/pages/amsterdam/HomePage/HomeNews.tsx
@@ -1,4 +1,4 @@
-import { AspectRatio, Card, Grid, Heading, Image } from '@amsterdam/design-system-react'
+import { Card, Grid, Heading, Image } from '@amsterdam/design-system-react'
 
 export const HomeNews = () => (
   <Grid paddingVertical="medium">
@@ -7,9 +7,7 @@ export const HomeNews = () => (
     </Grid.Cell>
     <Grid.Cell span={4}>
       <Card>
-        <AspectRatio ratio="x-wide">
-          <Image alt="" src="https://picsum.photos/640/360?random=1" />
-        </AspectRatio>
+        <Image alt="" aspectRatio="x-wide" src="https://picsum.photos/640/360?random=1" />
         <Card.HeadingGroup tagline="Nieuws">
           <Heading level={2} size="level-4">
             <Card.Link href="#">Nederlands eerste houten woonwijk komt in Zuidoost</Card.Link>
@@ -19,9 +17,7 @@ export const HomeNews = () => (
     </Grid.Cell>
     <Grid.Cell span={4}>
       <Card>
-        <AspectRatio ratio="x-wide">
-          <Image alt="" src="https://picsum.photos/640/360?random=2" />
-        </AspectRatio>
+        <Image alt="" aspectRatio="x-wide" src="https://picsum.photos/640/360?random=2" />
         <Card.HeadingGroup tagline="Nieuws">
           <Heading level={2} size="level-4">
             <Card.Link href="#">Gratis openbaar vervoer voor kinderen</Card.Link>
@@ -31,9 +27,7 @@ export const HomeNews = () => (
     </Grid.Cell>
     <Grid.Cell span={4}>
       <Card>
-        <AspectRatio ratio="x-wide">
-          <Image alt="" src="https://picsum.photos/640/360?random=3" />
-        </AspectRatio>
+        <Image alt="" aspectRatio="x-wide" src="https://picsum.photos/640/360?random=3" />
         <Card.HeadingGroup tagline="Nieuws">
           <Heading level={2} size="level-4">
             <Card.Link href="#">Zonnepanelen op uw dak? Zo houdt u uw huis veilig</Card.Link>

From 859edb9472ff1574f5b4186014dd4922f620d994 Mon Sep 17 00:00:00 2001
From: Ruben Sibon <r.sibon@amsterdam.nl>
Date: Fri, 20 Sep 2024 14:01:22 +0200
Subject: [PATCH 02/42] WIP(aspect-ratio): clarifying TODO comment

---
 packages/css/src/components/aspect-ratio/aspect-ratio.scss | 1 +
 1 file changed, 1 insertion(+)

diff --git a/packages/css/src/components/aspect-ratio/aspect-ratio.scss b/packages/css/src/components/aspect-ratio/aspect-ratio.scss
index b4a27f3c20..521e5de3d3 100644
--- a/packages/css/src/components/aspect-ratio/aspect-ratio.scss
+++ b/packages/css/src/components/aspect-ratio/aspect-ratio.scss
@@ -8,6 +8,7 @@
   inline-size: fit-content;
 }
 
+// TODO: needed on a wrapping element around the media element? I.e. Figure?
 .ams-aspect-ratio__container {
   overflow: hidden;
   position: relative;

From 999946659104fb887711da276f63302ad137785d Mon Sep 17 00:00:00 2001
From: Ruben Sibon <r.sibon@amsterdam.nl>
Date: Wed, 16 Oct 2024 13:56:53 +0200
Subject: [PATCH 03/42] fix: apply ratio to Breakout stories

---
 storybook/src/components/Breakout/Breakout.stories.tsx | 10 +++-------
 1 file changed, 3 insertions(+), 7 deletions(-)

diff --git a/storybook/src/components/Breakout/Breakout.stories.tsx b/storybook/src/components/Breakout/Breakout.stories.tsx
index 383261a874..78a676f463 100644
--- a/storybook/src/components/Breakout/Breakout.stories.tsx
+++ b/storybook/src/components/Breakout/Breakout.stories.tsx
@@ -3,7 +3,7 @@
  * Copyright Gemeente Amsterdam
  */
 
-import { AspectRatio, Image, Paragraph, Screen, Spotlight } from '@amsterdam/design-system-react'
+import { Image, Paragraph, Screen, Spotlight } from '@amsterdam/design-system-react'
 import { Breakout } from '@amsterdam/design-system-react/src'
 import { Meta, StoryObj } from '@storybook/react'
 
@@ -45,9 +45,7 @@ export const Default: Story = {
         rowSpan={2}
         rowStart={1}
       >
-        <AspectRatio ratio="square">
-          <Image alt="" src="https://picsum.photos/960/960" />
-        </AspectRatio>
+        <Image alt="" src="https://picsum.photos/960/960" aspectRatio="square" />
       </Breakout.Cell>,
     ],
   },
@@ -57,9 +55,7 @@ export const VerticalLayout: Story = {
   args: {
     children: [
       <Breakout.Cell colSpan="all" has="figure" rowSpan={2} rowStart={1}>
-        <AspectRatio ratio="x-wide">
-          <Image alt="" src="https://picsum.photos/1600/900" />
-        </AspectRatio>
+        <Image alt="" src="https://picsum.photos/1600/900" aspectRatio="x-wide" />
       </Breakout.Cell>,
       <Breakout.Cell colSpan="all" has="spotlight" rowSpan={2} rowStart={2}>
         <Spotlight />

From 239a0d6feda13cb7b9cd18bf3915512d801d7926 Mon Sep 17 00:00:00 2001
From: Ruben Sibon <r.sibon@amsterdam.nl>
Date: Wed, 16 Oct 2024 14:27:05 +0200
Subject: [PATCH 04/42] =?UTF-8?q?docs(ratio):=20=F0=9F=93=84=20more=20prop?=
 =?UTF-8?q?=20descr?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/react/src/AspectRatio/AspectRatio.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/react/src/AspectRatio/AspectRatio.tsx b/packages/react/src/AspectRatio/AspectRatio.tsx
index 1198968b22..7024766f07 100644
--- a/packages/react/src/AspectRatio/AspectRatio.tsx
+++ b/packages/react/src/AspectRatio/AspectRatio.tsx
@@ -6,6 +6,6 @@
 export type Ratio = 'x-tall' | 'tall' | 'square' | 'wide' | 'x-wide' | '2x-wide'
 
 export type AspectRatioProps = {
-  /** The dimensions. */
+  /** The ratio of the horizontal and vertical dimensions. */
   aspectRatio?: Ratio
 }

From 5c8569583fa888a93c530cdb8132b527f2ffe172 Mon Sep 17 00:00:00 2001
From: Ruben Sibon <r.sibon@amsterdam.nl>
Date: Wed, 16 Oct 2024 14:41:33 +0200
Subject: [PATCH 05/42] =?UTF-8?q?docs(ratio):=20=F0=9F=93=84=20design=20to?=
 =?UTF-8?q?ken=20docs?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../design-tokens/aspect-ratio.docs.mdx       | 22 +++++++++++++++++++
 1 file changed, 22 insertions(+)
 create mode 100644 storybook/src/foundation/design-tokens/aspect-ratio.docs.mdx

diff --git a/storybook/src/foundation/design-tokens/aspect-ratio.docs.mdx b/storybook/src/foundation/design-tokens/aspect-ratio.docs.mdx
new file mode 100644
index 0000000000..faf33bcd73
--- /dev/null
+++ b/storybook/src/foundation/design-tokens/aspect-ratio.docs.mdx
@@ -0,0 +1,22 @@
+{/* @license CC0-1.0 */}
+
+import { Meta } from "@storybook/blocks";
+
+<Meta title="Brand/Design Tokens/Aspect Ratio" />
+
+# Aspect Ratio
+
+Constrain elements like images and videos to one of the available aspect ratios.
+
+## Widths
+
+We have 6 named aspect ratios:
+
+| Token name                 | ratio  | Example                                                                                                                         |
+| :------------------------- | :----: | ------------------------------------------------------------------------------------------------------------------------------- |
+| `ams.aspect-ratio.x-tall`  | 9 / 16 | <div className="ams-docs-token-example--space" style={{ blockSize: '3rem', aspectRatio: 'var(--ams-aspect-ratio-x-tall)' }} />  |
+| `ams.aspect-ratio.tall`    | 3 / 4  | <div className="ams-docs-token-example--space" style={{ blockSize: '3rem', aspectRatio: 'var(--ams-aspect-ratio-tall)' }} />    |
+| `ams.aspect-ratio.square`  | 1 / 1  | <div className="ams-docs-token-example--space" style={{ blockSize: '3rem', aspectRatio: 'var(--ams-aspect-ratio-square)' }} />  |
+| `ams.aspect-ratio.wide`    | 4 / 3  | <div className="ams-docs-token-example--space" style={{ blockSize: '3rem', aspectRatio: 'var(--ams-aspect-ratio-wide)' }} />    |
+| `ams.aspect-ratio.x-wide`  | 16 / 9 | <div className="ams-docs-token-example--space" style={{ blockSize: '3rem', aspectRatio: 'var(--ams-aspect-ratio-x-wide)' }} />  |
+| `ams.aspect-ratio.2x-wide` | 16 / 5 | <div className="ams-docs-token-example--space" style={{ blockSize: '3rem', aspectRatio: 'var(--ams-aspect-ratio-2x-wide)' }} /> |

From 55943f96a12a790d5757cb6c2ce2166a982aec7b Mon Sep 17 00:00:00 2001
From: Ruben Sibon <r.sibon@amsterdam.nl>
Date: Wed, 16 Oct 2024 15:09:12 +0200
Subject: [PATCH 06/42] =?UTF-8?q?docs(ratio):=20=F0=9F=AA=9E=20refer=20to?=
 =?UTF-8?q?=20token=20docs?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/css/src/components/image/README.md | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/packages/css/src/components/image/README.md b/packages/css/src/components/image/README.md
index a0c96847d3..774f46ba27 100644
--- a/packages/css/src/components/image/README.md
+++ b/packages/css/src/components/image/README.md
@@ -15,8 +15,7 @@ Displays an image.
   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.
-  <!-- TODO: document usage of aspectRatio prop -->
-- Ensure that the aspect ratio of the image is supported by the [Aspect Ratio](/docs/components-layout-aspect-ratio--docs) component.
+- Ensure that the aspect ratio of the image is supported by the [aspect ratio token](/docs/brand-design-tokens-aspect-ratio--docs).
 
 ## Relevant WCAG requirements
 

From cbe31d219b6caf2a4968a2815098bff5fa58fdb5 Mon Sep 17 00:00:00 2001
From: Ruben Sibon <r.sibon@amsterdam.nl>
Date: Wed, 16 Oct 2024 15:21:36 +0200
Subject: [PATCH 07/42] =?UTF-8?q?chore(ratio):=20=F0=9F=97=91=EF=B8=8F=20r?=
 =?UTF-8?q?emove=20out-of-scope=20code?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/css/src/components/aspect-ratio/aspect-ratio.scss | 6 ------
 1 file changed, 6 deletions(-)

diff --git a/packages/css/src/components/aspect-ratio/aspect-ratio.scss b/packages/css/src/components/aspect-ratio/aspect-ratio.scss
index 521e5de3d3..70f44c05d0 100644
--- a/packages/css/src/components/aspect-ratio/aspect-ratio.scss
+++ b/packages/css/src/components/aspect-ratio/aspect-ratio.scss
@@ -8,12 +8,6 @@
   inline-size: fit-content;
 }
 
-// TODO: needed on a wrapping element around the media element? I.e. Figure?
-.ams-aspect-ratio__container {
-  overflow: hidden;
-  position: relative;
-}
-
 .ams-aspect-ratio--x-tall {
   aspect-ratio: var(--ams-aspect-ratio-x-tall);
 }

From a612015ced5cc9789ab667279973162c2eb100e9 Mon Sep 17 00:00:00 2001
From: Ruben Sibon <r.sibon@amsterdam.nl>
Date: Fri, 18 Oct 2024 09:52:49 +0200
Subject: [PATCH 08/42] =?UTF-8?q?test(ratio):=20=F0=9F=A7=AA=20test=20for?=
 =?UTF-8?q?=20ratio=20class=20names?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/react/src/Image/Image.test.tsx | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/packages/react/src/Image/Image.test.tsx b/packages/react/src/Image/Image.test.tsx
index c3035ca535..be245160ac 100644
--- a/packages/react/src/Image/Image.test.tsx
+++ b/packages/react/src/Image/Image.test.tsx
@@ -43,8 +43,7 @@ describe('Image', () => {
 
     const component = container.querySelector(':only-child')
 
-    expect(component).toHaveClass('ams-aspect-ratio')
-    expect(component).toHaveClass('ams-aspect-ratio--x-tall')
+    expect(component).toHaveClass('ams-image ams-image-aspect-ratio--x-tall')
   })
 
   it('supports ForwardRef in React', () => {

From e35e71ff76ad4020197ed6187002e9153ed4354b Mon Sep 17 00:00:00 2001
From: Ruben Sibon <r.sibon@amsterdam.nl>
Date: Fri, 18 Oct 2024 11:02:57 +0200
Subject: [PATCH 09/42] =?UTF-8?q?feat(ratio):=20=F0=9F=AA=A9=20add=20class?=
 =?UTF-8?q?=20names=20to=20Image?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/css/src/components/image/image.scss | 28 ++++++++++++++++++++
 packages/react/src/Image/Image.tsx           |  2 +-
 2 files changed, 29 insertions(+), 1 deletion(-)

diff --git a/packages/css/src/components/image/image.scss b/packages/css/src/components/image/image.scss
index 05d5a99a70..9500c3dbdf 100644
--- a/packages/css/src/components/image/image.scss
+++ b/packages/css/src/components/image/image.scss
@@ -9,6 +9,34 @@
   max-inline-size: 100%; /* [1] */
   vertical-align: middle; /* [2] */
 
+  &[class*="ams-image-aspect-ratio--"] {
+    inline-size: fit-content;
+  }
+
+  &-aspect-ratio--x-tall {
+    aspect-ratio: var(--ams-aspect-ratio-x-tall);
+  }
+
+  &-aspect-ratio--tall {
+    aspect-ratio: var(--ams-aspect-ratio-tall);
+  }
+
+  &-aspect-ratio--square {
+    aspect-ratio: var(--ams-aspect-ratio-square);
+  }
+
+  &-aspect-ratio--wide {
+    aspect-ratio: var(--ams-aspect-ratio-wide);
+  }
+
+  &-aspect-ratio--x-wide {
+    aspect-ratio: var(--ams-aspect-ratio-x-wide);
+  }
+
+  &-aspect-ratio--2x-wide {
+    aspect-ratio: var(--ams-aspect-ratio-2x-wide);
+  }
+
   &--cover {
     object-fit: cover;
   }
diff --git a/packages/react/src/Image/Image.tsx b/packages/react/src/Image/Image.tsx
index d94e51bdfb..88a49b7118 100644
--- a/packages/react/src/Image/Image.tsx
+++ b/packages/react/src/Image/Image.tsx
@@ -21,7 +21,7 @@ export const Image = forwardRef(
       className={clsx(
         'ams-image',
         cover && 'ams-image--cover',
-        aspectRatio && `ams-aspect-ratio ams-aspect-ratio--${aspectRatio}`,
+        aspectRatio && `ams-image-aspect-ratio--${aspectRatio}`,
         className,
       )}
     />

From d0874a318d12c61b10d6a0d3d0fe5a969e861ec7 Mon Sep 17 00:00:00 2001
From: Ruben Sibon <r.sibon@amsterdam.nl>
Date: Fri, 18 Oct 2024 17:29:19 +0200
Subject: [PATCH 10/42] =?UTF-8?q?feat(ratio):=20=F0=9F=A6=8B=20aspect-rati?=
 =?UTF-8?q?o=20mixins?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../src/components/aspect-ratio/_mixins.scss  | 19 ++++++++++++
 .../components/aspect-ratio/aspect-ratio.scss | 30 +++----------------
 packages/css/src/components/image/image.scss  | 28 +++--------------
 3 files changed, 27 insertions(+), 50 deletions(-)
 create mode 100644 packages/css/src/components/aspect-ratio/_mixins.scss

diff --git a/packages/css/src/components/aspect-ratio/_mixins.scss b/packages/css/src/components/aspect-ratio/_mixins.scss
new file mode 100644
index 0000000000..393d2598ab
--- /dev/null
+++ b/packages/css/src/components/aspect-ratio/_mixins.scss
@@ -0,0 +1,19 @@
+/**
+ * @license EUPL-1.2+
+ * Copyright Gemeente Amsterdam
+ */
+
+@mixin ams-aspect-ratio {
+  block-size: auto;
+  inline-size: fit-content;
+  overflow: hidden;
+  position: relative;
+}
+
+@mixin generate-aspect-ratio-classes($infix: "") {
+  @each $name in ("x-tall", "tall", "square", "wide", "x-wide", "2x-wide") {
+    &#{$infix}--#{$name} {
+      aspect-ratio: var(--ams-aspect-ratio-#{$name});
+    }
+  }
+}
diff --git a/packages/css/src/components/aspect-ratio/aspect-ratio.scss b/packages/css/src/components/aspect-ratio/aspect-ratio.scss
index 70f44c05d0..5b5aef5f40 100644
--- a/packages/css/src/components/aspect-ratio/aspect-ratio.scss
+++ b/packages/css/src/components/aspect-ratio/aspect-ratio.scss
@@ -3,31 +3,9 @@
  * Copyright Gemeente Amsterdam
  */
 
-.ams-aspect-ratio {
-  block-size: auto;
-  inline-size: fit-content;
-}
-
-.ams-aspect-ratio--x-tall {
-  aspect-ratio: var(--ams-aspect-ratio-x-tall);
-}
+@import "./mixins";
 
-.ams-aspect-ratio--tall {
-  aspect-ratio: var(--ams-aspect-ratio-tall);
-}
-
-.ams-aspect-ratio--square {
-  aspect-ratio: var(--ams-aspect-ratio-square);
-}
-
-.ams-aspect-ratio--wide {
-  aspect-ratio: var(--ams-aspect-ratio-wide);
-}
-
-.ams-aspect-ratio--x-wide {
-  aspect-ratio: var(--ams-aspect-ratio-x-wide);
-}
-
-.ams-aspect-ratio--2x-wide {
-  aspect-ratio: var(--ams-aspect-ratio-2x-wide);
+.ams-aspect-ratio {
+  @include ams-aspect-ratio;
+  @include generate-aspect-ratio-classes;
 }
diff --git a/packages/css/src/components/image/image.scss b/packages/css/src/components/image/image.scss
index 9500c3dbdf..868839286a 100644
--- a/packages/css/src/components/image/image.scss
+++ b/packages/css/src/components/image/image.scss
@@ -3,6 +3,8 @@
  * Copyright Gemeente Amsterdam
  */
 
+@import "../aspect-ratio/mixins";
+
 .ams-image {
   block-size: auto; /* [1] */
   font-style: italic; /* [3] */
@@ -10,32 +12,10 @@
   vertical-align: middle; /* [2] */
 
   &[class*="ams-image-aspect-ratio--"] {
-    inline-size: fit-content;
-  }
-
-  &-aspect-ratio--x-tall {
-    aspect-ratio: var(--ams-aspect-ratio-x-tall);
-  }
-
-  &-aspect-ratio--tall {
-    aspect-ratio: var(--ams-aspect-ratio-tall);
-  }
-
-  &-aspect-ratio--square {
-    aspect-ratio: var(--ams-aspect-ratio-square);
-  }
-
-  &-aspect-ratio--wide {
-    aspect-ratio: var(--ams-aspect-ratio-wide);
+    @include ams-aspect-ratio;
   }
 
-  &-aspect-ratio--x-wide {
-    aspect-ratio: var(--ams-aspect-ratio-x-wide);
-  }
-
-  &-aspect-ratio--2x-wide {
-    aspect-ratio: var(--ams-aspect-ratio-2x-wide);
-  }
+  @include generate-aspect-ratio-classes("-aspect-ratio");
 
   &--cover {
     object-fit: cover;

From a51445f29131cc4196a6190880dbbb800f951586 Mon Sep 17 00:00:00 2001
From: Ruben Sibon <r.sibon@amsterdam.nl>
Date: Fri, 18 Oct 2024 17:29:55 +0200
Subject: [PATCH 11/42] =?UTF-8?q?docs(ratio)=20=F0=9F=93=84=20cleanup=20an?=
 =?UTF-8?q?d=20expand?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/css/src/components/image/README.md      | 2 +-
 storybook/src/components/Image/Image.stories.tsx | 2 --
 2 files changed, 1 insertion(+), 3 deletions(-)

diff --git a/packages/css/src/components/image/README.md b/packages/css/src/components/image/README.md
index 774f46ba27..40e13674d3 100644
--- a/packages/css/src/components/image/README.md
+++ b/packages/css/src/components/image/README.md
@@ -15,7 +15,7 @@ Displays an image.
   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 token](/docs/brand-design-tokens-aspect-ratio--docs).
+- Ensure that the aspect ratio of the image is supported by the [aspect ratio token](/docs/brand-design-tokens-aspect-ratio--docs). Alternatively, use the `cover` Image prop or the `object-fit: contain` CSS property to display the image correctly.
 
 ## Relevant WCAG requirements
 
diff --git a/storybook/src/components/Image/Image.stories.tsx b/storybook/src/components/Image/Image.stories.tsx
index 76002b8bba..5bb9770bea 100644
--- a/storybook/src/components/Image/Image.stories.tsx
+++ b/storybook/src/components/Image/Image.stories.tsx
@@ -42,8 +42,6 @@ export const ResponsiveImages: Story = {
   },
 }
 
-// TODO: add aspect ratio story
-
 export const LazyLoading: Story = {
   args: {
     alt: '',

From 6232739d112cf38190e50cdca4b267e4051b2068 Mon Sep 17 00:00:00 2001
From: Ruben Sibon <r.sibon@amsterdam.nl>
Date: Fri, 18 Oct 2024 17:40:14 +0200
Subject: [PATCH 12/42] fix(ratio): docs

---
 storybook/src/foundation/design-tokens/aspect-ratio.docs.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/storybook/src/foundation/design-tokens/aspect-ratio.docs.mdx b/storybook/src/foundation/design-tokens/aspect-ratio.docs.mdx
index faf33bcd73..a315184832 100644
--- a/storybook/src/foundation/design-tokens/aspect-ratio.docs.mdx
+++ b/storybook/src/foundation/design-tokens/aspect-ratio.docs.mdx
@@ -8,7 +8,7 @@ import { Meta } from "@storybook/blocks";
 
 Constrain elements like images and videos to one of the available aspect ratios.
 
-## Widths
+## Ratios
 
 We have 6 named aspect ratios:
 

From be946f108780f60c1b30a8e991d473e7eedd2806 Mon Sep 17 00:00:00 2001
From: Ruben Sibon <r.sibon@amsterdam.nl>
Date: Fri, 18 Oct 2024 17:45:33 +0200
Subject: [PATCH 13/42] chore: remove unnecessary todo

---
 storybook/src/components/Image/Image.docs.mdx | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/storybook/src/components/Image/Image.docs.mdx b/storybook/src/components/Image/Image.docs.mdx
index 0924a2e695..6126030f7b 100644
--- a/storybook/src/components/Image/Image.docs.mdx
+++ b/storybook/src/components/Image/Image.docs.mdx
@@ -22,10 +22,6 @@ Don’t forget to still include the required `src` attribute.
 
 <Canvas of={ImageStories.ResponsiveImages} />
 
-### Provide aspect ratio
-
-{/* TODO: add aspect ratio story */}
-
 ### Lazy loading
 
 Set the `loading` attribute (see [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#loading)) to `lazy` and the browser will wait to load the image until it is close to the viewport.

From 441bd2e66bf5367c2dcc6a7286f4e2cf4c379663 Mon Sep 17 00:00:00 2001
From: Ruben Sibon <r.sibon@amsterdam.nl>
Date: Wed, 30 Oct 2024 08:58:12 +0100
Subject: [PATCH 14/42] =?UTF-8?q?style(image):=20=E2=99=BB=EF=B8=8F=20=20p?=
 =?UTF-8?q?rop=20order=20and=20sorting?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/react/src/Image/Image.tsx                         | 7 ++++---
 .../src/pages/amsterdam/ArticlePage/ArticleHeader.tsx      | 2 +-
 2 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/packages/react/src/Image/Image.tsx b/packages/react/src/Image/Image.tsx
index 88a49b7118..27b34ede72 100644
--- a/packages/react/src/Image/Image.tsx
+++ b/packages/react/src/Image/Image.tsx
@@ -8,13 +8,14 @@ import { forwardRef } from 'react'
 import type { ForwardedRef, ImgHTMLAttributes } from 'react'
 import { AspectRatioProps } from '../AspectRatio'
 
-export type ImageProps = AspectRatioProps & {
+export type ImageProps = {
   /** Whether to display the image exactly as large as its container. This will clip the image if necessary. */
   cover?: boolean
-} & ImgHTMLAttributes<HTMLImageElement>
+} & AspectRatioProps &
+  ImgHTMLAttributes<HTMLImageElement>
 
 export const Image = forwardRef(
-  ({ className, cover = false, aspectRatio, ...restProps }: ImageProps, ref: ForwardedRef<HTMLImageElement>) => (
+  ({ aspectRatio, className, cover = false, ...restProps }: ImageProps, ref: ForwardedRef<HTMLImageElement>) => (
     <img
       {...restProps}
       ref={ref}
diff --git a/storybook/src/pages/amsterdam/ArticlePage/ArticleHeader.tsx b/storybook/src/pages/amsterdam/ArticlePage/ArticleHeader.tsx
index e36b0ab879..8d9b9ee151 100644
--- a/storybook/src/pages/amsterdam/ArticlePage/ArticleHeader.tsx
+++ b/storybook/src/pages/amsterdam/ArticlePage/ArticleHeader.tsx
@@ -12,7 +12,7 @@ export const ArticleHeader = ({ heading, imageSrc }: ArticleHeaderProps) => (
       </Grid.Cell>
     </Grid>
     <Overlap>
-      <Image alt="" loading="lazy" aspectRatio="2x-wide" src={imageSrc} />
+      <Image alt="" aspectRatio="2x-wide" loading="lazy" src={imageSrc} />
     </Overlap>
   </header>
 )

From 69fcdf73d3c2c27fa07b8b29f0a54440e44f8b6b Mon Sep 17 00:00:00 2001
From: Ruben Sibon <r.sibon@amsterdam.nl>
Date: Wed, 30 Oct 2024 09:48:08 +0100
Subject: [PATCH 15/42] =?UTF-8?q?refactor(ratio):=20=F0=9F=A6=8B=20remove?=
 =?UTF-8?q?=20mixin=20and=20img=20class?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../src/components/aspect-ratio/_mixins.scss  | 19 -------------------
 .../components/aspect-ratio/aspect-ratio.scss |  9 +++++----
 packages/css/src/components/image/image.scss  |  9 +++------
 packages/react/src/Image/Image.tsx            |  6 +++---
 4 files changed, 11 insertions(+), 32 deletions(-)
 delete mode 100644 packages/css/src/components/aspect-ratio/_mixins.scss

diff --git a/packages/css/src/components/aspect-ratio/_mixins.scss b/packages/css/src/components/aspect-ratio/_mixins.scss
deleted file mode 100644
index 393d2598ab..0000000000
--- a/packages/css/src/components/aspect-ratio/_mixins.scss
+++ /dev/null
@@ -1,19 +0,0 @@
-/**
- * @license EUPL-1.2+
- * Copyright Gemeente Amsterdam
- */
-
-@mixin ams-aspect-ratio {
-  block-size: auto;
-  inline-size: fit-content;
-  overflow: hidden;
-  position: relative;
-}
-
-@mixin generate-aspect-ratio-classes($infix: "") {
-  @each $name in ("x-tall", "tall", "square", "wide", "x-wide", "2x-wide") {
-    &#{$infix}--#{$name} {
-      aspect-ratio: var(--ams-aspect-ratio-#{$name});
-    }
-  }
-}
diff --git a/packages/css/src/components/aspect-ratio/aspect-ratio.scss b/packages/css/src/components/aspect-ratio/aspect-ratio.scss
index 5b5aef5f40..75da842071 100644
--- a/packages/css/src/components/aspect-ratio/aspect-ratio.scss
+++ b/packages/css/src/components/aspect-ratio/aspect-ratio.scss
@@ -3,9 +3,10 @@
  * Copyright Gemeente Amsterdam
  */
 
-@import "./mixins";
-
 .ams-aspect-ratio {
-  @include ams-aspect-ratio;
-  @include generate-aspect-ratio-classes;
+  @each $name in ("x-tall", "tall", "square", "wide", "x-wide", "2x-wide") {
+    &--#{$name} {
+      aspect-ratio: var(--ams-aspect-ratio-#{$name});
+    }
+  }
 }
diff --git a/packages/css/src/components/image/image.scss b/packages/css/src/components/image/image.scss
index 868839286a..390ae7b7c4 100644
--- a/packages/css/src/components/image/image.scss
+++ b/packages/css/src/components/image/image.scss
@@ -3,20 +3,17 @@
  * Copyright Gemeente Amsterdam
  */
 
-@import "../aspect-ratio/mixins";
-
 .ams-image {
   block-size: auto; /* [1] */
   font-style: italic; /* [3] */
   max-inline-size: 100%; /* [1] */
   vertical-align: middle; /* [2] */
 
-  &[class*="ams-image-aspect-ratio--"] {
-    @include ams-aspect-ratio;
+  &[class*="ams-aspect-ratio--"] {
+    inline-size: fit-content;
+    position: relative;
   }
 
-  @include generate-aspect-ratio-classes("-aspect-ratio");
-
   &--cover {
     object-fit: cover;
   }
diff --git a/packages/react/src/Image/Image.tsx b/packages/react/src/Image/Image.tsx
index 27b34ede72..89a1dd73c3 100644
--- a/packages/react/src/Image/Image.tsx
+++ b/packages/react/src/Image/Image.tsx
@@ -15,14 +15,14 @@ export type ImageProps = {
   ImgHTMLAttributes<HTMLImageElement>
 
 export const Image = forwardRef(
-  ({ aspectRatio, className, cover = false, ...restProps }: ImageProps, ref: ForwardedRef<HTMLImageElement>) => (
+  ({ aspectRatio, className, cover, ...restProps }: ImageProps, ref: ForwardedRef<HTMLImageElement>) => (
     <img
       {...restProps}
       ref={ref}
       className={clsx(
         'ams-image',
-        cover && 'ams-image--cover',
-        aspectRatio && `ams-image-aspect-ratio--${aspectRatio}`,
+        (cover === true || (cover === undefined && aspectRatio)) && 'ams-image--cover',
+        aspectRatio && `ams-aspect-ratio--${aspectRatio}`,
         className,
       )}
     />

From 67310879a95e22f1d066bd6fbda9e2b2fabc1ef3 Mon Sep 17 00:00:00 2001
From: Ruben Sibon <r.sibon@amsterdam.nl>
Date: Wed, 30 Oct 2024 11:16:55 +0100
Subject: [PATCH 16/42] =?UTF-8?q?refactor(ratio):=20=E2=99=BB=EF=B8=8F=20?=
 =?UTF-8?q?=20replace=20comp=20with=20common=20types?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/react/src/AspectRatio/AspectRatio.tsx | 11 -----------
 packages/react/src/AspectRatio/README.md       |  5 -----
 packages/react/src/AspectRatio/index.ts        |  1 -
 packages/react/src/Image/Image.tsx             |  4 ++--
 packages/react/src/ImageSlider/ImageSlider.tsx |  7 ++-----
 packages/react/src/common/aspectRatio.ts       |  6 ++++++
 packages/react/src/index.ts                    |  1 -
 7 files changed, 10 insertions(+), 25 deletions(-)
 delete mode 100644 packages/react/src/AspectRatio/AspectRatio.tsx
 delete mode 100644 packages/react/src/AspectRatio/README.md
 delete mode 100644 packages/react/src/AspectRatio/index.ts
 create mode 100644 packages/react/src/common/aspectRatio.ts

diff --git a/packages/react/src/AspectRatio/AspectRatio.tsx b/packages/react/src/AspectRatio/AspectRatio.tsx
deleted file mode 100644
index 7024766f07..0000000000
--- a/packages/react/src/AspectRatio/AspectRatio.tsx
+++ /dev/null
@@ -1,11 +0,0 @@
-/**
- * @license EUPL-1.2+
- * Copyright Gemeente Amsterdam
- */
-
-export type Ratio = 'x-tall' | 'tall' | 'square' | 'wide' | 'x-wide' | '2x-wide'
-
-export type AspectRatioProps = {
-  /** The ratio of the horizontal and vertical dimensions. */
-  aspectRatio?: Ratio
-}
diff --git a/packages/react/src/AspectRatio/README.md b/packages/react/src/AspectRatio/README.md
deleted file mode 100644
index 285732e7e3..0000000000
--- a/packages/react/src/AspectRatio/README.md
+++ /dev/null
@@ -1,5 +0,0 @@
-<!-- @license CC0-1.0 -->
-
-# React Aspect Ratio property
-
-[Aspect ratio documentation](../../../css/src/components/aspect-ratio/README.md)
diff --git a/packages/react/src/AspectRatio/index.ts b/packages/react/src/AspectRatio/index.ts
deleted file mode 100644
index 8f3cd26c46..0000000000
--- a/packages/react/src/AspectRatio/index.ts
+++ /dev/null
@@ -1 +0,0 @@
-export type { AspectRatioProps, Ratio } from './AspectRatio'
diff --git a/packages/react/src/Image/Image.tsx b/packages/react/src/Image/Image.tsx
index 89a1dd73c3..cd5c64bffa 100644
--- a/packages/react/src/Image/Image.tsx
+++ b/packages/react/src/Image/Image.tsx
@@ -6,7 +6,7 @@
 import clsx from 'clsx'
 import { forwardRef } from 'react'
 import type { ForwardedRef, ImgHTMLAttributes } from 'react'
-import { AspectRatioProps } from '../AspectRatio'
+import { AspectRatioProps } from '../common/aspectRatio'
 
 export type ImageProps = {
   /** Whether to display the image exactly as large as its container. This will clip the image if necessary. */
@@ -15,7 +15,7 @@ export type ImageProps = {
   ImgHTMLAttributes<HTMLImageElement>
 
 export const Image = forwardRef(
-  ({ aspectRatio, className, cover, ...restProps }: ImageProps, ref: ForwardedRef<HTMLImageElement>) => (
+  ({ aspectRatio = 'wide', className, cover, ...restProps }: ImageProps, ref: ForwardedRef<HTMLImageElement>) => (
     <img
       {...restProps}
       ref={ref}
diff --git a/packages/react/src/ImageSlider/ImageSlider.tsx b/packages/react/src/ImageSlider/ImageSlider.tsx
index a3181dfd8a..98a3e91d62 100644
--- a/packages/react/src/ImageSlider/ImageSlider.tsx
+++ b/packages/react/src/ImageSlider/ImageSlider.tsx
@@ -11,13 +11,10 @@ import { ImageSliderControls } from './ImageSliderControls'
 import { ImageSliderItem } from './ImageSliderItem'
 import { ImageSliderScroller } from './ImageSliderScroller'
 import { ImageSliderThumbnails } from './ImageSliderThumbnails'
-import { Ratio } from '../AspectRatio'
 import { Image, ImageProps } from '../Image/Image'
+import { AspectRatioProps } from '../common/aspectRatio'
 
-export type ImageSliderImageProps = ImageProps & {
-  /** Specify the aspect ratio to use for the images. */
-  aspectRatio: Ratio
-}
+export type ImageSliderImageProps = ImageProps & AspectRatioProps
 
 export type ImageSliderProps = {
   /** Display buttons to navigate to the previous or next image. */
diff --git a/packages/react/src/common/aspectRatio.ts b/packages/react/src/common/aspectRatio.ts
new file mode 100644
index 0000000000..e8d3cdb5e4
--- /dev/null
+++ b/packages/react/src/common/aspectRatio.ts
@@ -0,0 +1,6 @@
+type Ratio = 'x-tall' | 'tall' | 'square' | 'wide' | 'x-wide' | '2x-wide'
+
+export type AspectRatioProps = {
+  /** The ratio of the horizontal and vertical dimensions. */
+  aspectRatio?: Ratio
+}
diff --git a/packages/react/src/index.ts b/packages/react/src/index.ts
index 5a1b28f7a6..9b88224382 100644
--- a/packages/react/src/index.ts
+++ b/packages/react/src/index.ts
@@ -46,7 +46,6 @@ export * from './Switch'
 export * from './Spotlight'
 export * from './Card'
 export * from './Alert'
-export * from './AspectRatio'
 export * from './Footer'
 export * from './PageMenu'
 export * from './TopTaskLink'

From 04aa7d96fb8b29b952e2c5e1c03da45a556c88a3 Mon Sep 17 00:00:00 2001
From: Ruben Sibon <r.sibon@amsterdam.nl>
Date: Wed, 30 Oct 2024 13:07:30 +0100
Subject: [PATCH 17/42] =?UTF-8?q?test(image):=20=F0=9F=96=BC=EF=B8=8F=20ne?=
 =?UTF-8?q?w=20className?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Also remove redudant className
---
 packages/react/src/Image/Image.test.tsx              |  2 +-
 proprietary/tokens/README.md                         |  2 +-
 ...oportion.tokens.json => aspect-ratio.tokens.json} |  2 +-
 .../src/components/ams/aspect-ratio.tokens.json      | 12 ------------
 .../tokens/src/components/ams/avatar.tokens.json     |  2 +-
 5 files changed, 4 insertions(+), 16 deletions(-)
 rename proprietary/tokens/src/brand/ams/{proportion.tokens.json => aspect-ratio.tokens.json} (91%)
 delete mode 100644 proprietary/tokens/src/components/ams/aspect-ratio.tokens.json

diff --git a/packages/react/src/Image/Image.test.tsx b/packages/react/src/Image/Image.test.tsx
index be245160ac..aef22b892f 100644
--- a/packages/react/src/Image/Image.test.tsx
+++ b/packages/react/src/Image/Image.test.tsx
@@ -43,7 +43,7 @@ describe('Image', () => {
 
     const component = container.querySelector(':only-child')
 
-    expect(component).toHaveClass('ams-image ams-image-aspect-ratio--x-tall')
+    expect(component).toHaveClass('ams-aspect-ratio--x-tall')
   })
 
   it('supports ForwardRef in React', () => {
diff --git a/proprietary/tokens/README.md b/proprietary/tokens/README.md
index 9c2dada27b..6113bad794 100644
--- a/proprietary/tokens/README.md
+++ b/proprietary/tokens/README.md
@@ -82,7 +82,7 @@ Examples:
 :root {
   --ams-color-primary-red: #ec0000;
   --ams-space-md: 1rem;
-  --ams-proportion-wide: 4/3;
+  --ams-aspect-ratio-wide: 4/3;
   --ams-border-width-lg: 0.1875rem;
 }
 ```
diff --git a/proprietary/tokens/src/brand/ams/proportion.tokens.json b/proprietary/tokens/src/brand/ams/aspect-ratio.tokens.json
similarity index 91%
rename from proprietary/tokens/src/brand/ams/proportion.tokens.json
rename to proprietary/tokens/src/brand/ams/aspect-ratio.tokens.json
index 423a580ff5..f8c45326fa 100644
--- a/proprietary/tokens/src/brand/ams/proportion.tokens.json
+++ b/proprietary/tokens/src/brand/ams/aspect-ratio.tokens.json
@@ -1,6 +1,6 @@
 {
   "ams": {
-    "proportion": {
+    "aspect-ratio": {
       "x-tall": { "value": "9 / 16" },
       "tall": { "value": "3 / 4" },
       "square": { "value": "1 / 1" },
diff --git a/proprietary/tokens/src/components/ams/aspect-ratio.tokens.json b/proprietary/tokens/src/components/ams/aspect-ratio.tokens.json
deleted file mode 100644
index 57f889c840..0000000000
--- a/proprietary/tokens/src/components/ams/aspect-ratio.tokens.json
+++ /dev/null
@@ -1,12 +0,0 @@
-{
-  "ams": {
-    "aspect-ratio": {
-      "x-tall": { "value": "{ams.proportion.x-tall}" },
-      "tall": { "value": "{ams.proportion.tall}" },
-      "square": { "value": "{ams.proportion.square}" },
-      "wide": { "value": "{ams.proportion.wide}" },
-      "x-wide": { "value": "{ams.proportion.x-wide}" },
-      "2x-wide": { "value": "{ams.proportion.2x-wide}" }
-    }
-  }
-}
diff --git a/proprietary/tokens/src/components/ams/avatar.tokens.json b/proprietary/tokens/src/components/ams/avatar.tokens.json
index 727faa1844..820b61132f 100644
--- a/proprietary/tokens/src/components/ams/avatar.tokens.json
+++ b/proprietary/tokens/src/components/ams/avatar.tokens.json
@@ -1,7 +1,7 @@
 {
   "ams": {
     "avatar": {
-      "aspect-ratio": { "value": "{ams.proportion.square}" },
+      "aspect-ratio": { "value": "{ams.aspect-ratio.square}" },
       "font-family": { "value": "{ams.text.font-family}" },
       "font-size": { "value": "{ams.text.level.6.font-size}" },
       "font-weight": { "value": "{ams.text.font-weight.normal}" },

From 3900d6b999559c1020eb3885967aa863592939b0 Mon Sep 17 00:00:00 2001
From: Ruben Sibon <r.sibon@amsterdam.nl>
Date: Wed, 30 Oct 2024 13:43:17 +0100
Subject: [PATCH 18/42] =?UTF-8?q?docs(image):=20=F0=9F=93=84=20simplify=20?=
 =?UTF-8?q?aspect=20ratio=20docs?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 packages/css/src/components/image/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/css/src/components/image/README.md b/packages/css/src/components/image/README.md
index 40e13674d3..640892ea77 100644
--- a/packages/css/src/components/image/README.md
+++ b/packages/css/src/components/image/README.md
@@ -15,7 +15,7 @@ Displays an image.
   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 token](/docs/brand-design-tokens-aspect-ratio--docs). Alternatively, use the `cover` Image prop or the `object-fit: contain` CSS property to display the image correctly.
+- The image has an aspect ratio of 16:9 by default. [Other options](/docs/brand-design-tokens-aspect-ratio--docs) are available.
 
 ## Relevant WCAG requirements
 

From 2ee01ac88716615184778ec8410321f7be73c53f Mon Sep 17 00:00:00 2001
From: Ruben Sibon <r.sibon@amsterdam.nl>
Date: Wed, 30 Oct 2024 15:51:49 +0100
Subject: [PATCH 19/42] =?UTF-8?q?docs(ratio):=20=F0=9F=93=84=20CSS=20class?=
 =?UTF-8?q?=20util=20story?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../utils/AspectRatio/AspectRatio.docs.mdx    | 13 ++++++
 .../utils/AspectRatio/AspectRatio.stories.tsx | 43 +++++++++++++++++++
 .../src/utils/AspectRatio/AspectRatio.tsx     | 14 ++++++
 3 files changed, 70 insertions(+)
 create mode 100644 storybook/src/utils/AspectRatio/AspectRatio.docs.mdx
 create mode 100644 storybook/src/utils/AspectRatio/AspectRatio.stories.tsx
 create mode 100644 storybook/src/utils/AspectRatio/AspectRatio.tsx

diff --git a/storybook/src/utils/AspectRatio/AspectRatio.docs.mdx b/storybook/src/utils/AspectRatio/AspectRatio.docs.mdx
new file mode 100644
index 0000000000..e53bd653fe
--- /dev/null
+++ b/storybook/src/utils/AspectRatio/AspectRatio.docs.mdx
@@ -0,0 +1,13 @@
+{/* @license CC0-1.0 */}
+
+import { Controls, Markdown, Meta, Primary } from "@storybook/blocks";
+import * as AspectRatioStories from "./AspectRatio.stories.tsx";
+import README from "../../../../packages/css/src/components/aspect-ratio/README.md?raw";
+
+<Meta of={AspectRatioStories} />
+
+<Markdown>{README}</Markdown>
+
+<Primary />
+
+<Controls />
diff --git a/storybook/src/utils/AspectRatio/AspectRatio.stories.tsx b/storybook/src/utils/AspectRatio/AspectRatio.stories.tsx
new file mode 100644
index 0000000000..af3594bf56
--- /dev/null
+++ b/storybook/src/utils/AspectRatio/AspectRatio.stories.tsx
@@ -0,0 +1,43 @@
+/**
+ * @license EUPL-1.2+
+ * Copyright Gemeente Amsterdam
+ */
+
+import { Paragraph } from '@amsterdam/design-system-react'
+import { Meta, StoryObj } from '@storybook/react'
+import { AspectRatio } from './AspectRatio'
+import type { AspectRatioProps } from './AspectRatio'
+
+const render = ({ aspectRatio }: AspectRatioProps) => (
+  <div className={`ams-aspect-ratio--${aspectRatio}`}>
+    <Paragraph
+      style={{
+        alignItems: 'center',
+        backgroundColor: 'gray',
+        blockSize: '100%',
+        color: 'white',
+        display: 'inline-flex',
+        inlineSize: '100%',
+        justifyContent: 'center',
+      }}
+    >
+      This gray block has two dimensions with fixed proportions.
+    </Paragraph>
+  </div>
+)
+
+const meta = {
+  title: 'Utilities/CSS/Aspect Ratio',
+  component: AspectRatio,
+  args: {
+    aspectRatio: 'wide',
+  },
+} satisfies Meta<typeof AspectRatio>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  render,
+}
diff --git a/storybook/src/utils/AspectRatio/AspectRatio.tsx b/storybook/src/utils/AspectRatio/AspectRatio.tsx
new file mode 100644
index 0000000000..001244e630
--- /dev/null
+++ b/storybook/src/utils/AspectRatio/AspectRatio.tsx
@@ -0,0 +1,14 @@
+/**
+ * @license EUPL-1.2+
+ * Copyright Gemeente Amsterdam
+ */
+
+import { AspectRatioProps as IAspectRatioProps } from '@amsterdam/design-system-react/src/common/aspectRatio'
+import { HTMLAttributes, PropsWithChildren } from 'react'
+
+export type AspectRatioProps = IAspectRatioProps & PropsWithChildren<HTMLAttributes<HTMLSpanElement>>
+
+/** Renders examples in Storybook. Not for reuse. */
+export const AspectRatio = ({ children, aspectRatio }: AspectRatioProps) => (
+  <span className={`ams-aspect-ratio--${aspectRatio}`}>{children}</span>
+)

From 3f25d4b6d0e6b84669aad046b009e0d1ef909b21 Mon Sep 17 00:00:00 2001
From: Ruben Sibon <r.sibon@amsterdam.nl>
Date: Fri, 1 Nov 2024 11:33:13 +0100
Subject: [PATCH 20/42] =?UTF-8?q?feat(image)!:=20=F0=9F=97=91=EF=B8=8F=20r?=
 =?UTF-8?q?emove=20cover=20prop?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Image always has an aspect ratio and object-fit: cover is always set.
---
 packages/css/src/components/image/README.md  |  3 ++-
 packages/css/src/components/image/image.scss |  5 +----
 packages/react/src/Image/Image.test.tsx      | 12 ++++++------
 packages/react/src/Image/Image.tsx           | 15 +++------------
 4 files changed, 12 insertions(+), 23 deletions(-)

diff --git a/packages/css/src/components/image/README.md b/packages/css/src/components/image/README.md
index 640892ea77..bc440443de 100644
--- a/packages/css/src/components/image/README.md
+++ b/packages/css/src/components/image/README.md
@@ -15,7 +15,8 @@ Displays an image.
   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.
-- The image has an aspect ratio of 16:9 by default. [Other options](/docs/brand-design-tokens-aspect-ratio--docs) are available.
+- An Image should always have an aspect ratio. The default is 16:9. [Other options](/docs/brand-design-tokens-aspect-ratio--docs) are available.
+- If the source image is not an exact fit for the given dimensions it will cover the container with clipped sides.
 
 ## Relevant WCAG requirements
 
diff --git a/packages/css/src/components/image/image.scss b/packages/css/src/components/image/image.scss
index 390ae7b7c4..77d9731e4e 100644
--- a/packages/css/src/components/image/image.scss
+++ b/packages/css/src/components/image/image.scss
@@ -11,11 +11,8 @@
 
   &[class*="ams-aspect-ratio--"] {
     inline-size: fit-content;
-    position: relative;
-  }
-
-  &--cover {
     object-fit: cover;
+    position: relative;
   }
 }
 
diff --git a/packages/react/src/Image/Image.test.tsx b/packages/react/src/Image/Image.test.tsx
index aef22b892f..26fd20aaba 100644
--- a/packages/react/src/Image/Image.test.tsx
+++ b/packages/react/src/Image/Image.test.tsx
@@ -30,20 +30,20 @@ describe('Image', () => {
     expect(component).toHaveClass('ams-image')
   })
 
-  it('renders a class name to display the image as large as its container', () => {
-    const { container } = render(<Image cover />)
+  it('renders class names to display the image in a given aspect ratio', () => {
+    const { container } = render(<Image aspectRatio="x-tall" />)
 
     const component = container.querySelector(':only-child')
 
-    expect(component).toHaveClass('ams-image--cover')
+    expect(component).toHaveClass('ams-aspect-ratio--x-tall')
   })
 
-  it('renders class names to display the image in a given aspect ratio', () => {
-    const { container } = render(<Image aspectRatio="x-tall" />)
+  it('renders class names to display the image with the default aspect ratio', () => {
+    const { container } = render(<Image />)
 
     const component = container.querySelector(':only-child')
 
-    expect(component).toHaveClass('ams-aspect-ratio--x-tall')
+    expect(component).toHaveClass('ams-aspect-ratio--wide')
   })
 
   it('supports ForwardRef in React', () => {
diff --git a/packages/react/src/Image/Image.tsx b/packages/react/src/Image/Image.tsx
index cd5c64bffa..174f3454d9 100644
--- a/packages/react/src/Image/Image.tsx
+++ b/packages/react/src/Image/Image.tsx
@@ -8,23 +8,14 @@ import { forwardRef } from 'react'
 import type { ForwardedRef, ImgHTMLAttributes } from 'react'
 import { AspectRatioProps } from '../common/aspectRatio'
 
-export type ImageProps = {
-  /** Whether to display the image exactly as large as its container. This will clip the image if necessary. */
-  cover?: boolean
-} & AspectRatioProps &
-  ImgHTMLAttributes<HTMLImageElement>
+export type ImageProps = AspectRatioProps & ImgHTMLAttributes<HTMLImageElement>
 
 export const Image = forwardRef(
-  ({ aspectRatio = 'wide', className, cover, ...restProps }: ImageProps, ref: ForwardedRef<HTMLImageElement>) => (
+  ({ aspectRatio = 'wide', className, ...restProps }: ImageProps, ref: ForwardedRef<HTMLImageElement>) => (
     <img
       {...restProps}
       ref={ref}
-      className={clsx(
-        'ams-image',
-        (cover === true || (cover === undefined && aspectRatio)) && 'ams-image--cover',
-        aspectRatio && `ams-aspect-ratio--${aspectRatio}`,
-        className,
-      )}
+      className={clsx('ams-image', aspectRatio && `ams-aspect-ratio--${aspectRatio}`, className)}
     />
   ),
 )

From dd73879149d077eea8ef56f145a1c425a053d037 Mon Sep 17 00:00:00 2001
From: Ruben Sibon <r.sibon@amsterdam.nl>
Date: Fri, 1 Nov 2024 11:43:01 +0100
Subject: [PATCH 21/42] =?UTF-8?q?refactor(ratio):=20=E2=99=BB=EF=B8=8F=20?=
 =?UTF-8?q?=20use=20color=20tokens=20in=20story?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 storybook/src/utils/AspectRatio/AspectRatio.stories.tsx | 5 +++--
 storybook/tsconfig.json                                 | 3 ++-
 2 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/storybook/src/utils/AspectRatio/AspectRatio.stories.tsx b/storybook/src/utils/AspectRatio/AspectRatio.stories.tsx
index af3594bf56..86eddfee7d 100644
--- a/storybook/src/utils/AspectRatio/AspectRatio.stories.tsx
+++ b/storybook/src/utils/AspectRatio/AspectRatio.stories.tsx
@@ -4,6 +4,7 @@
  */
 
 import { Paragraph } from '@amsterdam/design-system-react'
+import tokens from '@amsterdam/design-system-tokens/dist/index.json'
 import { Meta, StoryObj } from '@storybook/react'
 import { AspectRatio } from './AspectRatio'
 import type { AspectRatioProps } from './AspectRatio'
@@ -13,9 +14,9 @@ const render = ({ aspectRatio }: AspectRatioProps) => (
     <Paragraph
       style={{
         alignItems: 'center',
-        backgroundColor: 'gray',
+        backgroundColor: tokens.ams.color['neutral-grey2'],
         blockSize: '100%',
-        color: 'white',
+        color: tokens.ams.color['primary-white'],
         display: 'inline-flex',
         inlineSize: '100%',
         justifyContent: 'center',
diff --git a/storybook/tsconfig.json b/storybook/tsconfig.json
index 00d767d80f..c59bdbd36a 100644
--- a/storybook/tsconfig.json
+++ b/storybook/tsconfig.json
@@ -1,7 +1,8 @@
 {
   "compilerOptions": {
     "jsx": "react-jsx",
-    "allowSyntheticDefaultImports": true
+    "allowSyntheticDefaultImports": true,
+    "resolveJsonModule": true
   },
   "extends": "../tsconfig.json",
   "include": ["src/**/*.ts", "src/**/*.tsx", "config/**/*.ts", "config/**/*.tsx"],

From e812d3e45918b23d57f7f3e26f63e2b96862b536 Mon Sep 17 00:00:00 2001
From: Vincent Smedinga <v.smedinga@amsterdam.nl>
Date: Thu, 7 Nov 2024 13:58:17 +0100
Subject: [PATCH 22/42] Make token ans class documentation consistent

---
 .../css/src/components/aspect-ratio/README.md | 24 ++++++++------
 packages/css/src/components/image/README.md   |  8 +++--
 .../design-tokens/aspect-ratio.docs.mdx       | 32 ++++++++++++-------
 storybook/src/styles/docs.css                 |  6 ++++
 4 files changed, 47 insertions(+), 23 deletions(-)

diff --git a/packages/css/src/components/aspect-ratio/README.md b/packages/css/src/components/aspect-ratio/README.md
index ecbf9a672c..2da5a426bf 100644
--- a/packages/css/src/components/aspect-ratio/README.md
+++ b/packages/css/src/components/aspect-ratio/README.md
@@ -4,17 +4,21 @@
 
 Aspect Ratio updates the height of an element with its width.
 
-These are the proportions we use:
+## Class names
 
-| keyword   | ratio |
-| :-------- | ----: |
-| `2x-wide` |  16:5 |
-| `x-wide`  |  16:9 |
-| `wide`    |   4:3 |
-| `square`  |   1:1 |
-| `tall`    |   3:4 |
-| `x-tall`  |  9:16 |
+Each available aspect ratio has an associated class name.
+The class can be applied to any component or element.
+
+| Class name                  | Example                                                                     |
+| :-------------------------- | :-------------------------------------------------------------------------- |
+| `ams-aspect-ratio--x-tall`  | <div className="ams-docs-token-example--space ams-aspect-ratio--x-tall" />  |
+| `ams-aspect-ratio--tall`    | <div className="ams-docs-token-example--space ams-aspect-ratio--tall" />    |
+| `ams-aspect-ratio--square`  | <div className="ams-docs-token-example--space ams-aspect-ratio--square" />  |
+| `ams-aspect-ratio--wide`    | <div className="ams-docs-token-example--space ams-aspect-ratio--wide" />    |
+| `ams-aspect-ratio--x-wide`  | <div className="ams-docs-token-example--space ams-aspect-ratio--x-wide" />  |
+| `ams-aspect-ratio--2x-wide` | <div className="ams-docs-token-example--space ams-aspect-ratio--2x-wide" /> |
 
 ## Guidelines
 
-- Use this CSS class to constrain images, videos and other elements to one of the available aspect ratios.
+- Apply one of these classes to an image, video or other media content to constrain its dimensions to one of the available aspect ratios.
+- The default aspect ratio is 16 / 9.
diff --git a/packages/css/src/components/image/README.md b/packages/css/src/components/image/README.md
index bc440443de..4724961ca8 100644
--- a/packages/css/src/components/image/README.md
+++ b/packages/css/src/components/image/README.md
@@ -4,6 +4,12 @@
 
 Displays an image.
 
+## Design
+
+Every Image must display in one of the [available aspect ratios](https://designsystem.amsterdam/?path=/docs/brand-design-tokens-aspect-ratio--docs).
+The default is 16:9.
+If the intrinsic dimensions of the source do not match an aspect ratio, the image will get cropped to cover the intended area without distorting its appearance.
+
 ## Guidelines
 
 - Do not forget to include a description of the image in the `alt` attribute.
@@ -15,8 +21,6 @@ Displays an image.
   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.
-- An Image should always have an aspect ratio. The default is 16:9. [Other options](/docs/brand-design-tokens-aspect-ratio--docs) are available.
-- If the source image is not an exact fit for the given dimensions it will cover the container with clipped sides.
 
 ## Relevant WCAG requirements
 
diff --git a/storybook/src/foundation/design-tokens/aspect-ratio.docs.mdx b/storybook/src/foundation/design-tokens/aspect-ratio.docs.mdx
index a315184832..194569bc82 100644
--- a/storybook/src/foundation/design-tokens/aspect-ratio.docs.mdx
+++ b/storybook/src/foundation/design-tokens/aspect-ratio.docs.mdx
@@ -6,17 +6,27 @@ import { Meta } from "@storybook/blocks";
 
 # Aspect Ratio
 
-Constrain elements like images and videos to one of the available aspect ratios.
+Constrains media content to a supported aspect ratio.
 
-## Ratios
+## Design
 
-We have 6 named aspect ratios:
+Media content like images, videos, and maps take up sizable portions of a screen.
+Using just a limited set of aspect ratios to display them keeps the visual impression of a page composed.
 
-| Token name                 | ratio  | Example                                                                                                                         |
-| :------------------------- | :----: | ------------------------------------------------------------------------------------------------------------------------------- |
-| `ams.aspect-ratio.x-tall`  | 9 / 16 | <div className="ams-docs-token-example--space" style={{ blockSize: '3rem', aspectRatio: 'var(--ams-aspect-ratio-x-tall)' }} />  |
-| `ams.aspect-ratio.tall`    | 3 / 4  | <div className="ams-docs-token-example--space" style={{ blockSize: '3rem', aspectRatio: 'var(--ams-aspect-ratio-tall)' }} />    |
-| `ams.aspect-ratio.square`  | 1 / 1  | <div className="ams-docs-token-example--space" style={{ blockSize: '3rem', aspectRatio: 'var(--ams-aspect-ratio-square)' }} />  |
-| `ams.aspect-ratio.wide`    | 4 / 3  | <div className="ams-docs-token-example--space" style={{ blockSize: '3rem', aspectRatio: 'var(--ams-aspect-ratio-wide)' }} />    |
-| `ams.aspect-ratio.x-wide`  | 16 / 9 | <div className="ams-docs-token-example--space" style={{ blockSize: '3rem', aspectRatio: 'var(--ams-aspect-ratio-x-wide)' }} />  |
-| `ams.aspect-ratio.2x-wide` | 16 / 5 | <div className="ams-docs-token-example--space" style={{ blockSize: '3rem', aspectRatio: 'var(--ams-aspect-ratio-2x-wide)' }} /> |
+The default aspect ratio for media is 16 / 9.
+
+Content with intrinsic dimensions that do not match an aspect ratio will be cropped without distorting its appearance.
+
+| Token name                 |  Value | Example                                                                                                      |
+| :------------------------- | -----: | ------------------------------------------------------------------------------------------------------------ |
+| `ams.aspect-ratio.x-tall`  | 9 / 16 | <div className="ams-docs-token-example--space" style={{ aspectRatio: 'var(--ams-aspect-ratio-x-tall)' }} />  |
+| `ams.aspect-ratio.tall`    |  3 / 4 | <div className="ams-docs-token-example--space" style={{ aspectRatio: 'var(--ams-aspect-ratio-tall)' }} />    |
+| `ams.aspect-ratio.square`  |  1 / 1 | <div className="ams-docs-token-example--space" style={{ aspectRatio: 'var(--ams-aspect-ratio-square)' }} />  |
+| `ams.aspect-ratio.wide`    |  4 / 3 | <div className="ams-docs-token-example--space" style={{ aspectRatio: 'var(--ams-aspect-ratio-wide)' }} />    |
+| `ams.aspect-ratio.x-wide`  | 16 / 9 | <div className="ams-docs-token-example--space" style={{ aspectRatio: 'var(--ams-aspect-ratio-x-wide)' }} />  |
+| `ams.aspect-ratio.2x-wide` | 16 / 5 | <div className="ams-docs-token-example--space" style={{ aspectRatio: 'var(--ams-aspect-ratio-2x-wide)' }} /> |
+
+## Related components
+
+- The [Image](https://designsystem.amsterdam/?path=/docs/components-media-image--docs) component has an `aspectRatio` prop that sets one of these classes.
+- The [Breakout](https://designsystem.amsterdam/?path=/docs/components-layout-breakout--docs) layout positions an image with a certain aspect ratio in a Spotlight.
diff --git a/storybook/src/styles/docs.css b/storybook/src/styles/docs.css
index 6a346536d2..e60f4f3616 100644
--- a/storybook/src/styles/docs.css
+++ b/storybook/src/styles/docs.css
@@ -127,6 +127,12 @@
   }
 }
 
+.ams-docs-aspect-ratio {
+  min-block-size: initial;
+  padding-block: var(--ams-space-md);
+  padding-inline: var(--ams-space-md);
+}
+
 .ams-docs-item {
   background-color: var(--ams-docs-pink);
   border: thin dashed var(--ams-docs-grey);

From 07cf8086619d7c5760e12e10bb4b7a7338ad2803 Mon Sep 17 00:00:00 2001
From: Vincent Smedinga <v.smedinga@amsterdam.nl>
Date: Thu, 7 Nov 2024 13:59:00 +0100
Subject: [PATCH 23/42] Use a pink box for the generic example

---
 .../utils/AspectRatio/AspectRatio.stories.tsx | 37 +++++++------------
 1 file changed, 13 insertions(+), 24 deletions(-)

diff --git a/storybook/src/utils/AspectRatio/AspectRatio.stories.tsx b/storybook/src/utils/AspectRatio/AspectRatio.stories.tsx
index 86eddfee7d..a5bd7d6f79 100644
--- a/storybook/src/utils/AspectRatio/AspectRatio.stories.tsx
+++ b/storybook/src/utils/AspectRatio/AspectRatio.stories.tsx
@@ -3,42 +3,31 @@
  * Copyright Gemeente Amsterdam
  */
 
-import { Paragraph } from '@amsterdam/design-system-react'
-import tokens from '@amsterdam/design-system-tokens/dist/index.json'
 import { Meta, StoryObj } from '@storybook/react'
 import { AspectRatio } from './AspectRatio'
 import type { AspectRatioProps } from './AspectRatio'
 
-const render = ({ aspectRatio }: AspectRatioProps) => (
-  <div className={`ams-aspect-ratio--${aspectRatio}`}>
-    <Paragraph
-      style={{
-        alignItems: 'center',
-        backgroundColor: tokens.ams.color['neutral-grey2'],
-        blockSize: '100%',
-        color: tokens.ams.color['primary-white'],
-        display: 'inline-flex',
-        inlineSize: '100%',
-        justifyContent: 'center',
-      }}
-    >
-      This gray block has two dimensions with fixed proportions.
-    </Paragraph>
-  </div>
-)
-
 const meta = {
   title: 'Utilities/CSS/Aspect Ratio',
   component: AspectRatio,
   args: {
-    aspectRatio: 'wide',
+    aspectRatio: 'x-wide',
+  },
+  argTypes: {
+    aspectRatio: {
+      control: 'radio',
+      options: ['2x-wide', 'x-wide', 'wide', 'square', 'tall', 'x-tall'],
+    },
   },
+  render: ({ aspectRatio }: AspectRatioProps) => (
+    <div className="ams-docs-column ams-docs-aspect-ratio">
+      <div className={`ams-docs-item ams-aspect-ratio--${aspectRatio}`}></div>
+    </div>
+  ),
 } satisfies Meta<typeof AspectRatio>
 
 export default meta
 
 type Story = StoryObj<typeof meta>
 
-export const Default: Story = {
-  render,
-}
+export const Default: Story = {}

From 5aa442347684b44cb43beafefe85819ba61f4b48 Mon Sep 17 00:00:00 2001
From: Vincent Smedinga <v.smedinga@amsterdam.nl>
Date: Thu, 7 Nov 2024 13:59:49 +0100
Subject: [PATCH 24/42] Update border heading and table layout for consistency

---
 .../src/foundation/design-tokens/border.docs.mdx   | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/storybook/src/foundation/design-tokens/border.docs.mdx b/storybook/src/foundation/design-tokens/border.docs.mdx
index 548e8e3831..33dae7c12e 100644
--- a/storybook/src/foundation/design-tokens/border.docs.mdx
+++ b/storybook/src/foundation/design-tokens/border.docs.mdx
@@ -8,13 +8,13 @@ import { Meta } from "@storybook/blocks";
 
 Elements that have a border, outline or underline use one of these widths.
 
-## Widths
+## Design
 
 We have 4 border widths:
 
-| Token name            | px  |  rem   | Example                                                                                                             |
-| :-------------------- | :-: | :----: | ------------------------------------------------------------------------------------------------------------------- |
-| `ams.border.width.sm` |  1  | 0.0625 | <div className="ams-docs-token-example--border" style={{ borderInlineStartWidth: 'var(--ams-border-width-sm)' }} /> |
-| `ams.border.width.md` |  2  | 0.125  | <div className="ams-docs-token-example--border" style={{ borderInlineStartWidth: 'var(--ams-border-width-md)' }} /> |
-| `ams.border.width.lg` |  3  | 0.1875 | <div className="ams-docs-token-example--border" style={{ borderInlineStartWidth: 'var(--ams-border-width-lg)' }} /> |
-| `ams.border.width.xl` |  4  |  0.25  | <div className="ams-docs-token-example--border" style={{ borderInlineStartWidth: 'var(--ams-border-width-xl)' }} /> |
+| Token name            |     Value | Value (px) | Example                                                                                                             |
+| :-------------------- | --------: | :--------: | ------------------------------------------------------------------------------------------------------------------- |
+| `ams.border.width.sm` | 0.0625rem |     1      | <div className="ams-docs-token-example--border" style={{ borderInlineStartWidth: 'var(--ams-border-width-sm)' }} /> |
+| `ams.border.width.md` |  0.125rem |     2      | <div className="ams-docs-token-example--border" style={{ borderInlineStartWidth: 'var(--ams-border-width-md)' }} /> |
+| `ams.border.width.lg` | 0.1875rem |     3      | <div className="ams-docs-token-example--border" style={{ borderInlineStartWidth: 'var(--ams-border-width-lg)' }} /> |
+| `ams.border.width.xl` |   0.25rem |     4      | <div className="ams-docs-token-example--border" style={{ borderInlineStartWidth: 'var(--ams-border-width-xl)' }} /> |

From 59d79cc567f9c4b215a62bca0fc32ee66c0ff63b Mon Sep 17 00:00:00 2001
From: Vincent Smedinga <v.smedinga@amsterdam.nl>
Date: Thu, 7 Nov 2024 14:11:21 +0100
Subject: [PATCH 25/42] Set the default aspect ratio for images

---
 packages/css/src/components/image/image.scss           | 10 ++++------
 .../tokens/src/components/ams/image.tokens.json        |  7 +++++++
 2 files changed, 11 insertions(+), 6 deletions(-)
 create mode 100644 proprietary/tokens/src/components/ams/image.tokens.json

diff --git a/packages/css/src/components/image/image.scss b/packages/css/src/components/image/image.scss
index 77d9731e4e..3416e50223 100644
--- a/packages/css/src/components/image/image.scss
+++ b/packages/css/src/components/image/image.scss
@@ -4,19 +4,17 @@
  */
 
 .ams-image {
+  aspect-ratio: var(--ams-image-aspect-ratio);
   block-size: auto; /* [1] */
   font-style: italic; /* [3] */
+  inline-size: fit-content;
   max-inline-size: 100%; /* [1] */
+  object-fit: cover; /* [4] */
   vertical-align: middle; /* [2] */
-
-  &[class*="ams-aspect-ratio--"] {
-    inline-size: fit-content;
-    object-fit: cover;
-    position: relative;
-  }
 }
 
 // [1] Allow for fluid image sizing while maintaining aspect ratio governed by inline/block size attributes
 // [2] Remove ‘phantom’ white space
 // [3] Italicise alt text to visually offset it from surrounding copy
 // Source: https://x.com/csswizardry/status/1717841334462005661
+// [4] Crop the image to maintain a supported aspect ratio
diff --git a/proprietary/tokens/src/components/ams/image.tokens.json b/proprietary/tokens/src/components/ams/image.tokens.json
new file mode 100644
index 0000000000..cd7460011a
--- /dev/null
+++ b/proprietary/tokens/src/components/ams/image.tokens.json
@@ -0,0 +1,7 @@
+{
+  "ams": {
+    "image": {
+      "aspect-ratio": { "value": "{ams.aspect-ratio.x-wide}" }
+    }
+  }
+}

From f349157715d575f8234246c0651b6aab1df65442 Mon Sep 17 00:00:00 2001
From: Vincent Smedinga <v.smedinga@amsterdam.nl>
Date: Thu, 7 Nov 2024 14:11:33 +0100
Subject: [PATCH 26/42] Remove intermediate type

---
 packages/react/src/common/aspectRatio.ts | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/packages/react/src/common/aspectRatio.ts b/packages/react/src/common/aspectRatio.ts
index e8d3cdb5e4..ed16b5a14e 100644
--- a/packages/react/src/common/aspectRatio.ts
+++ b/packages/react/src/common/aspectRatio.ts
@@ -1,6 +1,4 @@
-type Ratio = 'x-tall' | 'tall' | 'square' | 'wide' | 'x-wide' | '2x-wide'
-
 export type AspectRatioProps = {
-  /** The ratio of the horizontal and vertical dimensions. */
-  aspectRatio?: Ratio
+  /** The aspect ratio to display media content in. */
+  aspectRatio?: 'x-tall' | 'tall' | 'square' | 'wide' | 'x-wide' | '2x-wide'
 }

From 138bf3bc6356c7c43156a77127e8bef1539395b0 Mon Sep 17 00:00:00 2001
From: Vincent Smedinga <v.smedinga@amsterdam.nl>
Date: Thu, 7 Nov 2024 14:14:54 +0100
Subject: [PATCH 27/42] Consolidate reused types

---
 packages/react/src/Column/Column.test.tsx          | 2 +-
 packages/react/src/Column/Column.tsx               | 2 +-
 packages/react/src/Row/Row.test.tsx                | 2 +-
 packages/react/src/Row/Row.tsx                     | 2 +-
 packages/react/src/common/aspectRatio.ts           | 4 ----
 packages/react/src/common/{layout.ts => types.ts}  | 5 +++++
 storybook/src/components/Column/Column.stories.tsx | 2 +-
 storybook/src/components/Row/Row.stories.tsx       | 2 +-
 8 files changed, 11 insertions(+), 10 deletions(-)
 delete mode 100644 packages/react/src/common/aspectRatio.ts
 rename packages/react/src/common/{layout.ts => types.ts} (78%)

diff --git a/packages/react/src/Column/Column.test.tsx b/packages/react/src/Column/Column.test.tsx
index f81fb12027..76a3f98c52 100644
--- a/packages/react/src/Column/Column.test.tsx
+++ b/packages/react/src/Column/Column.test.tsx
@@ -1,7 +1,7 @@
 import { render, screen } from '@testing-library/react'
 import { createRef } from 'react'
 import { Column, columnGapSizes } from './Column'
-import { crossAlignOptionsForColumn, mainAlignOptions } from '../common/layout'
+import { crossAlignOptionsForColumn, mainAlignOptions } from '../common/types'
 import '@testing-library/jest-dom'
 
 describe('Column', () => {
diff --git a/packages/react/src/Column/Column.tsx b/packages/react/src/Column/Column.tsx
index fd0e7c584b..1bceefda2e 100644
--- a/packages/react/src/Column/Column.tsx
+++ b/packages/react/src/Column/Column.tsx
@@ -6,7 +6,7 @@
 import clsx from 'clsx'
 import { forwardRef } from 'react'
 import type { HTMLAttributes, PropsWithChildren } from 'react'
-import type { CrossAlignForColumn, MainAlign } from '../common/layout'
+import type { CrossAlignForColumn, MainAlign } from '../common/types'
 
 export const columnGapSizes = ['none', 'extra-small', 'small', 'large', 'extra-large'] as const
 
diff --git a/packages/react/src/Row/Row.test.tsx b/packages/react/src/Row/Row.test.tsx
index 4aae85a7fe..3a9082708e 100644
--- a/packages/react/src/Row/Row.test.tsx
+++ b/packages/react/src/Row/Row.test.tsx
@@ -1,7 +1,7 @@
 import { render, screen } from '@testing-library/react'
 import { createRef } from 'react'
 import { Row, rowGapSizes } from './Row'
-import { crossAlignOptions, mainAlignOptions } from '../common/layout'
+import { crossAlignOptions, mainAlignOptions } from '../common/types'
 import '@testing-library/jest-dom'
 
 describe('Row', () => {
diff --git a/packages/react/src/Row/Row.tsx b/packages/react/src/Row/Row.tsx
index 446829799a..b1f6be9e07 100644
--- a/packages/react/src/Row/Row.tsx
+++ b/packages/react/src/Row/Row.tsx
@@ -6,7 +6,7 @@
 import clsx from 'clsx'
 import { forwardRef } from 'react'
 import type { HTMLAttributes, PropsWithChildren } from 'react'
-import type { CrossAlign, MainAlign } from '../common/layout'
+import type { CrossAlign, MainAlign } from '../common/types'
 
 export const rowGapSizes = ['none', 'extra-small', 'small', 'large', 'extra-large'] as const
 
diff --git a/packages/react/src/common/aspectRatio.ts b/packages/react/src/common/aspectRatio.ts
deleted file mode 100644
index ed16b5a14e..0000000000
--- a/packages/react/src/common/aspectRatio.ts
+++ /dev/null
@@ -1,4 +0,0 @@
-export type AspectRatioProps = {
-  /** The aspect ratio to display media content in. */
-  aspectRatio?: 'x-tall' | 'tall' | 'square' | 'wide' | 'x-wide' | '2x-wide'
-}
diff --git a/packages/react/src/common/layout.ts b/packages/react/src/common/types.ts
similarity index 78%
rename from packages/react/src/common/layout.ts
rename to packages/react/src/common/types.ts
index 9b7a20f4f0..3a294b70a9 100644
--- a/packages/react/src/common/layout.ts
+++ b/packages/react/src/common/types.ts
@@ -1,3 +1,8 @@
+export type AspectRatioProps = {
+  /** The aspect ratio to display media content in. */
+  aspectRatio?: 'x-tall' | 'tall' | 'square' | 'wide' | 'x-wide' | '2x-wide'
+}
+
 export const crossAlignOptions = ['start', 'center', 'baseline', 'end'] as const
 export type CrossAlign = (typeof crossAlignOptions)[number]
 
diff --git a/storybook/src/components/Column/Column.stories.tsx b/storybook/src/components/Column/Column.stories.tsx
index 65d8c40323..d9b595291f 100644
--- a/storybook/src/components/Column/Column.stories.tsx
+++ b/storybook/src/components/Column/Column.stories.tsx
@@ -5,7 +5,7 @@
 
 import { Card, Heading, Paragraph } from '@amsterdam/design-system-react'
 import { Column } from '@amsterdam/design-system-react/src'
-import { crossAlignOptionsForColumn, mainAlignOptions } from '@amsterdam/design-system-react/src/common/layout'
+import { crossAlignOptionsForColumn, mainAlignOptions } from '@amsterdam/design-system-react/src/common/types'
 import { Meta, StoryObj } from '@storybook/react'
 
 const ThreeItems = [
diff --git a/storybook/src/components/Row/Row.stories.tsx b/storybook/src/components/Row/Row.stories.tsx
index 9296559050..2b962f4a5a 100644
--- a/storybook/src/components/Row/Row.stories.tsx
+++ b/storybook/src/components/Row/Row.stories.tsx
@@ -5,7 +5,7 @@
 
 import { Avatar, Heading, Link } from '@amsterdam/design-system-react'
 import { Row } from '@amsterdam/design-system-react/src'
-import { crossAlignOptions, mainAlignOptions } from '@amsterdam/design-system-react/src/common/layout'
+import { crossAlignOptions, mainAlignOptions } from '@amsterdam/design-system-react/src/common/types'
 import { Meta, StoryObj } from '@storybook/react'
 
 const ThreeItems = [

From 01b0f35e62c239c042c303139997b879d7056864 Mon Sep 17 00:00:00 2001
From: Vincent Smedinga <v.smedinga@amsterdam.nl>
Date: Thu, 7 Nov 2024 14:15:12 +0100
Subject: [PATCH 28/42] Test for extra class consistently

---
 packages/react/src/Image/Image.test.tsx   | 3 +--
 packages/react/src/Switch/Switch.test.tsx | 2 +-
 2 files changed, 2 insertions(+), 3 deletions(-)

diff --git a/packages/react/src/Image/Image.test.tsx b/packages/react/src/Image/Image.test.tsx
index 26fd20aaba..6224efb8ed 100644
--- a/packages/react/src/Image/Image.test.tsx
+++ b/packages/react/src/Image/Image.test.tsx
@@ -26,8 +26,7 @@ describe('Image', () => {
 
     const component = container.querySelector(':only-child')
 
-    expect(component).toHaveClass('extra')
-    expect(component).toHaveClass('ams-image')
+    expect(component).toHaveClass('ams-image extra')
   })
 
   it('renders class names to display the image in a given aspect ratio', () => {
diff --git a/packages/react/src/Switch/Switch.test.tsx b/packages/react/src/Switch/Switch.test.tsx
index a21b62e6df..7cef895e7f 100644
--- a/packages/react/src/Switch/Switch.test.tsx
+++ b/packages/react/src/Switch/Switch.test.tsx
@@ -92,7 +92,7 @@ describe('Switch', () => {
 
     const component = container.querySelector(':only-child')
 
-    expect(component).toHaveClass('ams-switch', 'extra')
+    expect(component).toHaveClass('ams-switch extra')
   })
 
   it('is able to pass a React ref', () => {

From a194a11a723ec757359c293dd20035301bd5ebbf Mon Sep 17 00:00:00 2001
From: Vincent Smedinga <v.smedinga@amsterdam.nl>
Date: Thu, 7 Nov 2024 14:19:58 +0100
Subject: [PATCH 29/42] Write aspect ratios consistently and use token

---
 packages/css/src/components/aspect-ratio/README.md           | 2 +-
 storybook/src/docs/components/color-palette.css              | 2 +-
 storybook/src/foundation/design-tokens/aspect-ratio.docs.mdx | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/packages/css/src/components/aspect-ratio/README.md b/packages/css/src/components/aspect-ratio/README.md
index 2da5a426bf..e86b5b320a 100644
--- a/packages/css/src/components/aspect-ratio/README.md
+++ b/packages/css/src/components/aspect-ratio/README.md
@@ -21,4 +21,4 @@ The class can be applied to any component or element.
 ## Guidelines
 
 - Apply one of these classes to an image, video or other media content to constrain its dimensions to one of the available aspect ratios.
-- The default aspect ratio is 16 / 9.
+- The default aspect ratio is 16:9.
diff --git a/storybook/src/docs/components/color-palette.css b/storybook/src/docs/components/color-palette.css
index 6b8354b970..f35df283c8 100644
--- a/storybook/src/docs/components/color-palette.css
+++ b/storybook/src/docs/components/color-palette.css
@@ -18,7 +18,7 @@
 }
 
 .ams-storybook-color-palette__example {
-  aspect-ratio: 16 / 9;
+  aspect-ratio: var(--ams-aspect-ratio-x-wide);
   border: 0.0625rem solid rgb(0 0 0 / 12.5%);
   grid-area: example;
 }
diff --git a/storybook/src/foundation/design-tokens/aspect-ratio.docs.mdx b/storybook/src/foundation/design-tokens/aspect-ratio.docs.mdx
index 194569bc82..d266d6f7e1 100644
--- a/storybook/src/foundation/design-tokens/aspect-ratio.docs.mdx
+++ b/storybook/src/foundation/design-tokens/aspect-ratio.docs.mdx
@@ -13,7 +13,7 @@ Constrains media content to a supported aspect ratio.
 Media content like images, videos, and maps take up sizable portions of a screen.
 Using just a limited set of aspect ratios to display them keeps the visual impression of a page composed.
 
-The default aspect ratio for media is 16 / 9.
+The default aspect ratio for media is 16:9.
 
 Content with intrinsic dimensions that do not match an aspect ratio will be cropped without distorting its appearance.
 

From 114d82817e703d3648ce6688c28ac3c2f07d04e5 Mon Sep 17 00:00:00 2001
From: Vincent Smedinga <v.smedinga@amsterdam.nl>
Date: Thu, 7 Nov 2024 14:23:04 +0100
Subject: [PATCH 30/42] =?UTF-8?q?Add=20=E2=80=98Tokens=E2=80=99=20heading?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../src/foundation/design-tokens/aspect-ratio.docs.mdx    | 8 ++++----
 storybook/src/foundation/design-tokens/border.docs.mdx    | 4 +++-
 2 files changed, 7 insertions(+), 5 deletions(-)

diff --git a/storybook/src/foundation/design-tokens/aspect-ratio.docs.mdx b/storybook/src/foundation/design-tokens/aspect-ratio.docs.mdx
index d266d6f7e1..1a277f14dc 100644
--- a/storybook/src/foundation/design-tokens/aspect-ratio.docs.mdx
+++ b/storybook/src/foundation/design-tokens/aspect-ratio.docs.mdx
@@ -11,12 +11,12 @@ Constrains media content to a supported aspect ratio.
 ## Design
 
 Media content like images, videos, and maps take up sizable portions of a screen.
-Using just a limited set of aspect ratios to display them keeps the visual impression of a page composed.
-
-The default aspect ratio for media is 16:9.
-
+Displaying them in a limited set of aspect ratios keeps the visual impression of a page composed.
+The default aspect ratio is 16:9.
 Content with intrinsic dimensions that do not match an aspect ratio will be cropped without distorting its appearance.
 
+## Tokens
+
 | Token name                 |  Value | Example                                                                                                      |
 | :------------------------- | -----: | ------------------------------------------------------------------------------------------------------------ |
 | `ams.aspect-ratio.x-tall`  | 9 / 16 | <div className="ams-docs-token-example--space" style={{ aspectRatio: 'var(--ams-aspect-ratio-x-tall)' }} />  |
diff --git a/storybook/src/foundation/design-tokens/border.docs.mdx b/storybook/src/foundation/design-tokens/border.docs.mdx
index 33dae7c12e..7d048a7def 100644
--- a/storybook/src/foundation/design-tokens/border.docs.mdx
+++ b/storybook/src/foundation/design-tokens/border.docs.mdx
@@ -10,7 +10,9 @@ Elements that have a border, outline or underline use one of these widths.
 
 ## Design
 
-We have 4 border widths:
+We use a limited set of border widths for consistency.
+
+## Tokens
 
 | Token name            |     Value | Value (px) | Example                                                                                                             |
 | :-------------------- | --------: | :--------: | ------------------------------------------------------------------------------------------------------------------- |

From 393b789e4c8d72567efe35ae05dfa3f35b356b07 Mon Sep 17 00:00:00 2001
From: Vincent Smedinga <v.smedinga@amsterdam.nl>
Date: Thu, 7 Nov 2024 14:32:56 +0100
Subject: [PATCH 31/42] Fix type import paths

---
 packages/react/src/Image/Image.tsx              | 2 +-
 packages/react/src/ImageSlider/ImageSlider.tsx  | 2 +-
 storybook/src/utils/AspectRatio/AspectRatio.tsx | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/packages/react/src/Image/Image.tsx b/packages/react/src/Image/Image.tsx
index 174f3454d9..a5ec5cf71b 100644
--- a/packages/react/src/Image/Image.tsx
+++ b/packages/react/src/Image/Image.tsx
@@ -6,7 +6,7 @@
 import clsx from 'clsx'
 import { forwardRef } from 'react'
 import type { ForwardedRef, ImgHTMLAttributes } from 'react'
-import { AspectRatioProps } from '../common/aspectRatio'
+import { AspectRatioProps } from '../common/types'
 
 export type ImageProps = AspectRatioProps & ImgHTMLAttributes<HTMLImageElement>
 
diff --git a/packages/react/src/ImageSlider/ImageSlider.tsx b/packages/react/src/ImageSlider/ImageSlider.tsx
index 98a3e91d62..e62071e68c 100644
--- a/packages/react/src/ImageSlider/ImageSlider.tsx
+++ b/packages/react/src/ImageSlider/ImageSlider.tsx
@@ -12,7 +12,7 @@ import { ImageSliderItem } from './ImageSliderItem'
 import { ImageSliderScroller } from './ImageSliderScroller'
 import { ImageSliderThumbnails } from './ImageSliderThumbnails'
 import { Image, ImageProps } from '../Image/Image'
-import { AspectRatioProps } from '../common/aspectRatio'
+import { AspectRatioProps } from '../common/types'
 
 export type ImageSliderImageProps = ImageProps & AspectRatioProps
 
diff --git a/storybook/src/utils/AspectRatio/AspectRatio.tsx b/storybook/src/utils/AspectRatio/AspectRatio.tsx
index 001244e630..fe7cc5ea72 100644
--- a/storybook/src/utils/AspectRatio/AspectRatio.tsx
+++ b/storybook/src/utils/AspectRatio/AspectRatio.tsx
@@ -3,7 +3,7 @@
  * Copyright Gemeente Amsterdam
  */
 
-import { AspectRatioProps as IAspectRatioProps } from '@amsterdam/design-system-react/src/common/aspectRatio'
+import { AspectRatioProps as IAspectRatioProps } from '@amsterdam/design-system-react/src/common/types'
 import { HTMLAttributes, PropsWithChildren } from 'react'
 
 export type AspectRatioProps = IAspectRatioProps & PropsWithChildren<HTMLAttributes<HTMLSpanElement>>

From fa3006aacff707a3f6c298abb072853b5652028d Mon Sep 17 00:00:00 2001
From: Vincent Smedinga <v.smedinga@amsterdam.nl>
Date: Thu, 7 Nov 2024 14:33:24 +0100
Subject: [PATCH 32/42] Remove explicit default aspect ratio from Image

---
 packages/react/src/Image/Image.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/react/src/Image/Image.tsx b/packages/react/src/Image/Image.tsx
index a5ec5cf71b..2ccee61fb3 100644
--- a/packages/react/src/Image/Image.tsx
+++ b/packages/react/src/Image/Image.tsx
@@ -11,7 +11,7 @@ import { AspectRatioProps } from '../common/types'
 export type ImageProps = AspectRatioProps & ImgHTMLAttributes<HTMLImageElement>
 
 export const Image = forwardRef(
-  ({ aspectRatio = 'wide', className, ...restProps }: ImageProps, ref: ForwardedRef<HTMLImageElement>) => (
+  ({ aspectRatio, className, ...restProps }: ImageProps, ref: ForwardedRef<HTMLImageElement>) => (
     <img
       {...restProps}
       ref={ref}

From dea05356f13648bdbef4b96ccf7c372914b8fbf4 Mon Sep 17 00:00:00 2001
From: Vincent Smedinga <v.smedinga@amsterdam.nl>
Date: Thu, 7 Nov 2024 14:33:47 +0100
Subject: [PATCH 33/42] Test all aspect ratio classes on Image

---
 packages/react/src/Image/Image.test.tsx | 19 +++++++------------
 packages/react/src/common/types.ts      |  3 ++-
 2 files changed, 9 insertions(+), 13 deletions(-)

diff --git a/packages/react/src/Image/Image.test.tsx b/packages/react/src/Image/Image.test.tsx
index 6224efb8ed..5f830066be 100644
--- a/packages/react/src/Image/Image.test.tsx
+++ b/packages/react/src/Image/Image.test.tsx
@@ -1,6 +1,7 @@
 import { render } from '@testing-library/react'
 import { createRef } from 'react'
 import { Image } from './Image'
+import { aspectRatioOptions } from '../common/types'
 import '@testing-library/jest-dom'
 
 describe('Image', () => {
@@ -29,20 +30,14 @@ describe('Image', () => {
     expect(component).toHaveClass('ams-image extra')
   })
 
-  it('renders class names to display the image in a given aspect ratio', () => {
-    const { container } = render(<Image aspectRatio="x-tall" />)
+  aspectRatioOptions.forEach((aspectRatio) => {
+    it(`renders class names to display the image in the ${aspectRatio} aspect ratio`, () => {
+      const { container } = render(<Image aspectRatio={aspectRatio} />)
 
-    const component = container.querySelector(':only-child')
-
-    expect(component).toHaveClass('ams-aspect-ratio--x-tall')
-  })
-
-  it('renders class names to display the image with the default aspect ratio', () => {
-    const { container } = render(<Image />)
-
-    const component = container.querySelector(':only-child')
+      const component = container.querySelector(':only-child')
 
-    expect(component).toHaveClass('ams-aspect-ratio--wide')
+      expect(component).toHaveClass(`ams-aspect-ratio--${aspectRatio}`)
+    })
   })
 
   it('supports ForwardRef in React', () => {
diff --git a/packages/react/src/common/types.ts b/packages/react/src/common/types.ts
index 3a294b70a9..d18a01116b 100644
--- a/packages/react/src/common/types.ts
+++ b/packages/react/src/common/types.ts
@@ -1,6 +1,7 @@
+export const aspectRatioOptions = ['x-tall', 'tall', 'square', 'wide', 'x-wide', '2x-wide'] as const
 export type AspectRatioProps = {
   /** The aspect ratio to display media content in. */
-  aspectRatio?: 'x-tall' | 'tall' | 'square' | 'wide' | 'x-wide' | '2x-wide'
+  aspectRatio?: (typeof aspectRatioOptions)[number]
 }
 
 export const crossAlignOptions = ['start', 'center', 'baseline', 'end'] as const

From 1aca351f1092d8afa277ebf3434b03f324d3391a Mon Sep 17 00:00:00 2001
From: Vincent Smedinga <v.smedinga@amsterdam.nl>
Date: Thu, 7 Nov 2024 14:36:55 +0100
Subject: [PATCH 34/42] Remove duplicate type from union

---
 packages/react/src/ImageSlider/ImageSlider.tsx | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/packages/react/src/ImageSlider/ImageSlider.tsx b/packages/react/src/ImageSlider/ImageSlider.tsx
index e62071e68c..476b3921c5 100644
--- a/packages/react/src/ImageSlider/ImageSlider.tsx
+++ b/packages/react/src/ImageSlider/ImageSlider.tsx
@@ -12,9 +12,8 @@ import { ImageSliderItem } from './ImageSliderItem'
 import { ImageSliderScroller } from './ImageSliderScroller'
 import { ImageSliderThumbnails } from './ImageSliderThumbnails'
 import { Image, ImageProps } from '../Image/Image'
-import { AspectRatioProps } from '../common/types'
 
-export type ImageSliderImageProps = ImageProps & AspectRatioProps
+export type ImageSliderImageProps = ImageProps
 
 export type ImageSliderProps = {
   /** Display buttons to navigate to the previous or next image. */

From 487766f2d46b14ad93243127532feee103ce9dde Mon Sep 17 00:00:00 2001
From: Vincent Smedinga <v.smedinga@amsterdam.nl>
Date: Thu, 7 Nov 2024 14:39:09 +0100
Subject: [PATCH 35/42] Remove default aspect ratio from Image instances

---
 storybook/src/components/Breakout/Breakout.stories.tsx | 2 +-
 storybook/src/pages/amsterdam/HomePage/HomeNews.tsx    | 6 +++---
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/storybook/src/components/Breakout/Breakout.stories.tsx b/storybook/src/components/Breakout/Breakout.stories.tsx
index 78a676f463..e45b4d0c45 100644
--- a/storybook/src/components/Breakout/Breakout.stories.tsx
+++ b/storybook/src/components/Breakout/Breakout.stories.tsx
@@ -55,7 +55,7 @@ export const VerticalLayout: Story = {
   args: {
     children: [
       <Breakout.Cell colSpan="all" has="figure" rowSpan={2} rowStart={1}>
-        <Image alt="" src="https://picsum.photos/1600/900" aspectRatio="x-wide" />
+        <Image alt="" src="https://picsum.photos/1600/900" />
       </Breakout.Cell>,
       <Breakout.Cell colSpan="all" has="spotlight" rowSpan={2} rowStart={2}>
         <Spotlight />
diff --git a/storybook/src/pages/amsterdam/HomePage/HomeNews.tsx b/storybook/src/pages/amsterdam/HomePage/HomeNews.tsx
index 944979e7e8..5637dda59b 100644
--- a/storybook/src/pages/amsterdam/HomePage/HomeNews.tsx
+++ b/storybook/src/pages/amsterdam/HomePage/HomeNews.tsx
@@ -7,7 +7,7 @@ export const HomeNews = () => (
     </Grid.Cell>
     <Grid.Cell span={4}>
       <Card>
-        <Image alt="" aspectRatio="x-wide" src="https://picsum.photos/640/360?random=1" />
+        <Image alt="" src="https://picsum.photos/640/360?random=1" />
         <Card.HeadingGroup tagline="Nieuws">
           <Heading level={2} size="level-4">
             <Card.Link href="#">Nederlands eerste houten woonwijk komt in Zuidoost</Card.Link>
@@ -17,7 +17,7 @@ export const HomeNews = () => (
     </Grid.Cell>
     <Grid.Cell span={4}>
       <Card>
-        <Image alt="" aspectRatio="x-wide" src="https://picsum.photos/640/360?random=2" />
+        <Image alt="" src="https://picsum.photos/640/360?random=2" />
         <Card.HeadingGroup tagline="Nieuws">
           <Heading level={2} size="level-4">
             <Card.Link href="#">Gratis openbaar vervoer voor kinderen</Card.Link>
@@ -27,7 +27,7 @@ export const HomeNews = () => (
     </Grid.Cell>
     <Grid.Cell span={4}>
       <Card>
-        <Image alt="" aspectRatio="x-wide" src="https://picsum.photos/640/360?random=3" />
+        <Image alt="" src="https://picsum.photos/640/360?random=3" />
         <Card.HeadingGroup tagline="Nieuws">
           <Heading level={2} size="level-4">
             <Card.Link href="#">Zonnepanelen op uw dak? Zo houdt u uw huis veilig</Card.Link>

From 8f9ecc1d28445eeb08896f3be86929de686c2d20 Mon Sep 17 00:00:00 2001
From: Vincent Smedinga <v.smedinga@amsterdam.nl>
Date: Thu, 7 Nov 2024 14:40:02 +0100
Subject: [PATCH 36/42] Remove obsolete prop

---
 storybook/src/components/Overlap/Overlap.stories.tsx | 1 -
 1 file changed, 1 deletion(-)

diff --git a/storybook/src/components/Overlap/Overlap.stories.tsx b/storybook/src/components/Overlap/Overlap.stories.tsx
index b79c5a0bae..1783380b8d 100644
--- a/storybook/src/components/Overlap/Overlap.stories.tsx
+++ b/storybook/src/components/Overlap/Overlap.stories.tsx
@@ -22,7 +22,6 @@ export const Default: Story = {
       <Image
         key={1}
         alt=""
-        cover
         aspectRatio="2x-wide"
         sizes="(max-width: 36rem) 640px, (max-width: 68rem) 1280px, 1600px"
         src="https://picsum.photos/1600/500"

From d6787be1b852b77619f26d818dad4c456fdb1aae Mon Sep 17 00:00:00 2001
From: Vincent Smedinga <v.smedinga@amsterdam.nl>
Date: Fri, 8 Nov 2024 11:06:13 +0100
Subject: [PATCH 37/42] Ensure the utility class always wins

---
 packages/css/src/components/aspect-ratio/aspect-ratio.scss | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/css/src/components/aspect-ratio/aspect-ratio.scss b/packages/css/src/components/aspect-ratio/aspect-ratio.scss
index 75da842071..061cf6c6a9 100644
--- a/packages/css/src/components/aspect-ratio/aspect-ratio.scss
+++ b/packages/css/src/components/aspect-ratio/aspect-ratio.scss
@@ -6,7 +6,7 @@
 .ams-aspect-ratio {
   @each $name in ("x-tall", "tall", "square", "wide", "x-wide", "2x-wide") {
     &--#{$name} {
-      aspect-ratio: var(--ams-aspect-ratio-#{$name});
+      aspect-ratio: var(--ams-aspect-ratio-#{$name}) !important;
     }
   }
 }

From bfa6dfb66ccd4a58b9ba0ff21627ccaffb39423f Mon Sep 17 00:00:00 2001
From: Vincent Smedinga <v.smedinga@amsterdam.nl>
Date: Fri, 8 Nov 2024 11:25:03 +0100
Subject: [PATCH 38/42] Inline type to prevent confusing rename

---
 storybook/src/utils/AspectRatio/AspectRatio.tsx | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/storybook/src/utils/AspectRatio/AspectRatio.tsx b/storybook/src/utils/AspectRatio/AspectRatio.tsx
index fe7cc5ea72..ec0d114fa1 100644
--- a/storybook/src/utils/AspectRatio/AspectRatio.tsx
+++ b/storybook/src/utils/AspectRatio/AspectRatio.tsx
@@ -3,12 +3,13 @@
  * Copyright Gemeente Amsterdam
  */
 
-import { AspectRatioProps as IAspectRatioProps } from '@amsterdam/design-system-react/src/common/types'
+import { AspectRatioProps } from '@amsterdam/design-system-react/src/common/types'
 import { HTMLAttributes, PropsWithChildren } from 'react'
 
-export type AspectRatioProps = IAspectRatioProps & PropsWithChildren<HTMLAttributes<HTMLSpanElement>>
-
 /** Renders examples in Storybook. Not for reuse. */
-export const AspectRatio = ({ children, aspectRatio }: AspectRatioProps) => (
+export const AspectRatio = ({
+  children,
+  aspectRatio,
+}: AspectRatioProps & PropsWithChildren<HTMLAttributes<HTMLSpanElement>>) => (
   <span className={`ams-aspect-ratio--${aspectRatio}`}>{children}</span>
 )

From e47dc7f710070d3eaa8bfc1dd2cd7a3baf804428 Mon Sep 17 00:00:00 2001
From: Vincent Smedinga <v.smedinga@amsterdam.nl>
Date: Fri, 8 Nov 2024 11:25:53 +0100
Subject: [PATCH 39/42] Revert compiler setting

---
 storybook/tsconfig.json | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/storybook/tsconfig.json b/storybook/tsconfig.json
index c59bdbd36a..00d767d80f 100644
--- a/storybook/tsconfig.json
+++ b/storybook/tsconfig.json
@@ -1,8 +1,7 @@
 {
   "compilerOptions": {
     "jsx": "react-jsx",
-    "allowSyntheticDefaultImports": true,
-    "resolveJsonModule": true
+    "allowSyntheticDefaultImports": true
   },
   "extends": "../tsconfig.json",
   "include": ["src/**/*.ts", "src/**/*.tsx", "config/**/*.ts", "config/**/*.tsx"],

From 14893b988bedcb69066de6b4cacff44a3dd4d5d9 Mon Sep 17 00:00:00 2001
From: Vincent Smedinga <v.smedinga@amsterdam.nl>
Date: Fri, 8 Nov 2024 11:28:25 +0100
Subject: [PATCH 40/42] Infer removed type

---
 storybook/src/utils/AspectRatio/AspectRatio.stories.tsx | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/storybook/src/utils/AspectRatio/AspectRatio.stories.tsx b/storybook/src/utils/AspectRatio/AspectRatio.stories.tsx
index a5bd7d6f79..be6a976932 100644
--- a/storybook/src/utils/AspectRatio/AspectRatio.stories.tsx
+++ b/storybook/src/utils/AspectRatio/AspectRatio.stories.tsx
@@ -5,7 +5,6 @@
 
 import { Meta, StoryObj } from '@storybook/react'
 import { AspectRatio } from './AspectRatio'
-import type { AspectRatioProps } from './AspectRatio'
 
 const meta = {
   title: 'Utilities/CSS/Aspect Ratio',
@@ -19,7 +18,7 @@ const meta = {
       options: ['2x-wide', 'x-wide', 'wide', 'square', 'tall', 'x-tall'],
     },
   },
-  render: ({ aspectRatio }: AspectRatioProps) => (
+  render: ({ aspectRatio }) => (
     <div className="ams-docs-column ams-docs-aspect-ratio">
       <div className={`ams-docs-item ams-aspect-ratio--${aspectRatio}`}></div>
     </div>

From 062f47e7b49ad960a94cee42221e668156459073 Mon Sep 17 00:00:00 2001
From: Vincent Smedinga <v.smedinga@amsterdam.nl>
Date: Fri, 8 Nov 2024 11:31:18 +0100
Subject: [PATCH 41/42] Use consistent rationale

---
 packages/css/src/components/aspect-ratio/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/css/src/components/aspect-ratio/README.md b/packages/css/src/components/aspect-ratio/README.md
index e86b5b320a..e28f1973de 100644
--- a/packages/css/src/components/aspect-ratio/README.md
+++ b/packages/css/src/components/aspect-ratio/README.md
@@ -2,7 +2,7 @@
 
 # Aspect Ratio
 
-Aspect Ratio updates the height of an element with its width.
+Constrains media content to a supported aspect ratio.
 
 ## Class names
 

From e0c4049d8aae4ceed146e6204b052560ed893df3 Mon Sep 17 00:00:00 2001
From: Vincent Smedinga <v.smedinga@amsterdam.nl>
Date: Fri, 8 Nov 2024 11:35:55 +0100
Subject: [PATCH 42/42] Apply suggestions from code review

Co-authored-by: Aram <37216945+alimpens@users.noreply.github.com>
---
 packages/css/src/components/image/README.md                  | 4 ++--
 storybook/src/foundation/design-tokens/aspect-ratio.docs.mdx | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/packages/css/src/components/image/README.md b/packages/css/src/components/image/README.md
index 4724961ca8..c4a9cb7e52 100644
--- a/packages/css/src/components/image/README.md
+++ b/packages/css/src/components/image/README.md
@@ -6,9 +6,9 @@ Displays an image.
 
 ## Design
 
-Every Image must display in one of the [available aspect ratios](https://designsystem.amsterdam/?path=/docs/brand-design-tokens-aspect-ratio--docs).
+Every Image should be shown in one of the [available aspect ratios](https://designsystem.amsterdam/?path=/docs/brand-design-tokens-aspect-ratio--docs).
 The default is 16:9.
-If the intrinsic dimensions of the source do not match an aspect ratio, the image will get cropped to cover the intended area without distorting its appearance.
+If the intrinsic dimensions of the source do not match an aspect ratio, the image will get cropped to cover the intended area.
 
 ## Guidelines
 
diff --git a/storybook/src/foundation/design-tokens/aspect-ratio.docs.mdx b/storybook/src/foundation/design-tokens/aspect-ratio.docs.mdx
index 1a277f14dc..8d5bfc15d8 100644
--- a/storybook/src/foundation/design-tokens/aspect-ratio.docs.mdx
+++ b/storybook/src/foundation/design-tokens/aspect-ratio.docs.mdx
@@ -13,7 +13,7 @@ Constrains media content to a supported aspect ratio.
 Media content like images, videos, and maps take up sizable portions of a screen.
 Displaying them in a limited set of aspect ratios keeps the visual impression of a page composed.
 The default aspect ratio is 16:9.
-Content with intrinsic dimensions that do not match an aspect ratio will be cropped without distorting its appearance.
+Content with intrinsic dimensions that do not match an aspect ratio will be cropped.
 
 ## Tokens