Improve card docs

packages/css/src/components/card/README.md

@@ -1,12 +1,25 @@
 # Card
 
-Gebruik een card op een overzichtspagina om te verwijzen naar een detailpagina, zoals een nieuwsbericht, een vacature of een zoekresultaat. De card bevat meestal de titel, introductie en afbeelding van de content. De link is verplicht.
+Gebruik een card op een overzichtspagina om te verwijzen naar een detailpagina,
+zoals een nieuwsbericht, een vacature of een zoekresultaat.
+De card bevat meestal de titel, introductie en afbeelding van de content.
+De link is verplicht.
 
-## Schermlezers
+## Richtlijnen
 
-Met een schermlezer kun je onder andere navigeren via headings en links in een document. De titel van een card is een link in een heading, zodat je van beide navigatiemanieren gebruik kunt maken. Een schermlezer leest eerst de titel op, daarna de rest van de inhoud.
+- De titel van een card is een link in een heading.
+  Hier gelden dezelfde richtlijnen voor als voor reguliere [links](?path=/docs/react_navigation-link--docs) en [headings](?path=/docs/react_text-heading--docs).
+  De link is actief op het hele gebied van de card.
+- Een card heeft meer inhoud nodig dan alleen een titel.
+  Vul dit aan met tekstuele en/of visuele inhoud.
+- De tekst zet je in een reguliere paragraaf.
+  Alleen voor een tagline of datum gebruik je de kleinste tekstgrootte.
+- Als de inhoud geen detailpagina vertegenwoordigt is dit component niet de beste optie.
+  Om te verwijzen naar een thematische pagina gebruik je een [top task link](?path=/docs/react_navigation-top-task-link--docs).
+  Ook kun je een [reguliere link](?path=/docs/react_navigation-link--docs) inzetten.
 
-## Richtlijnen
+## Schermlezers
 
-- De titel van een card is een link in een heading. Hier gelden dezelfde richtlijnen voor als voor reguliere [links](https://amsterdam.github.io/design-system/?path=/docs/react_navigation-link--docs) en [headings](https://amsterdam.github.io/design-system/?path=/docs/react_text-heading--docs).
-- Een card heeft meer inhoud nodig dan alleen een titel. Vul dit aan met tekstuele en/of visuele inhoud. Als dit lastig is, kijk dan of een [top task link](https://amsterdam.github.io/design-system/?path=/docs/react_navigation-top-task-link--docs) of [reguliere link](https://amsterdam.github.io/design-system/?path=/docs/react_navigation-link--docs) beter past.
+Met een schermlezer kun je onder andere navigeren via headings en links in een document.
+De titel van een card is een link in een heading, zodat je van beide navigatiemanieren gebruik kunt maken.
+Een schermlezer leest eerst de titel op, daarna de rest van de inhoud.

storybook/storybook-react/src/Card/Card.docs.mdx

@@ -10,16 +10,17 @@ import README from "../../../../packages/css/src/components/card/README.md?raw";
 
 <Controls />
 
-## Card with tagline
+## Met tagline
 
-Een card kan een _tagline_ hebben, tekst voor de titel.
-Om de volgorde voor schermlezers logisch te houden,
-wordt eerst de titel gedefinieerd, en dan de _tagline_. Visueel wordt dit omgedraaid door `Card.HeadingGroup`.
+Een card kan boven de titel een _tagline_ tonen, een korte term zoals een categorie of informatiesoort.
+Gebruik een `Card.HeadingGroup`.
+Dit zorgt er ook voor dat schermlezers eerst de titel voorlezen, dan de tagline.
 
-<Canvas of={CardStories.CardWithTagline} />
+<Canvas of={CardStories.WithTagline} />
 
-## Image card
+## Met afbeelding
 
-Een card kan ook een plaatje bevatten. Gebruik het Aspect Ratio component voor de juiste beeldverhoudingen.
+Een card toont vaak de afbeelding van de detailpagina.
+Gebruik [Aspect Ratio](?path=/docs/layout-aspect-ratio--docs) voor de juiste beeldverhouding.
 
-<Canvas of={CardStories.ImageCard} />
+<Canvas of={CardStories.WithImage} />

storybook/storybook-react/src/Card/Card.stories.tsx

@@ -6,9 +6,23 @@
 import { AspectRatio, Card, Heading, Image, Paragraph } from '@amsterdam/design-system-react'
 import { Meta, StoryObj } from '@storybook/react'
 
+const dateFormat = new Intl.DateTimeFormat('nl', {
+  day: 'numeric',
+  month: 'long',
+  year: 'numeric',
+})
+const today = dateFormat.format(Date.now())
+
 const meta = {
-  title: 'Containers/Card',
+  title: 'Navigation/Card',
   component: Card,
+  decorators: [
+    (Story) => (
+      <div style={{ maxWidth: '24rem' }}>
+        <Story />
+      </div>
+    ),
+  ],
 } satisfies Meta<typeof Card>
 
 export default meta
@@ -21,21 +35,14 @@ export const Default: Story = {
       <Heading size="level-4" key={1}>
         <Card.Link href="/">Monitor Attracties MRA</Card.Link>
       </Heading>,
-      <Paragraph key={2} size="small">
+      <Paragraph key={2}>
         Ontwikkeling van het aantal attracties en bezoekers in de metropoolregio Amsterdam.
       </Paragraph>,
     ],
   },
-  decorators: [
-    (Story) => (
-      <div style={{ maxWidth: '400px' }}>
-        <Story />
-      </div>
-    ),
-  ],
 }
 
-export const CardWithTagline: Story = {
+export const WithTagline: Story = {
   args: {
     children: [
       <Card.HeadingGroup key={1} tagline="Dossier">
@@ -46,14 +53,11 @@ export const CardWithTagline: Story = {
       <Paragraph key={2}>
         Ontwikkeling van het aantal attracties en bezoekers in de metropoolregio Amsterdam.
       </Paragraph>,
-      <Paragraph key={3} size="small">
-        Laatst gewijzigd: 28 september 2023
-      </Paragraph>,
     ],
   },
 }
 
-export const ImageCard: Story = {
+export const WithImage: Story = {
   args: {
     children: [
       <AspectRatio key={1} ratio="wide">
@@ -64,16 +68,12 @@ export const ImageCard: Story = {
           <Card.Link href="/">Monitor Attracties MRA</Card.Link>
         </Heading>
       </Card.HeadingGroup>,
-      <Paragraph key={3} size="small">
+      <Paragraph key={3}>
         Ontwikkeling van het aantal attracties en bezoekers in de metropoolregio Amsterdam.
       </Paragraph>,
+      <Paragraph key={4} size="small">
+        {today}
+      </Paragraph>,
     ],
   },
-  decorators: [
-    (Story) => (
-      <div style={{ maxWidth: '440px' }}>
-        <Story />
-      </div>
-    ),
-  ],
 }