docs(heading): add usage notes and props comments

docs/elements/typography.md

@@ -55,6 +55,8 @@ To create consistent leading the line height is set to double the value of the b
 
 ## Headings
 
+**The Headings CSS classes are deprecated and should not be used. Use the [Display Heading](#displayheading) and [Heading](#heading) components instead.**
+
 ---
 
 - Use sentence case for headings

src/components/Typography/Heading/Heading.jsx

@@ -15,6 +15,11 @@ const getClassName = (level, invert) => {
   return `${styles[level]} ${colorClassName}`
 }
 
+/**
+ * Used for page headings.
+ *
+ * <span class="docs--badge green">new!</span> <span class="docs--badge purple">v0.22.0</span>
+ */
 const Heading = ({ level, invert, children, ...rest }) => (
   React.createElement(
     level,
@@ -26,10 +31,19 @@ const Heading = ({ level, invert, children, ...rest }) => (
   )
 )
 Heading.propTypes = {
+  /**
+   * Heading level (default is `h1`).
+   */
   level: PropTypes.oneOf([
     'h1', 'h2', 'h3', 'h4'
   ]).isRequired,
+  /**
+   * Whether or not to invert the colour scheme.
+   */
   invert: PropTypes.bool,
+  /**
+   * The heading text.
+   */
   children: PropTypes.node.isRequired
 }
 Heading.defaultProps = {

src/components/Typography/Heading/Heading.md

@@ -1,10 +1,19 @@
-### Minimal usage
+### Minimal Usage
+
+The Heading component outputs an `h1` tag by default.
 
 ```
 <Heading>Great Deals</Heading>
 ```
 
-### Defining sizes
+#### Usage criteria
+
+- Be mindful of SEO and accessibility.
+- Be sure to organise headers in a nested order: h1, then h2, then h3.
+- Do **not** skip levels: h1, then h3.
+- For splash banners or hero overlays, use [Display Heading](#displayheading).
+
+### Defining level
 
 ```
 <div>