feat(ui-heading): enable setting level for headings with variant

INSTUI-4612

Author: HerrTopi

packages/ui-heading/src/Heading/README.md

@@ -6,10 +6,15 @@ Heading is a component for creating typographic headings.
 
 ## Variant
 
-Variant covers almost all use cases for headings on pages. Their name reflects the places they meant to be used. It sets the `level` prop and takes care of the style of the heading
-We recommend using `variants` instead of the `level` (and `as`) props.
+Variant covers almost all use cases for headings on pages. Their name reflects the places they meant to be used. It takes care of the style of the heading
 
-NOTE: when `variant` is set, `level` and `as` props are ignored
+NOTE 1: for legacy reasons, each `variant` has a default `level` set. This is not the recommended way and will be removed in a later major release. Please specify the `level` directly!
+
+NOTE 2: when `variant` is set the `as` prop is ignored
+
+IMPORTANT A11Y NOTE 1: there can be only one `h1` tag in a page
+
+IMPORTANT A11Y NOTE 2: `h` tags can not skip a level, so for example an `h1` followed by an `h3` not allowed
 
 ```js
 ---

packages/ui-heading/src/Heading/index.tsx

@@ -88,11 +88,8 @@ class Heading extends Component<HeadingProps> {
   }
 
   checkProps() {
-    const { variant, level, as } = this.props
+    const { variant, as } = this.props
     if (variant) {
-      if (level) {
-        console.warn("[Heading]: Don't use 'level' with 'variant' ")
-      }
       if (as) {
         console.warn("[Heading]: Don't use 'as' with 'variant' ")
       }
@@ -138,13 +135,16 @@ class Heading extends Component<HeadingProps> {
     const propsForGetElementType = variant ? {} : this.props
 
     const ElementType = getElementType(Heading, propsForGetElementType, () => {
-      if (variant) {
-        return variantLevels[variant]
-      }
       if (level === 'reset') {
         return 'span'
+      } else if (level) {
+        return level
+      }
+
+      if (variant) {
+        return variantLevels[variant]
       } else {
-        return level!
+        return 'span'
       }
     })
 

packages/ui-heading/src/Heading/props.ts

@@ -84,8 +84,7 @@ type HeadingOwnProps = {
    */
   renderIcon?: Renderable
   /**
-   * Sets style and level at once. The as property will be the same as the level.
-   * NOTE: this is the recommended way of setting the appearance, instead of level
+   * Sets appearance of the heading.
    */
   variant?:
     | 'titlePageDesktop'