Require the as prop in heading components

.changeset/cuddly-taxis-behave.md

@@ -0,0 +1,5 @@
+---
+'@sumup/circuit-ui': major
+---
+
+Made the `as` prop required in the `Headline` and `SubHeadline` components. Intentionally setting the heading level ensures a consistent and accessible page structure.

packages/circuit-ui/components/Headline/Headline.docs.mdx

@@ -14,6 +14,16 @@ Headlines are used for titling major sections of the interface. They help better
 - **Do** position the heading above the content
 - **Do** use the `four` size for titling cards and `three` for pages
 
+## Content guidelines
+
+Nest headings by their rank (or level). The most important heading has rank 1 (`h1`), the least important heading rank 6 (`h6`). Headings with an equal or higher rank start a new section, headings with a lower rank start new subsections that are part of the higher-ranked section.
+
+Skipping heading ranks can be confusing and should be avoided where possible: Ensure that an `h2` is not followed directly by an `h4`, for example. It is ok to skip ranks when closing subsections, for instance, an `h2` beginning a new section can follow an `h4` as it closes the previous section.
+
+[Learn more about a proper page structure](https://www.w3.org/WAI/tutorials/page-structure/headings/).
+
+## Component variations
+
 ### Sizes
 
 <Story id="typography-headline--sizes" />

packages/circuit-ui/components/Headline/Headline.spec.tsx

@@ -32,7 +32,7 @@ describe('Headline', () => {
   const sizes = ['one', 'two', 'three', 'four'] as const;
   it.each(sizes)(`should render with size %s`, (size) => {
     const headline = create(
-      <Headline {...{ size }}>{`${size} headline`}</Headline>,
+      <Headline as="h2" {...{ size }}>{`${size} headline`}</Headline>,
     );
     expect(headline).toMatchSnapshot();
   });
@@ -41,7 +41,7 @@ describe('Headline', () => {
    * Accessibility tests.
    */
   it('should meet accessibility guidelines', async () => {
-    const wrapper = renderToHtml(<Headline>Headline</Headline>);
+    const wrapper = renderToHtml(<Headline as="h2">Headline</Headline>);
     const actual = await axe(wrapper);
     expect(actual).toHaveNoViolations();
   });

packages/circuit-ui/components/Headline/Headline.tsx

@@ -28,9 +28,11 @@ export interface HeadlineProps
    */
   size?: Size;
   /**
-   * The HTML headline element to render.
+   * The HTML heading element to render. Headings should be nested sequentially
+   * without skipping any levels. Learn more at
+   * https://www.w3.org/WAI/tutorials/page-structure/headings/.
    */
-  as?: string;
+  as: string;
 }
 
 const baseStyles = ({ theme }: StyleProps) => css`

packages/circuit-ui/components/SubHeadline/SubHeadline.docs.mdx

@@ -4,13 +4,20 @@ import { Status, Props, Story } from '../../../../.storybook/components';
 
 <Status.Stable />
 
-Subheadings help users break through larger related contents in the same section.
-They are usually used to separate sections within a card.
+Subheadlines help to break up larger related chunks of content in the same section. They are usually used to separate sections within a card.
 
 <Story id="typography-subheadline--base" />
 <Props />
 
 ## Usage guidelines
 
-- **Do** use subheadings to break complex and longer contents in a page or card
-- **Do not** use a subheading without a heading title for the same section
+- **Do** use subheadlines to break complex and longer chunks of content in a page or card
+- **Do not** use a subheadline without a heading title for the same section
+
+## Content guidelines
+
+Nest headings by their rank (or level). The most important heading has rank 1 (`h1`), the least important heading rank 6 (`h6`). Headings with an equal or higher rank start a new section, headings with a lower rank start new subsections that are part of the higher-ranked section.
+
+Skipping heading ranks can be confusing and should be avoided where possible: Ensure that an `h2` is not followed directly by an `h4`, for example. It is ok to skip ranks when closing subsections, for instance, an `h2` beginning a new section can follow an `h4` as it closes the previous section.
+
+[Learn more about a proper page structure](https://www.w3.org/WAI/tutorials/page-structure/headings/).

packages/circuit-ui/components/SubHeadline/SubHeadline.spec.tsx

@@ -30,15 +30,15 @@ describe('SubHeadline', () => {
   });
 
   it('should render with no margin styles when passed the prop', () => {
-    const actual = create(<SubHeadline />);
+    const actual = create(<SubHeadline as="h3" />);
     expect(actual).toMatchSnapshot();
   });
 
   /**
    * Accessibility tests.
    */
   it('should meet accessibility guidelines', async () => {
-    const wrapper = renderToHtml(<SubHeadline>Subheading</SubHeadline>);
+    const wrapper = renderToHtml(<SubHeadline as="h3">Subheading</SubHeadline>);
     const actual = await axe(wrapper);
     expect(actual).toHaveNoViolations();
   });

packages/circuit-ui/components/SubHeadline/SubHeadline.tsx

@@ -22,9 +22,11 @@ import styled, { StyleProps } from '../../styles/styled';
 export interface SubHeadlineProps
   extends Omit<HTMLProps<HTMLHeadingElement>, 'size'> {
   /**
-   * The HTML subheading element to render.
+   * The HTML heading element to render. Headings should be nested sequentially
+   * without skipping any levels. Learn more at
+   * https://www.w3.org/WAI/tutorials/page-structure/headings/.
    */
-  as?: string;
+  as: string;
 }
 
 const baseStyles = ({ theme }: StyleProps) => css`