From 5593916904db612f4dfa1c5d02c88add35d0103a Mon Sep 17 00:00:00 2001
From: Aram <37216945+alimpens@users.noreply.github.com>
Date: Fri, 21 Jun 2024 12:29:20 +0200
Subject: [PATCH 1/3] fix: Fix FieldSet float issue (#1268)

Co-authored-by: Vincent Smedinga <v.smedinga@amsterdam.nl>
---
 packages/css/src/components/field-set/field-set.scss   | 4 ++++
 storybook/src/components/FieldSet/FieldSet.stories.tsx | 6 +++---
 2 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/packages/css/src/components/field-set/field-set.scss b/packages/css/src/components/field-set/field-set.scss
index c5dbd83589..9b4a690462 100644
--- a/packages/css/src/components/field-set/field-set.scss
+++ b/packages/css/src/components/field-set/field-set.scss
@@ -28,6 +28,10 @@
   float: inline-start; // [1]
   inline-size: 100%; // [1]
   padding-inline: 0;
+
+  + * {
+    clear: both; // Reset the applied float for the legend’s first sibling
+  }
 }
 
 // [1] This combination allows the fieldset border to go around the legend, instead of through it.
diff --git a/storybook/src/components/FieldSet/FieldSet.stories.tsx b/storybook/src/components/FieldSet/FieldSet.stories.tsx
index 1aed9b47b9..ca444a3ed8 100644
--- a/storybook/src/components/FieldSet/FieldSet.stories.tsx
+++ b/storybook/src/components/FieldSet/FieldSet.stories.tsx
@@ -38,7 +38,7 @@ type Story = StoryObj<typeof meta>
 export const Default: Story = {
   render: (args) => (
     <FieldSet invalid={args.invalid} legend={args.legend}>
-      <Column gap="extra-small" style={{ width: '100%' }}>
+      <Column gap="extra-small">
         <Label htmlFor="input1">Voornaam</Label>
         <TextInput id="input1" invalid={args.invalid} aria-required="true" />
         <Label htmlFor="input2">Achternaam</Label>
@@ -161,7 +161,7 @@ export const CheckboxGroup: Story = {
   },
   render: (args) => (
     <FieldSet legend={args.legend} invalid={args.invalid}>
-      <Column gap="extra-small" style={{ width: '100%' }}>
+      <Column gap="extra-small">
         <Checkbox name="about" value="horeca" invalid={args.invalid} aria-required="true">
           Horecabedrijf
         </Checkbox>
@@ -187,7 +187,7 @@ export const CheckboxGroup: Story = {
 //   render: (args) => (
 //     <FieldSet legend={args.legend} invalid={args.invalid}>
 //       {args.invalid && <ErrorMessage className="ams-mb--sm">Geef aan waar uw melding over gaat.</ErrorMessage>}
-//       <Column gap="extra-small" style={{ width: '100%' }}>
+//       <Column gap="extra-small">
 //         <Checkbox name="about" value="horeca" invalid={args.invalid} aria-required="true">
 //           Horecabedrijf
 //         </Checkbox>

From e5f8d5820b4aac7e9ed145e3a3dbfd22480304de Mon Sep 17 00:00:00 2001
From: Niels Roozemond <n.roozemond@amsterdam.nl>
Date: Fri, 21 Jun 2024 14:11:37 +0200
Subject: [PATCH 2/3] feat: Add examples of entire pages to Storybook (#1234)

Co-authored-by: Vincent Smedinga <v.smedinga@amsterdam.nl>
---
 packages/react/src/PageMenu/PageMenu.test.tsx |  10 +-
 storybook/config/manager-head.html            |   6 +-
 storybook/config/preview.tsx                  |   2 +
 storybook/config/storybook-overrides.css      |   4 +
 .../Breadcrumb/Breadcrumb.stories.tsx         |   7 +-
 .../src/components/Card/Card.stories.tsx      |  15 +-
 .../src/components/Footer/Footer.docs.mdx     |  11 +-
 .../src/components/Footer/Footer.stories.tsx  | 198 +++++++++++++-----
 storybook/src/components/Image/Image.docs.mdx |   1 +
 .../src/components/Image/Image.stories.tsx    |   1 +
 .../components/Overlap/Overlap.stories.tsx    |   5 +-
 .../components/PageMenu/PageMenu.stories.tsx  |  19 +-
 .../src/components/shared/exampleContent.ts   |  59 +++++-
 storybook/src/pages/Introduction.docs.mdx     |  39 ++++
 .../pages/amsterdam/article/Article.docs.mdx  |  10 +
 .../amsterdam/article/Article.stories.tsx     |  38 ++++
 .../src/pages/amsterdam/article/Article.tsx   |  45 ++++
 .../pages/amsterdam/article/ArticleBody.tsx   | 116 ++++++++++
 .../amsterdam/article/ArticleBreadcrumb.tsx   |  12 ++
 .../pages/amsterdam/article/ArticleHeader.tsx |  20 ++
 .../src/pages/amsterdam/common/AppHeader.tsx  |  13 ++
 .../src/pages/amsterdam/home/Home.docs.mdx    |  46 ++++
 .../src/pages/amsterdam/home/Home.stories.tsx |  30 +++
 storybook/src/pages/amsterdam/home/Home.tsx   |  29 +++
 .../src/pages/amsterdam/home/HomeNews.tsx     |  45 ++++
 .../pages/amsterdam/home/HomeSpotlight.tsx    |  32 +++
 .../src/pages/amsterdam/home/HomeTopTasks.tsx |  84 ++++++++
 27 files changed, 808 insertions(+), 89 deletions(-)
 create mode 100644 storybook/src/pages/Introduction.docs.mdx
 create mode 100644 storybook/src/pages/amsterdam/article/Article.docs.mdx
 create mode 100644 storybook/src/pages/amsterdam/article/Article.stories.tsx
 create mode 100644 storybook/src/pages/amsterdam/article/Article.tsx
 create mode 100644 storybook/src/pages/amsterdam/article/ArticleBody.tsx
 create mode 100644 storybook/src/pages/amsterdam/article/ArticleBreadcrumb.tsx
 create mode 100644 storybook/src/pages/amsterdam/article/ArticleHeader.tsx
 create mode 100644 storybook/src/pages/amsterdam/common/AppHeader.tsx
 create mode 100644 storybook/src/pages/amsterdam/home/Home.docs.mdx
 create mode 100644 storybook/src/pages/amsterdam/home/Home.stories.tsx
 create mode 100644 storybook/src/pages/amsterdam/home/Home.tsx
 create mode 100644 storybook/src/pages/amsterdam/home/HomeNews.tsx
 create mode 100644 storybook/src/pages/amsterdam/home/HomeSpotlight.tsx
 create mode 100644 storybook/src/pages/amsterdam/home/HomeTopTasks.tsx

diff --git a/packages/react/src/PageMenu/PageMenu.test.tsx b/packages/react/src/PageMenu/PageMenu.test.tsx
index e87e594afa..ad40927c05 100644
--- a/packages/react/src/PageMenu/PageMenu.test.tsx
+++ b/packages/react/src/PageMenu/PageMenu.test.tsx
@@ -8,9 +8,11 @@ describe('Page menu', () => {
   it('renders a page menu with children', () => {
     const { container } = render(
       <PageMenu>
-        <PageMenu.Link href="#">English</PageMenu.Link>
+        <PageMenu.Link href="#" lang="en">
+          English
+        </PageMenu.Link>
         <PageMenu.Link href="#" icon={LoginIcon}>
-          Inloggen Mijn Amsterdam
+          Mijn Amsterdam
         </PageMenu.Link>
       </PageMenu>,
     )
@@ -39,7 +41,9 @@ describe('Page menu', () => {
     const ref = createRef<HTMLUListElement>()
     const { container } = render(
       <PageMenu ref={ref}>
-        <PageMenu.Link href="#">English</PageMenu.Link>
+        <PageMenu.Link href="#" lang="en">
+          English
+        </PageMenu.Link>
       </PageMenu>,
     )
     const component = container.querySelector(':only-child')
diff --git a/storybook/config/manager-head.html b/storybook/config/manager-head.html
index 7f45090a29..c45ed87fff 100644
--- a/storybook/config/manager-head.html
+++ b/storybook/config/manager-head.html
@@ -1,9 +1,11 @@
 <script id="storybook-mod-expand-all-folders" type="text/javascript">
   // Somewhat hacky way to expand all folders. Storybook does not support that natively.
   var clickCollapsedItemsUntilNoneLeft = () => {
-    const itemsLeftToClick = document.querySelectorAll('button[data-parent-id="components"][aria-expanded="false"]');
+    const collapsedItems = document.querySelectorAll(
+      ':is(button[data-parent-id="components"], button[data-parent-id="pages"])[aria-expanded="false"]',
+    );
 
-    for (item of itemsLeftToClick) {
+    for (item of collapsedItems) {
       item.click();
     }
   };
diff --git a/storybook/config/preview.tsx b/storybook/config/preview.tsx
index 4f7a0a31e3..246dbffdba 100644
--- a/storybook/config/preview.tsx
+++ b/storybook/config/preview.tsx
@@ -42,6 +42,8 @@ export const parameters = {
         ['Introduction', 'Assets', 'Design Guidelines'],
         'Components',
         ['Buttons', 'Containers', 'Feedback', 'Forms', 'Layout', 'Media', 'Navigation', 'Text'],
+        'Pages',
+        ['Introduction', 'Amsterdam.nl', ['Home']],
       ],
     },
   },
diff --git a/storybook/config/storybook-overrides.css b/storybook/config/storybook-overrides.css
index bd7a65cb51..20be896f9d 100644
--- a/storybook/config/storybook-overrides.css
+++ b/storybook/config/storybook-overrides.css
@@ -114,4 +114,8 @@
   font-size: 0.875rem;
 }
 
+:is(#storybook-root, .sbdocs-content) a[href="#"] {
+  cursor: not-allowed;
+}
+
 /* stylelint-enable */
diff --git a/storybook/src/components/Breadcrumb/Breadcrumb.stories.tsx b/storybook/src/components/Breadcrumb/Breadcrumb.stories.tsx
index bf6c23da07..6dc69fe307 100644
--- a/storybook/src/components/Breadcrumb/Breadcrumb.stories.tsx
+++ b/storybook/src/components/Breadcrumb/Breadcrumb.stories.tsx
@@ -22,10 +22,13 @@ export const Default: Story = {
         Home
       </Breadcrumb.Link>,
       <Breadcrumb.Link href="#" key={2}>
-        Nieuws
+        Afval
       </Breadcrumb.Link>,
       <Breadcrumb.Link href="#" key={3}>
-        Kennisgevingen en bekendmakingen
+        Bedrijfsafval
+      </Breadcrumb.Link>,
+      <Breadcrumb.Link href="#" key={4}>
+        Recyclepunten voor bedrijven
       </Breadcrumb.Link>,
     ],
   },
diff --git a/storybook/src/components/Card/Card.stories.tsx b/storybook/src/components/Card/Card.stories.tsx
index 58b0942815..f1fda4c4f8 100644
--- a/storybook/src/components/Card/Card.stories.tsx
+++ b/storybook/src/components/Card/Card.stories.tsx
@@ -5,6 +5,7 @@
 
 import { AspectRatio, Card, Heading, Image, Paragraph } from '@amsterdam/design-system-react/src'
 import { Meta, StoryObj } from '@storybook/react'
+import { exampleTopTask } from '../shared/exampleContent'
 
 const dateFormat = new Intl.DateTimeFormat('nl', {
   day: 'numeric',
@@ -13,6 +14,8 @@ const dateFormat = new Intl.DateTimeFormat('nl', {
 })
 const today = dateFormat.format(Date.now())
 
+const topTask = exampleTopTask()
+
 const meta = {
   title: 'Components/Navigation/Card',
   component: Card,
@@ -33,11 +36,9 @@ export const Default: Story = {
   args: {
     children: [
       <Heading size="level-4" key={1}>
-        <Card.Link href="/">Monitor Attracties MRA</Card.Link>
+        <Card.Link href="/">{topTask.heading}</Card.Link>
       </Heading>,
-      <Paragraph key={2}>
-        Ontwikkeling van het aantal attracties en bezoekers in de metropoolregio Amsterdam.
-      </Paragraph>,
+      <Paragraph key={2}>{topTask.description}</Paragraph>,
     ],
   },
 }
@@ -63,13 +64,13 @@ export const WithImage: Story = {
       <AspectRatio key={1} ratio="wide">
         <Image alt="" src="https://picsum.photos/480/360" />
       </AspectRatio>,
-      <Card.HeadingGroup key={2} tagline="Dossier">
+      <Card.HeadingGroup key={2} tagline="Nieuws">
         <Heading size="level-4">
-          <Card.Link href="/">Monitor Attracties MRA</Card.Link>
+          <Card.Link href="/">Nederlands eerste houten woonwijk komt in Zuidoost</Card.Link>
         </Heading>
       </Card.HeadingGroup>,
       <Paragraph key={3}>
-        Ontwikkeling van het aantal attracties en bezoekers in de metropoolregio Amsterdam.
+        We bouwen een levendige, groene en duurzame woonbuurt tussen de Gooiseweg en het Nelson Mandelapark.
       </Paragraph>,
       <Paragraph key={4} size="small">
         {today}
diff --git a/storybook/src/components/Footer/Footer.docs.mdx b/storybook/src/components/Footer/Footer.docs.mdx
index 8dc936480f..80017d7615 100644
--- a/storybook/src/components/Footer/Footer.docs.mdx
+++ b/storybook/src/components/Footer/Footer.docs.mdx
@@ -1,6 +1,6 @@
 {/* @license CC0-1.0 */}
 
-import { Markdown, Meta, Primary } from "@storybook/blocks";
+import { Canvas, Markdown, Meta, Primary } from "@storybook/blocks";
 import * as FooterStories from "./Footer.stories.tsx";
 import README from "../../../../packages/css/src/components/footer/README.md?raw";
 
@@ -9,3 +9,12 @@ import README from "../../../../packages/css/src/components/footer/README.md?raw
 <Markdown>{README}</Markdown>
 
 <Primary />
+
+## Examples
+
+### Onderzoek en Statistiek
+
+The footer for a specific website can be a bit different.
+Here’s an example for the ‘Onderzoek en Statistiek’ department.
+
+<Canvas of={FooterStories.Onderzoek} />
diff --git a/storybook/src/components/Footer/Footer.stories.tsx b/storybook/src/components/Footer/Footer.stories.tsx
index 2d65c76acf..54de0bbe19 100644
--- a/storybook/src/components/Footer/Footer.stories.tsx
+++ b/storybook/src/components/Footer/Footer.stories.tsx
@@ -12,8 +12,17 @@ import {
   Paragraph,
   VisuallyHidden,
 } from '@amsterdam/design-system-react/src'
-import { EmailIcon, PhoneIcon } from '@amsterdam/design-system-react-icons'
+import {
+  CameraIcon,
+  ClockIcon,
+  EmailIcon,
+  FacebookIcon,
+  LinkedinIcon,
+  PhoneIcon,
+  TwitterIcon,
+} from '@amsterdam/design-system-react-icons'
 import { Meta, StoryObj } from '@storybook/react'
+import { Default as PageMenuStory } from '../../components/PageMenu/PageMenu.stories'
 
 const meta = {
   title: 'Components/Containers/Footer',
@@ -24,6 +33,13 @@ export default meta
 
 type Story = StoryObj<typeof meta>
 
+const socialPlatforms = [
+  { icon: TwitterIcon, name: 'Twitter' },
+  { icon: FacebookIcon, name: 'Facebook' },
+  { icon: LinkedinIcon, name: 'Linkedin' },
+  { icon: CameraIcon, name: 'Instagram' },
+]
+
 export const Default: Story = {
   args: {
     children: [
@@ -32,65 +48,140 @@ export const Default: Story = {
           <Heading>Colofon</Heading>
         </VisuallyHidden>
         <Grid gapVertical="large" paddingVertical="medium">
-          <Grid.Cell span={3}>
-            <div style={{ display: 'grid', gap: '2.5rem' }}>
-              <Heading level={2} size="level-4" inverseColor>
-                Contact
+          <Grid.Cell span={4}>
+            <Heading className="ams-mb--xs" level={2} size="level-4" inverseColor>
+              Meer weten
+            </Heading>
+            <LinkList>
+              {['Veel gestelde vragen', 'Over ons', 'Werken bij', 'Kalender', 'Uit in Amsterdam', 'Bronnen'].map(
+                (label, index) => (
+                  <LinkList.Link href="#" key={index} onBackground="dark" size="small">
+                    {label}
+                  </LinkList.Link>
+                ),
+              )}
+            </LinkList>
+          </Grid.Cell>
+          <Grid.Cell span={4} start={{ narrow: 1, medium: 5, wide: 5 }}>
+            <Heading className="ams-mb--xs" level={2} size="level-4" inverseColor>
+              Contact
+            </Heading>
+            <Paragraph className="ams-mb--xs" inverseColor size="small">
+              Hebt u een vraag en kunt u het antwoord niet vinden op deze website? Neem dan contact met ons op.
+            </Paragraph>
+            <LinkList>
+              <LinkList.Link href="mailto:redactie@amsterdam.nl" icon={EmailIcon} onBackground="dark" size="small">
+                E-mail
+              </LinkList.Link>
+              <LinkList.Link href="tel:+3114020" icon={PhoneIcon} onBackground="dark" size="small">
+                14 020
+              </LinkList.Link>
+              <LinkList.Link href="#" icon={ClockIcon} onBackground="dark" size="small">
+                Contactgegevens en openingstijden
+              </LinkList.Link>
+            </LinkList>
+          </Grid.Cell>
+          <Grid.Cell span={4} start={{ narrow: 1, medium: 1, wide: 9 }}>
+            <section className="ams-mb--md">
+              <Heading className="ams-mb--xs" level={2} size="level-4" inverseColor>
+                Nieuwsbrief
               </Heading>
-              <Paragraph size="small" inverseColor>
-                Heeft u een vraag en kunt u het antwoord niet vinden op deze site? Neem dan contact met ons op.
-              </Paragraph>
               <LinkList>
-                <LinkList.Link href="mailto:redactie.os@amsterdam.nl" icon={EmailIcon} onBackground="dark" size="small">
-                  E-mail
-                </LinkList.Link>
-                <LinkList.Link href="tel:+31202510333" icon={PhoneIcon} onBackground="dark" size="small">
-                  020 251 0333
+                <LinkList.Link href="#" onBackground="dark" size="small">
+                  Inschrijven
                 </LinkList.Link>
               </LinkList>
-            </div>
-          </Grid.Cell>
-          <Grid.Cell span={3} start={{ narrow: 1, medium: 5, wide: 5 }}>
-            <div style={{ display: 'grid', gap: '2.5rem' }}>
-              <Heading level={2} size="level-4" inverseColor>
-                Panels en enquêtes
+            </section>
+            <section>
+              <Heading className="ams-mb--xs" level={2} size="level-4" inverseColor>
+                Volg ons
               </Heading>
-              <Paragraph size="small" inverseColor>
-                Bent u uitgenodigd om mee te doen aan onderzoek of heeft u vragen over het panel of stadspaspanel?
-              </Paragraph>
               <LinkList>
-                <LinkList.Link href="#" onBackground="dark" rel="external" size="small">
-                  Meedoen aan onderzoek
-                </LinkList.Link>
-                <LinkList.Link href="#" onBackground="dark" rel="external" size="small">
-                  Panel Amsterdam
-                </LinkList.Link>
-                <LinkList.Link href="#" onBackground="dark" rel="external" size="small">
-                  Stadspaspanel Amsterdam
-                </LinkList.Link>
+                {socialPlatforms.map(({ name, icon }) => (
+                  <LinkList.Link href="#" icon={icon} key={name} onBackground="dark" size="small">
+                    {name}
+                  </LinkList.Link>
+                ))}
               </LinkList>
-            </div>
+            </section>
+          </Grid.Cell>
+        </Grid>
+      </Footer.Top>,
+      <Footer.Bottom key="footer-bottom">
+        <VisuallyHidden>
+          <Heading level={2}>Over deze website</Heading>
+        </VisuallyHidden>
+        <Grid paddingVertical="small">
+          <Grid.Cell span="all">
+            <PageMenu>{PageMenuStory.args?.children}</PageMenu>
+          </Grid.Cell>
+        </Grid>
+      </Footer.Bottom>,
+    ],
+  },
+}
+
+export const Onderzoek: Story = {
+  args: {
+    children: [
+      <Footer.Top key="footer-top">
+        <VisuallyHidden>
+          <Heading>Colofon</Heading>
+        </VisuallyHidden>
+        <Grid gapVertical="large" paddingVertical="medium">
+          <Grid.Cell span={3}>
+            <Heading className="ams-mb--xs" level={2} size="level-4" inverseColor>
+              Contact
+            </Heading>
+            <Paragraph className="ams-mb--xs" size="small" inverseColor>
+              Heeft u een vraag en kunt u het antwoord niet vinden op deze site? Neem dan contact met ons op.
+            </Paragraph>
+            <LinkList>
+              <LinkList.Link href="mailto:redactie.os@amsterdam.nl" icon={EmailIcon} onBackground="dark" size="small">
+                E-mail
+              </LinkList.Link>
+              <LinkList.Link href="tel:+31202510333" icon={PhoneIcon} onBackground="dark" size="small">
+                020 251 0333
+              </LinkList.Link>
+            </LinkList>
+          </Grid.Cell>
+          <Grid.Cell span={3} start={{ narrow: 1, medium: 5, wide: 5 }}>
+            <Heading className="ams-mb--xs" level={2} size="level-4" inverseColor>
+              Panels en enquêtes
+            </Heading>
+            <Paragraph className="ams-mb--xs" inverseColor size="small">
+              Bent u uitgenodigd om mee te doen aan onderzoek of heeft u vragen over het panel of stadspaspanel?
+            </Paragraph>
+            <LinkList>
+              <LinkList.Link href="#" onBackground="dark" rel="external" size="small">
+                Meedoen aan onderzoek
+              </LinkList.Link>
+              <LinkList.Link href="#" onBackground="dark" rel="external" size="small">
+                Panel Amsterdam
+              </LinkList.Link>
+              <LinkList.Link href="#" onBackground="dark" rel="external" size="small">
+                Stadspaspanel Amsterdam
+              </LinkList.Link>
+            </LinkList>
           </Grid.Cell>
           <Grid.Cell span={3} start={{ narrow: 1, medium: 1, wide: 9 }}>
-            <div style={{ display: 'grid', gap: '2.5rem' }}>
-              <Heading level={2} size="level-4" inverseColor>
-                Onderzoek en Statistiek
-              </Heading>
-              <LinkList>
-                <LinkList.Link href="#" onBackground="dark" size="small">
-                  Over Onderzoek en Statistiek
-                </LinkList.Link>
-                <LinkList.Link href="#" onBackground="dark" size="small">
-                  Veelgestelde vragen
-                </LinkList.Link>
-                <LinkList.Link href="#" onBackground="dark" rel="external" size="small">
-                  Nieuwsbrief
-                </LinkList.Link>
-                <LinkList.Link href="#" onBackground="dark" size="small">
-                  Vacatures
-                </LinkList.Link>
-              </LinkList>
-            </div>
+            <Heading className="ams-mb--xs" level={2} size="level-4" inverseColor>
+              Onderzoek en Statistiek
+            </Heading>
+            <LinkList>
+              <LinkList.Link href="#" onBackground="dark" size="small">
+                Over Onderzoek en Statistiek
+              </LinkList.Link>
+              <LinkList.Link href="#" onBackground="dark" size="small">
+                Veelgestelde vragen
+              </LinkList.Link>
+              <LinkList.Link href="#" onBackground="dark" rel="external" size="small">
+                Nieuwsbrief
+              </LinkList.Link>
+              <LinkList.Link href="#" onBackground="dark" size="small">
+                Vacatures
+              </LinkList.Link>
+            </LinkList>
           </Grid.Cell>
         </Grid>
       </Footer.Top>,
@@ -100,10 +191,7 @@ export const Default: Story = {
         </VisuallyHidden>
         <Grid paddingVertical="small">
           <Grid.Cell span="all">
-            <PageMenu>
-              <PageMenu.Link href="#">Privacy</PageMenu.Link>
-              <PageMenu.Link href="#">Toegankelijkheid</PageMenu.Link>
-            </PageMenu>
+            <PageMenu>{PageMenuStory.args?.children}</PageMenu>
           </Grid.Cell>
         </Grid>
       </Footer.Bottom>,
diff --git a/storybook/src/components/Image/Image.docs.mdx b/storybook/src/components/Image/Image.docs.mdx
index 3c965f23d5..95e2441c44 100644
--- a/storybook/src/components/Image/Image.docs.mdx
+++ b/storybook/src/components/Image/Image.docs.mdx
@@ -18,6 +18,7 @@ import README from "../../../../packages/css/src/components/image/README.md?raw"
 
 Use the srcSet prop, which controls the corresponding HTML attribute (see [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#srcset)), to let the browser select the optimal source file for the image.
 A mobile device can often download a smaller file, saving the user’s bandwidth and time.
+Don’t forget to still include the required `src` attribute.
 
 <Canvas of={ImageStories.MultipleSources} />
 
diff --git a/storybook/src/components/Image/Image.stories.tsx b/storybook/src/components/Image/Image.stories.tsx
index a96ce36a45..34922db809 100644
--- a/storybook/src/components/Image/Image.stories.tsx
+++ b/storybook/src/components/Image/Image.stories.tsx
@@ -36,6 +36,7 @@ export const Default: Story = {
 export const MultipleSources: Story = {
   args: {
     alt: '',
+    src: 'https://picsum.photos/1280/720',
     srcSet: 'https://picsum.photos/640/360 640w, https://picsum.photos/1280/720 1280w',
     sizes: '(max-width: 36rem) 640px, 50vw',
   },
diff --git a/storybook/src/components/Overlap/Overlap.stories.tsx b/storybook/src/components/Overlap/Overlap.stories.tsx
index b67df32551..ce8ae980f5 100644
--- a/storybook/src/components/Overlap/Overlap.stories.tsx
+++ b/storybook/src/components/Overlap/Overlap.stories.tsx
@@ -18,15 +18,16 @@ type Story = StoryObj<typeof meta>
 export const Default: Story = {
   args: {
     children: [
-      <AspectRatio key="background-image" ratio="2x-wide">
+      <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>,
-      <Grid key="search-field" style={{ alignSelf: 'center' }}>
+      <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()}>
             <SearchField.Input label="Zoeken" placeholder="Wat kunnen we voor u vinden?" />
diff --git a/storybook/src/components/PageMenu/PageMenu.stories.tsx b/storybook/src/components/PageMenu/PageMenu.stories.tsx
index d618024fd3..e84ef4eee6 100644
--- a/storybook/src/components/PageMenu/PageMenu.stories.tsx
+++ b/storybook/src/components/PageMenu/PageMenu.stories.tsx
@@ -4,7 +4,7 @@
  */
 
 import { PageMenu } from '@amsterdam/design-system-react/src'
-import { LoginIcon, SearchIcon } from '@amsterdam/design-system-react-icons'
+import { SearchIcon } from '@amsterdam/design-system-react-icons'
 import { Meta, StoryObj } from '@storybook/react'
 
 const meta = {
@@ -24,10 +24,13 @@ export const Default: Story = {
   args: {
     children: [
       <PageMenu.Link href="#" key={1}>
-        English
+        Over deze site
+      </PageMenu.Link>,
+      <PageMenu.Link href="#" key={2}>
+        Privacy
       </PageMenu.Link>,
-      <PageMenu.Link href="#" icon={LoginIcon} key={2}>
-        Inloggen Mijn Amsterdam
+      <PageMenu.Link href="#" key={3}>
+        Cookies
       </PageMenu.Link>,
     ],
   },
@@ -37,13 +40,13 @@ export const Alignment: Story = {
   args: {
     alignEnd: true,
     children: [
-      <PageMenu.Link href="#" key={1}>
-        Contact
+      <PageMenu.Link href="#" key={1} lang="en">
+        English
       </PageMenu.Link>,
       <PageMenu.Link href="#" key={2}>
-        Mijn Amsterdam
+        Contact
       </PageMenu.Link>,
-      <PageMenu.Link href="#" icon={SearchIcon} key={3}>
+      <PageMenu.Link href="#" key={3} icon={SearchIcon}>
         Zoeken
       </PageMenu.Link>,
     ],
diff --git a/storybook/src/components/shared/exampleContent.ts b/storybook/src/components/shared/exampleContent.ts
index 0420e1a774..f6ddd28ceb 100644
--- a/storybook/src/components/shared/exampleContent.ts
+++ b/storybook/src/components/shared/exampleContent.ts
@@ -3,12 +3,10 @@
  * Copyright Gemeente Amsterdam
  */
 
-const pickRandomItem = (list: Array<string>): string => list[Math.floor(Math.random() * list.length)]
-
-const pickRandomList = (list: Array<Array<string>>): Array<string> => list[Math.floor(Math.random() * list.length)]
+const pickRandomContent = <T>(list: Array<T>): T => list[Math.floor(Math.random() * list.length)]
 
 export const exampleHeading = () =>
-  pickRandomItem([
+  pickRandomContent<string>([
     'Meer plekken voor kunst en cultuur, verspreid over de stad',
     'Amsterdam Light Festival maakt de stad ook deze winter een beetje mooier',
     'Opvang voor dak- en thuisloze mensen vanwege lage temperaturen',
@@ -25,7 +23,7 @@ export const exampleHeading = () =>
   ])
 
 export const exampleLinkList = () =>
-  pickRandomList([
+  pickRandomContent<Array<string>>([
     ['Contactformulier', 'Adressen en openingstijden', 'Bel 14 020'],
     ['Monumenten en archeologie', 'Ateliers en broedplaatsen', 'Kunstenplan', 'Subsidies'],
     [
@@ -48,7 +46,7 @@ export const exampleLinkList = () =>
   ])
 
 export const exampleOrderedList = () =>
-  pickRandomList([
+  pickRandomContent<Array<string>>([
     [
       'Voor deze actie hebben uw kinderen een persoonlijke OV-chipkaart nodig. Hebben zij die nog niet, dan kunt u die nu al aanvragen. Ieder kind heeft een eigen OV-chipkaart nodig.',
       'U kunt hem aanvragen via ov-chipkaart.nl. De kaart kost € 7,50. U krijgt hem na een dag of 5 thuisgestuurd.',
@@ -86,7 +84,7 @@ export const exampleOrderedList = () =>
   ])
 
 export const exampleParagraph = () =>
-  pickRandomItem([
+  pickRandomContent<string>([
     'Het waterrijke achterland van de provincie Holland was een paradijs voor vissers. Maar terwijl de visserij floreerde in Holland, was Amsterdam eigenlijk helemaal geen visserijstad. Toch maakten Amsterdammers naam in de vishandel. Zij speelden namelijk een cruciale rol bij het klaarmaken en vervoeren van haring.',
     'De politie controleert op overtredingen met opgevoerde/illegale e-bikes en fatbikes. Er worden boetes uitgedeeld en bij grove overtredingen neemt de politie fatbikes in beslag.',
     'Na een flink aantal jaren zijn alle laaghangende takken weg, zodat de boom geen hinder meer geeft. Daarom zie je in het onderste deel van een stadsboom meestal geen zijtakken. Ook halen we takken weg die dood of zwak zijn. Zij kunnen afbreken en dat kan gevaarlijk zijn.',
@@ -101,7 +99,7 @@ export const exampleParagraph = () =>
   ])
 
 export const exampleQuote = () =>
-  pickRandomItem([
+  pickRandomContent<string>([
     'We kunnen in heel Nederland schoolpleinen creëren waar kinderen worden uitgedaagd om samen te spelen en te sporten.',
     'Ik hou zo van een Amsterdamse kroeg en van het zwijgend met gedachten spelen. Alleen het sluitingsuur, voor mij en velen, komt steeds te laat en altijd weer te vroeg.',
     'Voetballen is heel simpel, maar het moeilijkste wat er is, is simpel voetballen.',
@@ -111,8 +109,51 @@ export const exampleQuote = () =>
     'Zorg goed voor de stad en voor elkaar.',
   ])
 
+type TopTask = {
+  heading: string
+  description: string
+}
+
+export const exampleTopTask = () =>
+  pickRandomContent<TopTask>([
+    {
+      heading: 'Gemeentebelastingen',
+      description: 'Bekijk welke belastingen en heffingen er zijn, hoe u bezwaar maakt of een betalingsregeling treft.',
+    },
+    {
+      heading: 'Parkeren + Reizen (P+R)',
+      description: 'U kunt met uw auto goedkoop parkeren bij een P+R-locatie aan de rand van de stad.',
+    },
+    {
+      heading: 'Paspoort',
+      description: 'Vraag deze bewijzen aan of verleng ze. Geef een vermissing aan.',
+    },
+    {
+      heading: 'Onderwijs',
+      description:
+        'Meld een kind aan voor basisschool, middelbare school of kinderopvang. Bekijk het kindtegoed op uw Stadspas.',
+    },
+    {
+      heading: 'Meldingen openbare ruimte en overlast',
+      description:
+        'Ziet u op straat of in een park iets waarvan u wilt dat het gemaakt of opgeruimd wordt, dan kunt u dat bij de gemeente melden.',
+    },
+    {
+      heading: 'Verhuizing doorgeven',
+      description: 'Geef uw nieuwe adres door als u binnen Amsterdam of naar Amsterdam verhuist.',
+    },
+    {
+      heading: 'Grof afval',
+      description: 'Grof afval zijn spullen die niet in een vuilniszak passen.',
+    },
+    {
+      heading: 'Kennisgevingen en bekendmakingen',
+      description: 'Kennisgevingen en bekendmakingen van de gemeente Amsterdam van de laatste 8 weken.',
+    },
+  ])
+
 export const exampleUnorderedList = () =>
-  pickRandomList([
+  pickRandomContent<Array<string>>([
     [
       'Kopie van de pagina’s van het huur- of koopcontract waarop uw naam, adres en handtekeningen staan.',
       'Als u bij iemand woont: een toestemmingsverklaring van de bewoner en een kopie van het paspoort, rijbewijs of ID-kaart van de bewoner.',
diff --git a/storybook/src/pages/Introduction.docs.mdx b/storybook/src/pages/Introduction.docs.mdx
new file mode 100644
index 0000000000..a5f6bf6eb5
--- /dev/null
+++ b/storybook/src/pages/Introduction.docs.mdx
@@ -0,0 +1,39 @@
+{/* @license CC0-1.0 */}
+
+import { Meta } from "@storybook/blocks";
+
+<Meta title="Pages/Introduction" />
+
+# Introduction
+
+This section demonstrates how to compose pages using the Design System’s components.
+It uses the latest release of the libraries, without any customizations, giving an honest representation of what can be achieved with them and how they work in the browser.
+
+Currently, we offer a home page and an article page for the upcoming Amsterdam.nl website.
+
+## Documentation
+
+The ‘Docs’ page explains the design decisions for this type of page and how to build it.
+
+## Examples
+
+Each example, of which the first is called ‘Default’, shows the actual page in its entirety.
+
+### Flexible content
+
+Reload an example to get new random texts and images.
+Use the Control tab to experiment with your own content.
+
+### Test for accessibility and see HTML output
+
+The ‘Accessibility’ tab offers a report of various automatic tests.
+The ‘HTML’ tab displays the entire HTML-document rendered by all components on the page.
+
+### Check how the page would look on various devices
+
+The buttons in the toolbar offer various features, of which the ‘three layered square’ button replicates the appearance and behaviour of the page on a phone, tablet or desktop. Press the button with the two arrows to rotate the screen.
+
+### See the page full-screen
+
+Use the ‘Go to full screen’ (or press `alt+F`) or ‘Open canvas in new tab’ buttons to the top right to see the entire page.
+Alternatively, press `alt+S,T,A` to hide the three panels.
diff --git a/storybook/src/pages/amsterdam/article/Article.docs.mdx b/storybook/src/pages/amsterdam/article/Article.docs.mdx
new file mode 100644
index 0000000000..60e1939d8a
--- /dev/null
+++ b/storybook/src/pages/amsterdam/article/Article.docs.mdx
@@ -0,0 +1,10 @@
+{/* @license CC0-1.0 */}
+
+import { Meta } from "@storybook/blocks";
+import * as ArticleStories from "./Article.stories.tsx";
+
+<Meta of={ArticleStories} />
+
+# Article Page
+
+This page type is mainly for news or related kinds of articles.
diff --git a/storybook/src/pages/amsterdam/article/Article.stories.tsx b/storybook/src/pages/amsterdam/article/Article.stories.tsx
new file mode 100644
index 0000000000..502e365d2d
--- /dev/null
+++ b/storybook/src/pages/amsterdam/article/Article.stories.tsx
@@ -0,0 +1,38 @@
+/**
+ * @license EUPL-1.2+
+ * Copyright Gemeente Amsterdam
+ */
+
+import type { FooterProps } from '@amsterdam/design-system-react'
+import { Meta, StoryObj } from '@storybook/react'
+import type { ReactElement } from 'react'
+import { Article } from './Article'
+import * as FooterStories from '../../../components/Footer/Footer.stories'
+import * as ImageStories from '../../../components/Image/Image.stories'
+
+const meta = {
+  title: 'Pages/Amsterdam.nl/Article',
+  component: Article,
+  args: {
+    footer: FooterStories.Default.args?.children as ReactElement<FooterProps>,
+    heading: 'Ontvang uw paspoort of ID-kaart in de zomer gratis thuis',
+    imageSrc: ImageStories.LazyLoading.args?.src,
+    lead: 'Niet meer naar het Stadsloket, maar thuis of op het werk uw nieuwe paspoort ontvangen. In juni en juli kan dat. Deze zomer bezorgt de gemeente reisdocumenten gratis aan huis. We doen dat om de drukte in de Stadsloketten te verminderen. En u hoeft maar 1 keer naar het Stadsloket.',
+    paragraph1:
+      'Van maandag 10 juni tot en met zaterdag 27 juli bezorgt de gemeente Amsterdam uw paspoort of ID-kaart gratis bij u thuis of op het werk. U moet wel naar het Stadsloket om uw reisdocument aan te vragen. Lees hier hoe het werkt.',
+    spotlightHeading: 'Vraag een paspoort of ID-kaart aan',
+    spotlightLinkLabel: 'Vraag nu een paspoort of ID-kaart aan',
+  },
+  argTypes: {
+    footer: {
+      table: { disable: true },
+    },
+  },
+  parameters: {
+    layout: 'fullscreen',
+  },
+} satisfies Meta<typeof Article>
+
+export default meta
+
+export const Default: StoryObj = {}
diff --git a/storybook/src/pages/amsterdam/article/Article.tsx b/storybook/src/pages/amsterdam/article/Article.tsx
new file mode 100644
index 0000000000..2551004667
--- /dev/null
+++ b/storybook/src/pages/amsterdam/article/Article.tsx
@@ -0,0 +1,45 @@
+import { Footer, Screen, SkipLink } from '@amsterdam/design-system-react'
+import type { FooterProps } from '@amsterdam/design-system-react'
+import { ReactElement } from 'react'
+import { ArticleBody } from './ArticleBody'
+import { ArticleBreadcrumb } from './ArticleBreadcrumb'
+import { ArticleHeader } from './ArticleHeader'
+import { AppHeader } from '../common/AppHeader'
+
+export type ArticleProps = {
+  footer: ReactElement<FooterProps>
+  heading: string
+  imageSrc: string
+  lead: string
+  paragraph1: string
+  spotlightHeading: string
+  spotlightLinkLabel: string
+}
+
+export const Article = ({
+  footer,
+  heading,
+  imageSrc,
+  lead,
+  paragraph1,
+  spotlightHeading,
+  spotlightLinkLabel,
+}: ArticleProps) => (
+  <>
+    <SkipLink href="#main">Direct naar inhoud</SkipLink>
+    <Screen maxWidth="wide">
+      <AppHeader />
+      <ArticleBreadcrumb />
+      <main id="main">
+        <ArticleHeader heading={heading} imageSrc={imageSrc} />
+        <ArticleBody
+          lead={lead}
+          paragraph1={paragraph1}
+          spotlightHeading={spotlightHeading}
+          spotlightLinkLabel={spotlightLinkLabel}
+        />
+      </main>
+      <Footer>{footer}</Footer>
+    </Screen>
+  </>
+)
diff --git a/storybook/src/pages/amsterdam/article/ArticleBody.tsx b/storybook/src/pages/amsterdam/article/ArticleBody.tsx
new file mode 100644
index 0000000000..7b0b6d74de
--- /dev/null
+++ b/storybook/src/pages/amsterdam/article/ArticleBody.tsx
@@ -0,0 +1,116 @@
+import {
+  Column,
+  Grid,
+  Heading,
+  Link,
+  LinkList,
+  Paragraph,
+  Spotlight,
+  UnorderedList,
+} from '@amsterdam/design-system-react'
+import type { ArticleProps } from './Article'
+
+type ArticleBodyProps = Pick<ArticleProps, 'lead' | 'paragraph1' | 'spotlightHeading' | 'spotlightLinkLabel'>
+
+export const ArticleBody = ({ lead, paragraph1, spotlightHeading, spotlightLinkLabel }: ArticleBodyProps) => (
+  <>
+    <Grid paddingVertical="medium">
+      <Grid.Cell span={{ narrow: 4, medium: 8, wide: 10 }} start={{ narrow: 1, medium: 1, wide: 2 }}>
+        <Paragraph className="ams-mb--md" size="large">
+          {lead}
+        </Paragraph>
+        <Paragraph>{paragraph1}</Paragraph>
+      </Grid.Cell>
+    </Grid>
+    <Spotlight as="section" color="purple">
+      <Grid paddingTop="medium" paddingBottom="large">
+        <Grid.Cell span={{ narrow: 4, medium: 6, wide: 8 }} start={{ narrow: 1, medium: 2, wide: 3 }}>
+          <Column gap="small">
+            <Heading inverseColor level={2}>
+              {spotlightHeading}
+            </Heading>
+            <UnorderedList inverseColor>
+              <UnorderedList.Item>
+                Vraag uw paspoort of ID-kaart aan bij een Stadsloket in Amsterdam.
+              </UnorderedList.Item>
+              <UnorderedList.Item>
+                U kunt elke dag langskomen van 9.00 uur tot 17.00 uur en op donderdag tot 20.00 uur.
+              </UnorderedList.Item>
+              <UnorderedList.Item>Op amsterdam.nl/paspoort staat wat u mee moet nemen.</UnorderedList.Item>
+              <UnorderedList.Item>
+                Laat aan het loket bij uw aanvraag weten dat u kiest voor gratis bezorgen.
+              </UnorderedList.Item>
+              <UnorderedList.Item>
+                Als uw paspoort of ID-kaart klaar is, krijgt u een e-mail en sms-bericht met inloggegevens. Met deze
+                inloggegevens kunt u zelf inplannen wanneer u uw reisdocument bezorgd wilt hebben.
+              </UnorderedList.Item>
+            </UnorderedList>
+            <Paragraph inverseColor>
+              <Link href="https://amsterdam.nl/paspoort/" onBackground="dark">
+                {spotlightLinkLabel}
+              </Link>
+            </Paragraph>
+          </Column>
+        </Grid.Cell>
+      </Grid>
+    </Spotlight>
+    <Grid paddingVertical="medium">
+      <Grid.Cell span={{ narrow: 4, medium: 8, wide: 10 }} start={{ narrow: 1, medium: 1, wide: 2 }}>
+        <Column>
+          <section>
+            <Heading className="ams-mb--xs" level={2}>
+              Wanneer bezorgen we
+            </Heading>
+            <Paragraph>
+              We bezorgen op werkdagen en zaterdag tussen 8.00 en 18.00 uur. De ene week bezorgen wij op dinsdag en
+              donderdag ook tot 21.00 uur en de andere week op woensdag tot 21.00 uur.
+            </Paragraph>
+          </section>
+          <section>
+            <Heading className="ams-mb--xs" level={2}>
+              Tekenen voor ontvangst
+            </Heading>
+            <Paragraph>
+              Zorg dat u thuis bent om uw paspoort of ID-kaart te ontvangen. Bij bezorging voor meerdere personen moeten
+              alle personen aanwezig zijn. Ook kinderen vanaf 12 jaar moeten tekenen voor ontvangst. Tot 12 jaar tekent
+              de ouder of wettelijk vertegenwoordiger van het kind.
+            </Paragraph>
+          </section>
+          <section>
+            <Heading className="ams-mb--xs" level={2}>
+              Bezorgen met waarde-transport
+            </Heading>
+            <Paragraph>
+              De gemeente laat uw paspoort of ID-kaart bezorgen met een waarde-transport. Op{' '}
+              <Link href="https://mijnafspraak.nl/">mijnafspraak.nl</Link> ziet u wie er langskomt. De pasfoto van de
+              medewerker is vanaf 8.00 uur zichtbaar. De bezorger controleert bij aankomst uw identiteit en geeft u het
+              nieuwe reisdocument. U geeft uw oude reisdocument aan de bezorger. De bezorger maakt uw oude reisdocument
+              ongeldig waar u bij bent. Daarna mag u het zelf houden of meegeven aan de bezorger, die het vernietigt.
+            </Paragraph>
+          </section>
+          <section>
+            <Heading className="ams-mb--xs" level={2}>
+              Wanneer kan bezorgen niet?
+            </Heading>
+            <UnorderedList>
+              <UnorderedList.Item>Bij een spoedaanvraag.</UnorderedList.Item>
+              <UnorderedList.Item>
+                Als u een geldig visum in uw paspoort hebt dat u nog wilt gebruiken.
+              </UnorderedList.Item>
+              <UnorderedList.Item>Als u het oude reisdocument kwijt bent.</UnorderedList.Item>
+              <UnorderedList.Item>Als u op een van de Waddeneilanden woont. Daar bezorgen we niet.</UnorderedList.Item>
+            </UnorderedList>
+          </section>
+          <section>
+            <Heading className="ams-mb--xs" level={2}>
+              Meer weten
+            </Heading>
+            <LinkList>
+              <LinkList.Link href="https://amsterdam.nl/paspoort/">amsterdam.nl/paspoort</LinkList.Link>
+            </LinkList>
+          </section>
+        </Column>
+      </Grid.Cell>
+    </Grid>
+  </>
+)
diff --git a/storybook/src/pages/amsterdam/article/ArticleBreadcrumb.tsx b/storybook/src/pages/amsterdam/article/ArticleBreadcrumb.tsx
new file mode 100644
index 0000000000..fb8141e6bf
--- /dev/null
+++ b/storybook/src/pages/amsterdam/article/ArticleBreadcrumb.tsx
@@ -0,0 +1,12 @@
+import { Breadcrumb, Grid } from '@amsterdam/design-system-react'
+
+export const ArticleBreadcrumb = () => (
+  <Grid paddingTop="small">
+    <Grid.Cell span={{ narrow: 4, medium: 8, wide: 10 }} start={{ narrow: 1, medium: 1, wide: 2 }}>
+      <Breadcrumb>
+        <Breadcrumb.Link href="#">Home</Breadcrumb.Link>
+        <Breadcrumb.Link href="#">Nieuws</Breadcrumb.Link>
+      </Breadcrumb>
+    </Grid.Cell>
+  </Grid>
+)
diff --git a/storybook/src/pages/amsterdam/article/ArticleHeader.tsx b/storybook/src/pages/amsterdam/article/ArticleHeader.tsx
new file mode 100644
index 0000000000..71ffb380bb
--- /dev/null
+++ b/storybook/src/pages/amsterdam/article/ArticleHeader.tsx
@@ -0,0 +1,20 @@
+import { AspectRatio, Grid, Heading, Image, Overlap, Paragraph } from '@amsterdam/design-system-react'
+import type { ArticleProps } from './Article'
+
+type ArticleHeaderProps = Pick<ArticleProps, 'heading' | 'imageSrc'>
+
+export const ArticleHeader = ({ heading, imageSrc }: ArticleHeaderProps) => (
+  <header>
+    <Grid paddingBottom="medium">
+      <Grid.Cell span={{ narrow: 4, medium: 8, wide: 10 }} start={{ narrow: 1, medium: 1, wide: 2 }}>
+        <Heading className="ams-mb--sm">{heading}</Heading>
+        <Paragraph size="small">7 juni 2024</Paragraph>
+      </Grid.Cell>
+    </Grid>
+    <Overlap>
+      <AspectRatio ratio="2x-wide">
+        <Image alt="" loading="lazy" src={imageSrc} />
+      </AspectRatio>
+    </Overlap>
+  </header>
+)
diff --git a/storybook/src/pages/amsterdam/common/AppHeader.tsx b/storybook/src/pages/amsterdam/common/AppHeader.tsx
new file mode 100644
index 0000000000..67d990ee09
--- /dev/null
+++ b/storybook/src/pages/amsterdam/common/AppHeader.tsx
@@ -0,0 +1,13 @@
+import { Grid, Header, PageMenu } from '@amsterdam/design-system-react'
+import { Alignment as PageMenuStory } from '../../../components/PageMenu/PageMenu.stories'
+
+export const AppHeader = () => (
+  <Grid>
+    <Grid.Cell span="all">
+      <Header
+        links={<PageMenu alignEnd>{PageMenuStory.args?.children}</PageMenu>}
+        menu={<button className="ams-header__menu-button">Menu</button>}
+      />
+    </Grid.Cell>
+  </Grid>
+)
diff --git a/storybook/src/pages/amsterdam/home/Home.docs.mdx b/storybook/src/pages/amsterdam/home/Home.docs.mdx
new file mode 100644
index 0000000000..9e031266d3
--- /dev/null
+++ b/storybook/src/pages/amsterdam/home/Home.docs.mdx
@@ -0,0 +1,46 @@
+{/* @license CC0-1.0 */}
+
+import { Meta } from "@storybook/blocks";
+import * as HomeStories from "./Home.stories.tsx";
+
+<Meta of={HomeStories} />
+
+# Home Page
+
+## Layout
+
+A typical layout for a homepage:
+
+```tsx
+<SkipLink href="#main">Direct naar inhoud</SkipLink>
+<Screen maxWidth="wide">
+  <Grid>
+    <Header />
+  </Grid>
+  <main id="main">
+    <Overlap>
+      <Search />
+    </Overlap>
+    <Grid>
+      <AppComponent1 />
+      <AppComponent2 />
+      <AppComponent3 />
+    </Grid>
+  </main>
+  <Footer>
+    <Grid />
+  </Footer>
+</Screen>
+```
+
+1. The Skip Link prevents users from having to pass all preceding navigation links.
+2. The Screen component sets a maximum width for the entire page.
+3. The Grid divides the available width into 4, 8, or 12 columns.
+4. The Header shows the logo and menus for the application.
+5. The main element wraps everything between Header and Footer.
+   It carries an id for the skip link to target.
+6. An Overlap stacks a Search Field on a background Image.
+   It is as wide as the Grid, hence it is a sibling of it.
+7. Other components in the main area are laid out on a Grid again.
+8. The Footer contains its own Grid.
+   This allows its background colour to stretch to the Screen’s width.
diff --git a/storybook/src/pages/amsterdam/home/Home.stories.tsx b/storybook/src/pages/amsterdam/home/Home.stories.tsx
new file mode 100644
index 0000000000..547ac65d83
--- /dev/null
+++ b/storybook/src/pages/amsterdam/home/Home.stories.tsx
@@ -0,0 +1,30 @@
+/**
+ * @license EUPL-1.2+
+ * Copyright Gemeente Amsterdam
+ */
+
+import type { FooterProps } from '@amsterdam/design-system-react'
+import { Meta, StoryObj } from '@storybook/react'
+import type { ReactElement } from 'react'
+import { Home } from './Home'
+import * as FooterStories from '../../../components/Footer/Footer.stories'
+
+const meta = {
+  title: 'Pages/Amsterdam.nl/Home',
+  component: Home,
+  args: {
+    footer: FooterStories.Default.args?.children as ReactElement<FooterProps>,
+  },
+  argTypes: {
+    footer: {
+      table: { disable: true },
+    },
+  },
+  parameters: {
+    layout: 'fullscreen',
+  },
+} satisfies Meta<typeof Home>
+
+export default meta
+
+export const Default: StoryObj = {}
diff --git a/storybook/src/pages/amsterdam/home/Home.tsx b/storybook/src/pages/amsterdam/home/Home.tsx
new file mode 100644
index 0000000000..5117b262ac
--- /dev/null
+++ b/storybook/src/pages/amsterdam/home/Home.tsx
@@ -0,0 +1,29 @@
+import { Footer, Overlap, Screen, SkipLink } from '@amsterdam/design-system-react'
+import type { FooterProps } from '@amsterdam/design-system-react'
+import { ReactElement } from 'react'
+import { HomeNews } from './HomeNews'
+import { HomeSpotlight } from './HomeSpotlight'
+import { HomeTopTasks } from './HomeTopTasks'
+import { Default as OverlapStory } from '../../../components/Overlap/Overlap.stories'
+import SkipLinkStoryMeta from '../../../components/SkipLink/SkipLink.stories'
+import { AppHeader } from '../common/AppHeader'
+
+type HomeProps = {
+  footer: ReactElement<FooterProps>
+}
+
+export const Home = ({ footer }: HomeProps) => (
+  <>
+    <SkipLink href="#main">{SkipLinkStoryMeta.args.children}</SkipLink>
+    <Screen maxWidth="wide">
+      <AppHeader />
+      <main id="main">
+        <Overlap>{OverlapStory.args?.children}</Overlap>
+        <HomeTopTasks />
+        <HomeSpotlight />
+        <HomeNews />
+      </main>
+      <Footer>{footer}</Footer>
+    </Screen>
+  </>
+)
diff --git a/storybook/src/pages/amsterdam/home/HomeNews.tsx b/storybook/src/pages/amsterdam/home/HomeNews.tsx
new file mode 100644
index 0000000000..6fcdfc09f6
--- /dev/null
+++ b/storybook/src/pages/amsterdam/home/HomeNews.tsx
@@ -0,0 +1,45 @@
+import { AspectRatio, Card, Grid, Heading, Image } from '@amsterdam/design-system-react'
+
+export const HomeNews = () => (
+  <Grid paddingVertical="medium">
+    <Grid.Cell span="all">
+      <Heading level={2}>Nieuws</Heading>
+    </Grid.Cell>
+    <Grid.Cell span={4}>
+      <Card>
+        <AspectRatio ratio="x-wide">
+          <Image alt="" src="https://picsum.photos/640/360?random=1" />
+        </AspectRatio>
+        <Card.HeadingGroup tagline="Nieuws">
+          <Heading level={2} size="level-4">
+            <Card.Link href="#">Nederlands eerste houten woonwijk komt in Zuidoost</Card.Link>
+          </Heading>
+        </Card.HeadingGroup>
+      </Card>
+    </Grid.Cell>
+    <Grid.Cell span={4}>
+      <Card>
+        <AspectRatio ratio="x-wide">
+          <Image alt="" src="https://picsum.photos/640/360?random=2" />
+        </AspectRatio>
+        <Card.HeadingGroup tagline="Nieuws">
+          <Heading level={2} size="level-4">
+            <Card.Link href="#">Gratis openbaar vervoer voor kinderen</Card.Link>
+          </Heading>
+        </Card.HeadingGroup>
+      </Card>
+    </Grid.Cell>
+    <Grid.Cell span={4}>
+      <Card>
+        <AspectRatio ratio="x-wide">
+          <Image alt="" src="https://picsum.photos/640/360?random=3" />
+        </AspectRatio>
+        <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>
+          </Heading>
+        </Card.HeadingGroup>
+      </Card>
+    </Grid.Cell>
+  </Grid>
+)
diff --git a/storybook/src/pages/amsterdam/home/HomeSpotlight.tsx b/storybook/src/pages/amsterdam/home/HomeSpotlight.tsx
new file mode 100644
index 0000000000..8e21124e4d
--- /dev/null
+++ b/storybook/src/pages/amsterdam/home/HomeSpotlight.tsx
@@ -0,0 +1,32 @@
+import { Grid, Heading, Link, Paragraph, Spotlight } from '@amsterdam/design-system-react'
+
+export const HomeSpotlight = () => (
+  <Spotlight color="purple">
+    <Grid paddingVertical="medium">
+      <Grid.Cell span={{ narrow: 4, medium: 4, wide: 6 }}>
+        <Heading className="ams-mb--xs" inverseColor size="level-2">
+          Ontheffing of vergunning
+        </Heading>
+        <Paragraph className="ams-mb--sm" inverseColor>
+          Check welke ontheffing of vergunning u nodig heeft. Bijvoorbeeld een RVV, TVM, objectvergunning,{' '}
+          nachtwerkontheffing, e-RVV, e-TVM of filmmelding. Dat regult u allemaal met 1 formulier.
+        </Paragraph>
+        <Link href="#" onBackground="dark" variant="standalone">
+          Eenvoudig regelen
+        </Link>
+      </Grid.Cell>
+      <Grid.Cell span={{ narrow: 4, medium: 4, wide: 6 }}>
+        <Heading className="ams-mb--xs" inverseColor size="level-2">
+          Werkzaamheden
+        </Heading>
+        <Paragraph className="ams-mb--sm" inverseColor>
+          Lees waar en wanneer we werken aan nieuwbouw, groot onderhoud, herinrichting van straten en wegen, aanpak van
+          parken of ontwikkeling van hele gebieden.
+        </Paragraph>
+        <Link href="#" onBackground="dark" variant="standalone">
+          Alle bouw- en verkeerswerkzaamheden
+        </Link>
+      </Grid.Cell>
+    </Grid>
+  </Spotlight>
+)
diff --git a/storybook/src/pages/amsterdam/home/HomeTopTasks.tsx b/storybook/src/pages/amsterdam/home/HomeTopTasks.tsx
new file mode 100644
index 0000000000..fcd43eb8ad
--- /dev/null
+++ b/storybook/src/pages/amsterdam/home/HomeTopTasks.tsx
@@ -0,0 +1,84 @@
+import { Card, Grid, Heading, Paragraph } from '@amsterdam/design-system-react'
+
+export const HomeTopTasks = () => (
+  <Grid paddingVertical="medium">
+    <Grid.Cell span="all">
+      <Heading>Belangrijkste onderwerpen</Heading>
+    </Grid.Cell>
+    <Grid.Cell span={{ narrow: 4, medium: 4, wide: 3 }}>
+      <Card>
+        <Heading level={2} size="level-4">
+          <Card.Link href="#">Gemeentebelastingen</Card.Link>
+        </Heading>
+        <Paragraph size="small">
+          Bekijk welke belastingen en heffingen er zijn, hoe u bezwaar maakt of een betalingsregeling treft.
+        </Paragraph>
+      </Card>
+    </Grid.Cell>
+    <Grid.Cell span={{ narrow: 4, medium: 4, wide: 3 }}>
+      <Card>
+        <Heading level={3} size="level-4">
+          <Card.Link href="#">Parkeren + Reizen (P+R)</Card.Link>
+        </Heading>
+        <Paragraph size="small">
+          U kunt met uw auto goedkoop parkeren bij een P+R-locatie aan de rand van de stad.
+        </Paragraph>
+      </Card>
+    </Grid.Cell>
+    <Grid.Cell span={{ narrow: 4, medium: 4, wide: 3 }}>
+      <Card>
+        <Heading level={3} size="level-4">
+          <Card.Link href="#">Paspoort, ID-kaart en rijbewijs</Card.Link>
+        </Heading>
+        <Paragraph size="small">Vraag deze bewijzen aan of verleng ze. Geef een vermissing aan.</Paragraph>
+      </Card>
+    </Grid.Cell>
+    <Grid.Cell span={{ narrow: 4, medium: 4, wide: 3 }}>
+      <Card>
+        <Heading level={3} size="level-4">
+          <Card.Link href="#">Onderwijs</Card.Link>
+        </Heading>
+        <Paragraph size="small">
+          Meld een kind aan voor basisschool, middelbare school of kinderopvang. Bekijk het kindtegoed op uw Stadspas.
+        </Paragraph>
+      </Card>
+    </Grid.Cell>
+    <Grid.Cell span={{ narrow: 4, medium: 4, wide: 3 }}>
+      <Card>
+        <Heading level={3} size="level-4">
+          <Card.Link href="#">Meldingen openbare ruimte en overlast</Card.Link>
+        </Heading>
+        <Paragraph size="small">
+          Ziet u op straat of in een park iets waarvan u wilt dat het gemaakt of opgeruimd wordt, dan kunt u dat bij de
+          gemeente melden.
+        </Paragraph>
+      </Card>
+    </Grid.Cell>
+    <Grid.Cell span={{ narrow: 4, medium: 4, wide: 3 }}>
+      <Card>
+        <Heading level={3} size="level-4">
+          <Card.Link href="#">Verhuizing doorgeven</Card.Link>
+        </Heading>
+        <Paragraph size="small">Geef uw nieuwe adres door als u binnen Amsterdam of naar Amsterdam verhuist.</Paragraph>
+      </Card>
+    </Grid.Cell>
+    <Grid.Cell span={{ narrow: 4, medium: 4, wide: 3 }}>
+      <Card>
+        <Heading level={3} size="level-4">
+          <Card.Link href="#">Grof afval</Card.Link>
+        </Heading>
+        <Paragraph size="small">Grof afval zijn spullen die niet in een vuilniszak passen.</Paragraph>
+      </Card>
+    </Grid.Cell>
+    <Grid.Cell span={{ narrow: 4, medium: 4, wide: 3 }}>
+      <Card>
+        <Heading level={3} size="level-4">
+          <Card.Link href="#">Kennisgevingen en bekendmakingen</Card.Link>
+        </Heading>
+        <Paragraph size="small">
+          Kennisgevingen en bekendmakingen van de gemeente Amsterdam van de laatste 8 weken.
+        </Paragraph>
+      </Card>
+    </Grid.Cell>
+  </Grid>
+)

From dc1e5d5d0e1f7a1f9baa29581de11a3400d4d9da Mon Sep 17 00:00:00 2001
From: Vincent Smedinga <v.smedinga@amsterdam.nl>
Date: Fri, 21 Jun 2024 14:17:48 +0200
Subject: [PATCH 3/3] feat: Allow various types of text input (#1259)

Co-authored-by: Ruben Sibon <r.sibon@amsterdam.nl>
Co-authored-by: Aram <37216945+alimpens@users.noreply.github.com>
---
 .../css/src/components/text-input/README.md   |   4 +-
 .../react/src/DateInput/DateInput.test.tsx    |  14 ++-
 packages/react/src/DateInput/DateInput.tsx    |   6 +-
 .../react/src/TextInput/TextInput.test.tsx    |  31 ++++-
 packages/react/src/TextInput/TextInput.tsx    |  10 +-
 .../components/TextInput/TextInput.docs.mdx   | 118 ++++++++++++++++++
 .../TextInput/TextInput.stories.tsx           |  34 ++++-
 7 files changed, 208 insertions(+), 9 deletions(-)

diff --git a/packages/css/src/components/text-input/README.md b/packages/css/src/components/text-input/README.md
index 3b4dd57757..dd52c5c0ad 100644
--- a/packages/css/src/components/text-input/README.md
+++ b/packages/css/src/components/text-input/README.md
@@ -9,8 +9,8 @@ A form field in which a user can enter text.
 - Use a Text Input when users need to enter a single line of text, such as their name or phone number.
 - Do not use a Text Input when users could provide more than 1 sentence of text.
 - The width of the Text Input should be appropriate for the information to be entered.
-- A Text Input must have a label, and in most cases, this label should be visible.
+- A Text Input must have a Label, and in most cases, this label should be visible.
 - Use `spellcheck="false"` for fields that may contain sensitive information, such as passwords and personal data.
   Some browser extensions for spell-checking send this information to external servers.
 - Apply automatic assistance where possible.
-  For example, in logged-in systems, pre-filling input can prevent errors and save time.
+  For example, in logged-in systems, pre-filling known values can prevent errors and save time.
diff --git a/packages/react/src/DateInput/DateInput.test.tsx b/packages/react/src/DateInput/DateInput.test.tsx
index 5c34f43fdc..b15eadfd7b 100644
--- a/packages/react/src/DateInput/DateInput.test.tsx
+++ b/packages/react/src/DateInput/DateInput.test.tsx
@@ -1,6 +1,6 @@
 import { render } from '@testing-library/react'
 import { createRef } from 'react'
-import { DateInput } from './DateInput'
+import { DateInput, dateInputTypes } from './DateInput'
 import '@testing-library/jest-dom'
 
 describe('Date input', () => {
@@ -65,4 +65,16 @@ describe('Date input', () => {
       expect(component).not.toHaveAttribute('aria-invalid')
     })
   })
+
+  describe('Type', () => {
+    dateInputTypes.map((type) =>
+      it(`sets the ‘${type}’ type`, () => {
+        const { container } = render(<DateInput type={type} />)
+
+        const component = container.querySelector(':only-child')
+
+        expect(component).toHaveAttribute('type', type)
+      }),
+    )
+  })
 })
diff --git a/packages/react/src/DateInput/DateInput.tsx b/packages/react/src/DateInput/DateInput.tsx
index b32b90892a..d91974af6a 100644
--- a/packages/react/src/DateInput/DateInput.tsx
+++ b/packages/react/src/DateInput/DateInput.tsx
@@ -7,11 +7,15 @@ import clsx from 'clsx'
 import { forwardRef } from 'react'
 import type { ForwardedRef, InputHTMLAttributes } from 'react'
 
+export const dateInputTypes = ['date', 'datetime-local'] as const
+
+type DateInputType = (typeof dateInputTypes)[number]
+
 export type DateInputProps = {
   /** Whether the value fails a validation rule. */
   invalid?: boolean
   /** The kind of data that the user should provide. */
-  type?: 'date' | 'datetime-local'
+  type?: DateInputType
 } & Omit<InputHTMLAttributes<HTMLInputElement>, 'aria-invalid' | 'type'>
 
 export const DateInput = forwardRef(
diff --git a/packages/react/src/TextInput/TextInput.test.tsx b/packages/react/src/TextInput/TextInput.test.tsx
index 3196b8a210..f0b2f38e72 100644
--- a/packages/react/src/TextInput/TextInput.test.tsx
+++ b/packages/react/src/TextInput/TextInput.test.tsx
@@ -1,7 +1,8 @@
 import { render, screen } from '@testing-library/react'
 import userEvent from '@testing-library/user-event'
 import { createRef, useState } from 'react'
-import { TextInput } from './TextInput'
+import { TextInput, textInputTypes } from './TextInput'
+import { Label } from '../Label'
 import '@testing-library/jest-dom'
 
 describe('Text input', () => {
@@ -116,4 +117,32 @@ describe('Text input', () => {
       expect(component).not.toHaveAttribute('aria-invalid')
     })
   })
+
+  describe('Type', () => {
+    textInputTypes
+      .filter((type) => type !== 'password')
+      .map((type) =>
+        it(`sets the ‘${type}’ type`, () => {
+          render(<TextInput type={type} />)
+
+          const component = screen.getByRole('textbox')
+
+          expect(component).toHaveAttribute('type', type)
+        }),
+      )
+
+    // https://github.com/testing-library/dom-testing-library/issues/567
+    it('sets the ‘password’ type', () => {
+      render(
+        <>
+          <Label htmlFor="password-field">Password</Label>
+          <TextInput id="password-field" type="password" />
+        </>,
+      )
+
+      const component = screen.getByLabelText(/password/i)
+
+      expect(component).toHaveAttribute('type', 'password')
+    })
+  })
 })
diff --git a/packages/react/src/TextInput/TextInput.tsx b/packages/react/src/TextInput/TextInput.tsx
index 89e3670b8d..f224294336 100644
--- a/packages/react/src/TextInput/TextInput.tsx
+++ b/packages/react/src/TextInput/TextInput.tsx
@@ -7,20 +7,26 @@ import clsx from 'clsx'
 import { forwardRef } from 'react'
 import type { ForwardedRef, InputHTMLAttributes } from 'react'
 
+export const textInputTypes = ['email', 'password', 'tel', 'text', 'url'] as const
+
+type TextInputType = (typeof textInputTypes)[number]
+
 export type TextInputProps = {
   /** Whether the value fails a validation rule. */
   invalid?: boolean
+  /** The kind of data that the user should provide. */
+  type?: TextInputType
 } & Omit<InputHTMLAttributes<HTMLInputElement>, 'aria-invalid'>
 
 export const TextInput = forwardRef(
-  ({ className, dir, invalid, ...restProps }: TextInputProps, ref: ForwardedRef<HTMLInputElement>) => (
+  ({ className, dir, invalid, type = 'text', ...restProps }: TextInputProps, ref: ForwardedRef<HTMLInputElement>) => (
     <input
       {...restProps}
       aria-invalid={invalid || undefined}
       className={clsx('ams-text-input', className)}
       dir={dir ?? 'auto'}
       ref={ref}
-      type="text"
+      type={type}
     />
   ),
 )
diff --git a/storybook/src/components/TextInput/TextInput.docs.mdx b/storybook/src/components/TextInput/TextInput.docs.mdx
index c256c274c1..8850274411 100644
--- a/storybook/src/components/TextInput/TextInput.docs.mdx
+++ b/storybook/src/components/TextInput/TextInput.docs.mdx
@@ -14,14 +14,132 @@ import README from "../../../../packages/css/src/components/text-input/README.md
 
 ## Examples
 
+### Type: Password
+
+Creates an input where the user can enter a password.
+The characters entered are hidden, usually represented by dots or asterisks, so that the actual text is not visible.
+
+Use the password type when the input requires sensitive information, like passwords or PINs.
+It ensures that the input is not readable by others who might be looking at the screen.
+
+Consider setting the following attributes:
+
+1. Allow the user’s password manager to automatically fill the password through `autocomplete="current-password"`.
+   When asking for a new password, use `autocomplete="new-password"` instead.
+2. Add a `minlength` attribute to ensure passwords meet a minimum length requirement.
+   Do not add a `maxlength` attribute.
+3. Use the `pattern` attribute to enforce password policies, like including numbers and special characters.
+   Describe these policies in the [Field](?path=/docs/components-forms-field--docs)’s description as well.
+4. If the password is a numeric PIN, add `inputmode="numeric"`.
+   Devices with virtual keyboards then switch to a numeric keypad layout which makes entering the password easier.
+5. Set `autocapitalize="none"`, `autocorrect="off"` and `spellcheck="false"` to stop browsers automatically changing user input.
+   Passwords shouldn’t be checked for spelling or grammar.
+   This may also prevent posting the password to third-party plugins.
+
+Follow the [guidelines for asking for passwords](https://design-system.service.gov.uk/patterns/passwords/) of the GOV.UK Design System.
+
+<Canvas of={TextInputStories.Password} />
+
+### Type: Email address
+
+This field helps the user enter an email address.
+It has built-in validation to check for a valid email format.
+However, do not rely only on the browser’s validation.
+
+The `email` input field looks like a standard text input.
+On some devices, it may show an email-specific keyboard.
+
+Consider setting the following attributes:
+
+1. Set `autocomplete="email"` to help browsers autofill the user’s email address.
+2. Set `autocapitalize="none"`, `autocorrect="off"` and `spellcheck="false"` to stop browsers automatically changing user input.
+   Email addresses shouldn’t be checked for spelling or grammar.
+   This may also prevent posting the email address to third-party plugins.
+
+Follow the [guidelines for asking for email addresses](https://design-system.service.gov.uk/patterns/email-addresses/) of the GOV.UK Design System.
+
+<Canvas of={TextInputStories.EmailAddress} />
+
+### Type: Web address
+
+This field helps the user enter a web address or URL.
+It has built-in validation to check for a valid format.
+However, do not rely only on the browser’s validation.
+
+The `url` input field looks like a standard text input.
+On some devices, it may show a URL-specific keyboard to aid in entering web addresses.
+
+Consider setting the following attributes:
+
+1. Set `autocomplete="url"` to help browsers autofill the user’s web address.
+2. Set `autocapitalize="none"`, `autocorrect="off"` and `spellcheck="false"` to stop browsers automatically changing user input.
+   Email addresses shouldn’t be checked for spelling or grammar.
+   This may also prevent posting the web address to third-party plugins.
+
+<Canvas of={TextInputStories.WebAddress} />
+
+### Type: Phone number
+
+This field helps the user enter a phone number.
+It has built-in validation to check for a valid format.
+However, do not rely only on the browser’s validation.
+
+The `tel` input field looks like a standard text input.
+On mobile devices, it may display a numeric keypad or a keyboard optimized for entering phone numbers.
+
+Guidelines:
+
+1. Set `autocomplete="tel"` to help browsers autofill the user’s phone number.
+
+Follow the [guidelines for asking for telephone numbers](https://design-system.service.gov.uk/patterns/telephone-numbers/) of the GOV.UK Design System.
+
+<Canvas of={TextInputStories.PhoneNumber} />
+
 ### Placeholder
 
+This text appears in the field when it is empty. It can give a brief hint about the kind of data to enter.
+
+Don’t try too hard to find a suitable text for a placeholder.
+Inputs without placeholder text are just fine – the label and a description should be clear enough.
+Do not use a placeholder instead of a [Label](?path=/docs/components-forms-label--docs).
+
+Follow the [guidelines for placeholder text](https://www.nldesignsystem.nl/richtlijnen/formulieren/placeholders) by NL Design System.
+
 <Canvas of={TextInputStories.Placeholder} />
 
 ### Invalid
 
+Indicates that the input value does not meet the specified constraints.
+An [Error Message](?path=/docs/components-forms-error-message--docs) must be displayed above the field.
+To highlight the error even more, the parent [Field](?path=/docs/components-forms-field--docs) component’s `invalid` prop must also be set.
+
 <Canvas of={TextInputStories.Invalid} />
 
 ### Disabled
 
+A field that can not (yet) be used is indicated with a grey border.
+It will not respond to interactions, e.g. with the mouse or keyboard.
+
+Avoid disabling input fields.
+They cause usability and accessibility problems.
+
+Disabled fields are often skipped by screen readers.
+This makes it hard for the user who rely on assistive technologies to understand the form’s content.
+They are not included in form submissions, which can lead to incomplete or missing data.
+
+Alternatives:
+
+1. Use the `readonly` attribute.
+   This makes a field uneditable but keeps it accessible and included in form submissions.
+2. Display data as plain text or within a non-input element like a `span` or `div`.
+3. Use conditional logic to hide or show fields based on user interaction.
+   This ensures all necessary fields are accessible and editable when needed.
+4. Use a label or text to explain why a field is not editable if you must disable it temporarily.
+   This helps the user understand the context.
+
 <Canvas of={TextInputStories.Disabled} />
+
+## Further reading
+
+- Extensive [guidelines for all types of input](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/text) on Mozilla Developer Network.
+- An overview of [suitable metadata for various kinds of content](https://nl-design-system.github.io/utrecht/storybook/?path=/docs/react_react-textbox--docs) to be entered by Gemeente Utrecht.
diff --git a/storybook/src/components/TextInput/TextInput.stories.tsx b/storybook/src/components/TextInput/TextInput.stories.tsx
index a21c14446a..80b12798c5 100644
--- a/storybook/src/components/TextInput/TextInput.stories.tsx
+++ b/storybook/src/components/TextInput/TextInput.stories.tsx
@@ -12,7 +12,6 @@ const meta = {
   args: {
     disabled: false,
     invalid: false,
-    value: '',
   },
   argTypes: {
     disabled: {
@@ -33,20 +32,51 @@ type Story = StoryObj<typeof meta>
 
 export const Default: Story = {}
 
+export const Password: Story = {
+  args: {
+    minLength: 8,
+    type: 'password',
+    value: 'password',
+  },
+}
+
+export const EmailAddress: Story = {
+  args: {
+    type: 'email',
+    value: 'designsystem@amsterdam.nl',
+  },
+}
+
+export const WebAddress: Story = {
+  args: {
+    type: 'url',
+    value: 'https://designsystem.amsterdam/',
+  },
+}
+
+export const PhoneNumber: Story = {
+  args: {
+    type: 'tel',
+    value: '14020',
+  },
+}
+
 export const Placeholder: Story = {
   args: {
-    placeholder: 'E-mail',
+    placeholder: 'Placeholder text',
   },
 }
 
 export const Invalid: Story = {
   args: {
     invalid: true,
+    value: 'Invalid value',
   },
 }
 
 export const Disabled: Story = {
   args: {
     disabled: true,
+    value: 'Disabled input',
   },
 }