Document the props not having a default value

Author: VincentSmedinga

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

@@ -2,16 +2,16 @@
 
 # Heading
 
-Describes the content that follows it.
-Use Headings to allow the user to grasp the structure of the page quickly.
+Introduces a page section and describes the following content.
 
 ## Guidelines
 
-- A heading describes the content beneath it.
-- 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.
+- All headings together represent the document’s structure. Users of screen readers may use headings to navigate the page – an incorrect hierarchy will confuse them.
+- Every page should contain one heading with level 1.
+  The level of subsequent headings should be appropriate: a subsection must use one level higher than the section it belongs to.
+  The `level` prop doesn’t have a default value; the correct level should be determined for each instance.
+- Search engines give more weight to text in headers.
+- Don’t use a Heading only to produce its appearance.
 
 ## Relevant WCAG requirements
 

packages/react/src/Accordion/Accordion.tsx

@@ -12,7 +12,10 @@ 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. */
+  /**
+   * The hierarchical level of this Accordion’s Section Headings within the document.
+   * There is no default value; determine the correct level for each instance.
+   **/
   headingLevel: HeadingProps['level']
   /** The HTML element to use for each Accordion Section. */
   sectionAs?: 'div' | 'section'

packages/react/src/Alert/Alert.tsx

@@ -20,9 +20,9 @@ export type AlertProps = {
   /** The text for the Heading. */
   heading?: string
   /**
-   * The hierarchical level of the Heading within the document.
-   * Note: this intentionally does not change the font size.
-   */
+   * The hierarchical level of the Alert’s Heading within the document.
+   * There is no default value; determine the correct level for each instance.
+   **/
   headingLevel: HeadingProps['level']
   /** A function to run when dismissing. */
   onClose?: () => void

packages/react/src/FormErrorList/FormErrorList.tsx

@@ -34,10 +34,9 @@ export type FormErrorListProps = {
    */
   heading?: string
   /**
-   * The hierarchical level of the Heading within the document.
-   * Note: this intentionally does not change the font size.
-   * @default 2
-   */
+   * The hierarchical level of the Form Error List’s Heading within the document.
+   * There is no default value; determine the correct level for each instance.
+   **/
   headingLevel: HeadingProps['level']
 } & HTMLAttributes<HTMLDivElement>
 

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

@@ -68,5 +68,6 @@ export const Sizes: Story = {
 export const InverseColour: Story = {
   args: {
     inverseColor: true,
+    level: 2,
   },
 }