feat!: Remove HeadingLevel type, group Heading sizes in story

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

@@ -2,15 +2,15 @@
 
 # Heading
 
-A heading conveys information about the content below it.
-Use headings to allow the user to grasp the structure of the page quickly.
+Communicates the organization of the content on a page.
 
 ## Guidelines
 
 - A heading describes the content beneath it.
-- Do not use a heading for formatting and styling. Use it to represent the page’s structure.
-- Use headings hierarchically, and do not skip heading levels.
-  So, an `h1` heading should be followed by an `h2`, not an `h3`.
+- Every page should contain one Heading with level 1.
+- Do not skip heading levels, e.g. a level 2 Heading should be followed by one with level 3, not level 4.
+- Do not use a Heading for formatting and styling, but to represent the page’s structure.
+  Users of screen readers use headings to navigate the page – an incorrect hierarchy can confuse them.
 
 ## Relevant WCAG Requirements
 

packages/react/documentation/coding-conventions.md

@@ -22,13 +22,13 @@ However, barrel files have 2 potential pitfalls:
 
 We can avoid this last pitfall by adhering to the following code convention: barrel file imports should only be used to import from a package, not within one.
 
-To illustrate: If the `Accordion` React component needs the `HeadingLevel` type from the `Heading` React component, it should import it like this:
+To illustrate: If the `Accordion` React component needs the `HeadingProps` type from the `Heading` React component, it should import it like this:
 
-`import { HeadingLevel } from '../Heading/Heading'`
+`import type { HeadingProps } from '../Heading/Heading'`
 
 Instead of this:
 
-`import { HeadingLevel } from '../Heading'` or `import { HeadingLevel } from '../'`
+`import type { HeadingProps } from '../Heading'` or `import type { HeadingProps } from '../'`
 
 ## Subcomponents
 

packages/react/src/Accordion/Accordion.tsx

@@ -8,12 +8,12 @@ import { forwardRef, useImperativeHandle, useRef } from 'react'
 import type { ForwardedRef, HTMLAttributes, PropsWithChildren } from 'react'
 import AccordionContext from './AccordionContext'
 import { AccordionSection } from './AccordionSection'
-import { HeadingLevel } from '../Heading/Heading'
+import type { HeadingProps } from '../Heading/Heading'
 import { useKeyboardFocus } from '../common/useKeyboardFocus'
 
 export type AccordionProps = {
   /** The hierarchical level of the Accordion Section heading(s) within the document. */
-  headingLevel: HeadingLevel
+  headingLevel: HeadingProps['level']
   /** The HTML element to use for each Accordion Section. */
   sectionAs?: 'div' | 'section'
 } & PropsWithChildren<HTMLAttributes<HTMLDivElement>>

packages/react/src/Accordion/AccordionContext.tsx

@@ -4,10 +4,10 @@
  */
 
 import { createContext } from 'react'
-import { HeadingLevel } from '../Heading/Heading'
+import type { HeadingProps } from '../Heading/Heading'
 
 export type AccordionContextValue = {
-  headingLevel: HeadingLevel
+  headingLevel: HeadingProps['level']
   sectionAs?: 'div' | 'section'
 }
 

packages/react/src/Alert/Alert.tsx

@@ -8,7 +8,7 @@ import clsx from 'clsx'
 import { forwardRef } from 'react'
 import type { ForwardedRef, HTMLAttributes, PropsWithChildren } from 'react'
 import { Heading } from '../Heading'
-import type { HeadingLevel } from '../Heading'
+import type { HeadingProps } from '../Heading'
 import { Icon } from '../Icon'
 import { IconButton } from '../IconButton'
 
@@ -23,7 +23,7 @@ export type AlertProps = {
    * The hierarchical level of the Heading within the document.
    * Note: this intentionally does not change the font size.
    */
-  headingLevel?: HeadingLevel
+  headingLevel?: HeadingProps['level']
   /** A function to run when dismissing. */
   onClose?: () => void
   /** The significance of the message conveyed. */

packages/react/src/FormErrorList/FormErrorList.tsx

@@ -8,7 +8,7 @@ import { forwardRef } from 'react'
 import type { ForwardedRef, HTMLAttributes } from 'react'
 import { useAddErrorCountToDocumentTitle } from './useAddErrorCountToDocumentTitle'
 import { Alert } from '../Alert'
-import type { HeadingLevel } from '../Heading'
+import type { HeadingProps } from '../Heading'
 import { LinkList } from '../LinkList'
 
 export type FormError = {
@@ -30,7 +30,7 @@ export type FormErrorListProps = {
    * The hierarchical level of the Heading within the document.
    * Note: this intentionally does not change the font size.
    */
-  headingLevel?: HeadingLevel
+  headingLevel?: HeadingProps['level']
 } & HTMLAttributes<HTMLDivElement>
 
 export const FormErrorList = forwardRef(

packages/react/src/Heading/Heading.tsx

@@ -9,16 +9,13 @@ import { forwardRef } from 'react'
 import type { ForwardedRef, HTMLAttributes, PropsWithChildren } from 'react'
 import { getHeadingElement } from './getHeadingElement'
 
-export type HeadingLevel = 1 | 2 | 3 | 4
-type HeadingSize = 'level-1' | 'level-2' | 'level-3' | 'level-4' | 'level-5' | 'level-6'
-
 export type HeadingProps = {
   /** Changes the text colour for readability on a dark background. */
   inverseColor?: boolean
   /** The hierarchical level within the document. */
-  level?: HeadingLevel
+  level?: 1 | 2 | 3 | 4
   /** Uses larger or smaller text without changing its position in the heading hierarchy. */
-  size?: HeadingSize
+  size?: 'level-1' | 'level-2' | 'level-3' | 'level-4' | 'level-5' | 'level-6'
 } & PropsWithChildren<HTMLAttributes<HTMLHeadingElement>>
 
 export const Heading = forwardRef(

packages/react/src/Heading/getHeadingElement.ts

@@ -1,6 +1,6 @@
-import { HeadingLevel } from './Heading'
+import type { HeadingProps } from './Heading'
 
-export function getHeadingElement(level: HeadingLevel) {
+export function getHeadingElement(level: HeadingProps['level']) {
   switch (level) {
     case 2:
       return 'h2'

packages/react/src/Heading/index.ts

@@ -1,2 +1,2 @@
 export { Heading } from './Heading'
-export type { HeadingLevel, HeadingProps } from './Heading'
+export type { HeadingProps } from './Heading'

packages/react/src/TableOfContents/TableOfContents.tsx

@@ -9,7 +9,7 @@ import type { ForwardedRef, HTMLAttributes, PropsWithChildren } from 'react'
 import { TableOfContentsLink } from './TableOfContentsLink'
 import { TableOfContentsList } from './TableOfContentsList'
 import { Heading } from '../Heading'
-import type { HeadingLevel } from '../Heading'
+import type { HeadingProps } from '../Heading'
 
 export type TableOfContentsProps = {
   /** The text for the Heading. */
@@ -18,7 +18,7 @@ export type TableOfContentsProps = {
    * The hierarchical level of the Heading within the document.
    * Note: this intentionally does not change the font size.
    */
-  headingLevel?: HeadingLevel
+  headingLevel?: HeadingProps['level']
 } & PropsWithChildren<HTMLAttributes<HTMLElement>>
 
 const TableOfContentsRoot = forwardRef(

storybook/src/components/Heading/Heading.docs.mdx

@@ -14,21 +14,34 @@ import README from "../../../../packages/css/src/components/heading/README.md?ra
 
 ## Examples
 
-### Heading 1
+### Levels
 
-<Canvas of={HeadingStories.Heading1} />
+We’ve limited the number of heading levels to four.
+More detailed content should probably be split into multiple pages or have some sections merged.
 
-### Heading 2
+#### Level 1
 
-<Canvas of={HeadingStories.Heading2} />
+<Canvas of={HeadingStories.Level1} />
 
-### Heading 3
+#### Level 2
 
-<Canvas of={HeadingStories.Heading3} />
+<Canvas of={HeadingStories.Level2} />
 
-### Heading 4
+#### Level 3
 
-<Canvas of={HeadingStories.Heading4} />
+<Canvas of={HeadingStories.Level3} />
+
+#### Level 4
+
+<Canvas of={HeadingStories.Level4} />
+
+### Sizes
+
+It may be visually more suitable to display a heading in a smaller font size.
+Six sizes from the set of [Text Levels](?path=/docs/docs-design-guidelines-typography--docs) can be used for this purpose.
+Ensure that you still select a level that accurately represents the section’s hierarchy.
+
+<Canvas of={HeadingStories.Sizes} />
 
 ### Inverse colour
 

storybook/src/components/Heading/Heading.stories.tsx

@@ -3,7 +3,7 @@
  * Copyright Gemeente Amsterdam
  */
 
-import { Heading } from '@amsterdam/design-system-react/src'
+import { Column, Heading } from '@amsterdam/design-system-react/src'
 import { Meta, StoryObj } from '@storybook/react'
 import { inverseColorDecorator } from '../shared/decorators'
 import { exampleHeading } from '../shared/exampleContent'
@@ -32,26 +32,39 @@ type Story = StoryObj<typeof meta>
 
 export const Default: Story = {}
 
-export const Heading1: Story = {}
+export const Level1: Story = {}
 
-export const Heading2: Story = {
+export const Level2: Story = {
   args: {
     level: 2,
   },
 }
 
-export const Heading3: Story = {
+export const Level3: Story = {
   args: {
     level: 3,
   },
 }
 
-export const Heading4: Story = {
+export const Level4: Story = {
   args: {
     level: 4,
   },
 }
 
+export const Sizes: Story = {
+  render: (args) => (
+    <Column gap="small">
+      <Heading {...args} key="level-1" size="level-1" />
+      <Heading {...args} key="level-2" size="level-2" />
+      <Heading {...args} key="level-3" size="level-3" />
+      <Heading {...args} key="level-4" size="level-4" />
+      <Heading {...args} key="level-5" size="level-5" />
+      <Heading {...args} key="level-6" size="level-6" />
+    </Column>
+  ),
+}
+
 export const InvertedColor: Story = {
   args: {
     inverseColor: true,