From f8d5a8a71f14ea1b86ae957bf95dc7638e3e5711 Mon Sep 17 00:00:00 2001
From: Enrico <enrico.sacchetti@telus.com>
Date: Tue, 29 Aug 2017 14:07:33 -0400
Subject: [PATCH] docs(heading): add usage notes and props comments

---
 docs/elements/typography.md                   |  2 ++
 src/components/Typography/Heading/Heading.jsx | 14 ++++++++++++++
 src/components/Typography/Heading/Heading.md  | 13 +++++++++++--
 3 files changed, 27 insertions(+), 2 deletions(-)

diff --git a/docs/elements/typography.md b/docs/elements/typography.md
index d8dbcd729a..11cee8f155 100644
--- a/docs/elements/typography.md
+++ b/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
diff --git a/src/components/Typography/Heading/Heading.jsx b/src/components/Typography/Heading/Heading.jsx
index ab696436a3..b550cb9c9f 100644
--- a/src/components/Typography/Heading/Heading.jsx
+++ b/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 = {
diff --git a/src/components/Typography/Heading/Heading.md b/src/components/Typography/Heading/Heading.md
index 34c17ce173..eabf2b5e4f 100644
--- a/src/components/Typography/Heading/Heading.md
+++ b/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>