Require description for top task link (#744)

* Require description for top task link * Improve documentation * Refer to link list if no descriptions * Update unit tests
Amsterdam · Nov 14, 2023 · b31fe24 · b31fe24
1 parent 98cd2f5
commit b31fe24
Show file tree

Hide file tree

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

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

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

diff --git a/storybook/storybook-react/src/TopTaskLink/TopTaskLink.docs.mdx b/storybook/storybook-react/src/TopTaskLink/TopTaskLink.docs.mdx
@@ -10,10 +10,9 @@ import README from "../../../../packages/css/src/top-task-link/README.md?raw";
 
 <Controls />
 
-### Without description
+### Meerdere links
 
-<Canvas of={TopTaskLinkStories.WithoutDescription} />
+Normaal gesproken zijn er meerdere toptaken.
+Deze links komen dan ook vaak voor in een grid:
 
-### With description
-
-<Canvas of={TopTaskLinkStories.WithDescription} />
+<Canvas of={TopTaskLinkStories.Multiple} />
diff --git a/storybook/storybook-react/src/TopTaskLink/TopTaskLink.stories.tsx b/storybook/storybook-react/src/TopTaskLink/TopTaskLink.stories.tsx
@@ -11,73 +11,54 @@ import '@amsterdam/design-system-css/src/top-task-link/top-task-link.scss'
 const meta = {
   title: 'Navigation/Top Task Link',
   component: TopTaskLink,
-  args: {
-    href: '/',
-  },
 } satisfies Meta<typeof TopTaskLink>
 
 export default meta
 
 type Story = StoryObj<typeof meta>
 
 export const Default: Story = {
-  decorators: [
-    (Story) => (
-      <Grid>
-        <Grid.Cell span={4}>
-          <Story />
-        </Grid.Cell>
-      </Grid>
-    ),
-  ],
   args: {
-    href: '/',
-    label: 'Titel',
-    description: 'Omschrijving',
-  },
-}
-
-export const WithoutDescription: Story = {
-  args: {
-    label: 'Titel',
-  },
-  render: () => (
-    <Grid>
-      <Grid.Cell span={4}>
-        <TopTaskLink href="/" label="Melding openbare ruimte en overlast" />
-      </Grid.Cell>
-      <Grid.Cell span={4}>
-        <TopTaskLink href="/" label="Verhuizing doorgeven" />
-      </Grid.Cell>
-      <Grid.Cell span={4}>
-        <TopTaskLink href="/" label="Kennisgevingen en bekendmakingen" />
-      </Grid.Cell>
-    </Grid>
-  ),
-  parameters: {
-    docs: {
-      source: { type: 'dynamic' },
-    },
+    description: 'Geef uw nieuwe adres door als u binnen Amsterdam of naar Amsterdam verhuist.',
+    href: '#',
+    label: 'Verhuizing doorgeven',
   },
 }
 
-export const WithDescription: Story = {
+export const Multiple: Story = {
   args: {
+    description: 'Omschrijving',
     label: 'Titel',
   },
   render: () => (
     <Grid>
       <Grid.Cell span={3}>
-        <TopTaskLink href="/" label="Stadsloket" description="Locaties en openingstijden" />
+        <TopTaskLink
+          description="Bekijk welke belastingen en heffingen er zijn, hoe u bezwaar maakt of een betalingsregeling treft."
+          href="#"
+          label="Gemeentebelastingen"
+        />
       </Grid.Cell>
       <Grid.Cell span={3}>
-        <TopTaskLink href="/" label="P+R" description="Parkeren en reizen" />
+        <TopTaskLink
+          description="U kunt met uw auto goedkoop parkeren bij een P+R-locatie aan de rand van de stad."
+          href="#"
+          label="Parkeren + Reizen (P+R)"
+        />
       </Grid.Cell>
       <Grid.Cell span={3}>
-        <TopTaskLink href="/" label="Documenten" description="Paspoort, ID-kaart en rijbewijs" />
+        <TopTaskLink
+          description="Vraag deze bewijzen aan of verleng ze. Geef een vermissing aan."
+          href="#"
+          label="Paspoort, ID-kaart en rijbewijs"
+        />
       </Grid.Cell>
       <Grid.Cell span={3}>
-        <TopTaskLink href="/" label="Meldingen" description="Melding openbare ruimte en overlast" />
+        <TopTaskLink
+          description="Meld een kind aan voor basisschool, middelbare school of kinderopvang. Bekijk het kindtegoed op uw Stadspas."
+          href="#"
+          label="Onderwijs"
+        />
       </Grid.Cell>
     </Grid>
   ),