docs: migrate Headline docs

Author: Nikolai Lopin

src/components/Headline/Headline.tsx

@@ -21,7 +21,7 @@ interface HeadlineProps extends ComponentPropsWithoutRef<'h1'>, MarginProps, Tex
     size?: ResponsiveValue<'xxl' | 'xl' | 'l' | 'm' | 's' | 'xs'>;
 }
 
-const DEFAULT_HEADLINE_SIZE = {
+export const DEFAULT_HEADLINE_SIZE = {
     h1: 'xxl',
     h2: 'xl',
     h3: 'l',

src/components/Headline/docs/Headline.mdx

@@ -0,0 +1,60 @@
+import { Meta, StoryObj } from '@storybook/react';
+import { DEFAULT_HEADLINE_SIZE, Headline } from '../Headline';
+
+const meta: Meta = {
+    title: 'Components/Headline',
+    component: Headline,
+    args: {
+        children: "The dos and don'ts of eating sushi"
+    },
+    argTypes: {
+        size: {
+            table: {
+                defaultValue: {
+                    summary: 'depends on the heading level',
+                    detail: Object.entries(DEFAULT_HEADLINE_SIZE)
+                        .map(([tag, size]) => `${tag} → ${size}`)
+                        .join('\n')
+                }
+            },
+            control: 'select',
+            options: ['xxl', 'xl', 'l', 'm', 's', 'xs']
+        }
+    }
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Headline>;
+
+export const Default: Story = {};
+
+export const WithAnotherLevel: Story = {
+    args: {
+        as: 'h3'
+    }
+};
+
+export const WithAnotherSize: Story = {
+    args: {
+        size: 's'
+    }
+};
+
+export const Inverted: Story = {
+    args: {
+        inverted: true
+    },
+    parameters: {
+        backgrounds: {
+            default: 'dark'
+        }
+    }
+};
+
+export const Responsive: Story = {
+    args: {
+        children: 'Change the viewport size',
+        size: ['s', 'xl']
+    }
+};

src/components/Headline/docs/Headline.stories.tsx

@@ -0,0 +1,76 @@
+import { ArgsTable, Meta, Primary, Stories, Unstyled } from '@storybook/blocks';
+import { ItemWrapper } from '../../../../docs/components/ItemWrapper';
+import { StyledSystemLinks } from '../../../docs/StyledSystemLinks';
+import { Headline } from '../Headline';
+import * as HeadlineStories from './Headline.stories';
+
+<Meta of={HeadlineStories} />
+
+# Headline
+
+<Primary />
+
+The Headline component will render an html `h1-6` tag. Please reference the
+[w3 recommendations for headings](https://www.w3.org/WAI/tutorials/page-structure/headings/) to ensure your headings
+provide an accessible experience for screen reader users.
+
+Prefer to use headlines starting from level one and not skip levels. Use combination of `as` and `size` property to keep
+the semantics while following the design.
+
+-   Use different headlines and paragraphs to structure your content hierarchically
+-   Avoid using headline lengths, breaking more than two times (three times on mobile)
+-   Avoid using sizes outside the given range
+-   Recommended width of headline is between 500px and 700px
+
+## Properties
+
+<ArgsTable of={Headline} />
+<StyledSystemLinks component="Headline" supportedProps={['margin', 'textAlign']} />
+
+## Default headlines
+
+<Unstyled>
+    <ItemWrapper>
+        <Headline as="h1">headline h1</Headline>
+        <Headline as="h2">headline h2</Headline>
+        <Headline as="h3">headline h3</Headline>
+        <Headline as="h4">headline h4</Headline>
+        <Headline as="h5">headline h5</Headline>
+        <Headline as="h6">headline h6</Headline>
+    </ItemWrapper>
+    <ItemWrapper inverted>
+        <Headline as="h1" inverted>
+            headline h1 inverted
+        </Headline>
+        <Headline as="h2" inverted>
+            headline h2 inverted
+        </Headline>
+        <Headline as="h3" inverted>
+            headline h3 inverted
+        </Headline>
+        <Headline as="h4" inverted>
+            headline h4 inverted
+        </Headline>
+        <Headline as="h5" inverted>
+            headline h5 inverted
+        </Headline>
+        <Headline as="h6" inverted>
+            headline h6 inverted
+        </Headline>
+    </ItemWrapper>
+</Unstyled>
+
+## Responsive size
+
+The `size` property supports [responsive values](https://styled-system.com/responsive-styles/). Pass an array or an object
+and the design system use corresponding values for different viewport sizes.
+
+For example, the following snippet uses `s` size for mobile and `xl` size bigger screens:
+
+```jsx
+<Headline as="h2" size={{ _: 's', medium: 'xl' }}>
+    Small on mobile, big on bigger screens
+</Headline>
+```
+
+<Stories includePrimary={false} />