docs(headings): Edits and cleanup to the DisplayHeading and Heading docs

src/components/Typography/DisplayHeading/DisplayHeading.jsx

@@ -12,7 +12,7 @@ const getClassName = invert => (
 )
 
 /**
- * Used for big page headings.
+ * Large page titles. Renders an HTML `<h1>` element.
  *
  * <span class="docs--badge green">new!</span> <span class="docs--badge purple">v0.22.0</span>
  */
@@ -22,11 +22,11 @@ const DisplayHeading = ({ invert, children, ...rest }) => (
 
 DisplayHeading.propTypes = {
   /**
-   * Whether or not to invert the colour scheme.
+   * Invert the text color to appear light on dark backgrounds.
    */
   invert: PropTypes.bool,
   /**
-   * The text.
+   * The text. Can be text, other components, or HTML elements.
    */
   children: PropTypes.node.isRequired
 }

src/components/Typography/DisplayHeading/DisplayHeading.md

@@ -1,10 +1,5 @@
-### Minimal usage
+Use as an overlay on Hero, Promo or Headline blocks.
 
 ```
-<DisplayHeading>Great Deals</DisplayHeading>
+<DisplayHeading>Smartphones</DisplayHeading>
 ```
-
-#### Usage criteria
-
-- Display Heading outputs an `h1` tag.
-- Use as an overlay on hero, promo or headline blocks.

src/components/Typography/DisplayHeading/DisplayHeadingSup/DisplayHeadingSup.jsx

@@ -5,7 +5,7 @@ import safeRest from '../../../../utils/safeRest'
 import styles from '../DisplayHeading.modules.scss'
 
 /**
- * Superscript text for headings.
+ * Superscript text for `DisplayHeading` an as HTML `<sup>` element.
  *
  * <span class="docs--badge green">new!</span> <span class="docs--badge purple">v0.22.0</span>
  *

src/components/Typography/DisplayHeading/DisplayHeadingSup/DisplayHeadingSup.md

@@ -1,7 +1,5 @@
-### Usage
-
-The Display Heading Sup component wraps text in a `<sup>` tag. It assures proper font sizes are rendered depending on the parent font size.
-
 ```
-  <DisplayHeading>Great Deals<DisplayHeading.Sup>1</DisplayHeading.Sup></DisplayHeading>
+<DisplayHeading>
+  TELUS Optik TV<DisplayHeading.Sup>®</DisplayHeading.Sup>
+</DisplayHeading>
 ```

src/components/Typography/Heading/Heading.jsx

@@ -18,7 +18,7 @@ const getClassName = (level, invert) => {
 }
 
 /**
- * Used for page headings.
+ * Page headings. Renders an HTML `<h1-h4>` element.
  *
  * <span class="docs--badge green">new!</span> <span class="docs--badge purple">v0.22.0</span>
  */
@@ -34,22 +34,19 @@ const Heading = ({ level, invert, children, ...rest }) => (
 )
 Heading.propTypes = {
   /**
-   * Heading level (default is `h1`).
+   * The heading level.
    */
-  level: PropTypes.oneOf([
-    'h1', 'h2', 'h3', 'h4'
-  ]).isRequired,
+  level: PropTypes.oneOf(['h1', 'h2', 'h3', 'h4']).isRequired,
   /**
-   * Whether or not to invert the colour scheme.
+   * Invert the text color to appear light on dark backgrounds.
    */
   invert: PropTypes.bool,
   /**
-   * The text.
+   * The text. Can be text, other components, or HTML elements.
    */
   children: PropTypes.node.isRequired
 }
 Heading.defaultProps = {
-  level: 'h1',
   invert: false
 }
 

src/components/Typography/Heading/Heading.md

@@ -1,35 +1,15 @@
-### Minimal Usage
-
-The Heading component outputs an `h1` tag by default.
-
 ```
-<Heading>Great Deals</Heading>
+<div>
+  <Heading level="h1">Heading level 1</Heading>
+  <Heading level="h2">Heading level 2</Heading>
+  <Heading level="h3">Heading level 3</Heading>
+  <Heading level="h4">Heading level 4</Heading>
+</div>
 ```
 
 #### Usage criteria
 
 - Be mindful of SEO and accessibility.
-- Be sure to organise headers in a nested order: h1, then h2, then h3.
+- Organise headers in a nested order: h1, then h2, then h3.
 - Do **not** skip levels: h1, then h3.
-- For hero overlays, headlines, or promo blocks, use [Display Heading](#displayheading).
-
-### Defining level
-
-```
-<div>
-  <Heading level="h1">Great Deals</Heading>
-  <Heading level="h2">Great Deals</Heading>
-  <Heading level="h3">Great Deals</Heading>
-  <Heading level="h4">Great Deals</Heading>
-</div>
-```
-
-### Invert on dark colours
-
-```
-const PurpleBlock = require('../../__docs__/PurpleBlock').default;
-
-<PurpleBlock>
-  <Heading invert>Great Deals</Heading>
-</PurpleBlock>
-```
+- For Hero overlays, Headlines, or Promo blocks, use [`DisplayHeading`](#displayheading).

src/components/Typography/Heading/HeadingSup/HeadingSup.jsx

@@ -5,7 +5,7 @@ import safeRest from '../../../../utils/safeRest'
 import styles from '../Heading.modules.scss'
 
 /**
- * Superscript text for headings.
+ * Superscript text for `Heading` an as HTML `<sup>` element.
  *
  * <span class="docs--badge green">new!</span> <span class="docs--badge purple">v0.22.0</span>
  *

src/components/Typography/Heading/HeadingSup/HeadingSup.md

@@ -1,23 +1,8 @@
-### Usage
-
-The Heading Sup component wraps text in a `<sup>` tag. It assures proper font sizes are rendered depending on the parent font size.
-
-**Note: do not use Heading Sup within a Display Heading component. Use [DisplayHeading.Sup](#displayheadingsup) instead.**
-
-
 ```
 <div>
-  <div>
-    <Heading level="h1">Optik TV<Heading.Sup>®</Heading.Sup></Heading>
-    <Heading level="h2">Optik TV<Heading.Sup>®</Heading.Sup></Heading>
-    <Heading level="h3">Optik TV<Heading.Sup>®</Heading.Sup></Heading>
-    <Heading level="h4">Optik TV<Heading.Sup>®</Heading.Sup></Heading>
-  </div>
-  <div>
-    <Heading level="h1">TELUS Pik TV<Heading.Sup>&trade;</Heading.Sup></Heading>
-    <Heading level="h2">TELUS Pik TV<Heading.Sup>&trade;</Heading.Sup></Heading>
-    <Heading level="h3">TELUS Pik TV<Heading.Sup>&trade;</Heading.Sup></Heading>
-    <Heading level="h4">TELUS Pik TV<Heading.Sup>&trade;</Heading.Sup></Heading>
-  </div>
+  <Heading level="h1">TELUS Pik TV<Heading.Sup>&trade;</Heading.Sup></Heading>
+  <Heading level="h2">TELUS Pik TV<Heading.Sup>&trade;</Heading.Sup></Heading>
+  <Heading level="h3">TELUS Pik TV<Heading.Sup>&trade;</Heading.Sup></Heading>
+  <Heading level="h4">TELUS Pik TV<Heading.Sup>&trade;</Heading.Sup></Heading>
 </div>
 ```

src/components/Typography/Heading/__tests__/Heading.spec.jsx

@@ -5,8 +5,11 @@ import toJson from 'enzyme-to-json'
 import Heading from '../Heading'
 
 describe('Heading', () => {
+  const defaultProps = {
+    level: 'h1'
+  }
   const doShallow = (overrides = {}) => shallow(
-    <Heading {...overrides}>Go home</Heading>
+    <Heading {...defaultProps} {...overrides}>Go home</Heading>
   )
 
   it('renders', () => {

src/components/Typography/Typography.md

@@ -1,16 +1,23 @@
-Typography components replace standard HTML dom (preferring `<Small></Small>` over `<small></small>`) in order to provide maintainable font sizes and styles.
+Typography components replace standard HTML dom (`<Paragraph>` instead of `<p>`) in order to provide maintainable
+font styles.
 
 ## Spacing system
 
-As of v0.22.0, Typography components **do not** have built-in styles for spacing (padding or margin). For the interim, designers are strongly advised to follow TDS Sketch assets for spacing rules in order for developers to properly apply the correct spacing between related components.
+As of v0.22.0, Typography components **do not** have built-in padding or margin. For the interim, designers are strongly
+advised to follow TDS Sketch assets for spacing rules in order for developers to properly apply the correct spacing between
+related components.
 
-For example, a `<Paragraph />` component immediately following a `<Heading />` component would require `1rem` spacing between them. For this case, we recommend:
+For example, a `<Paragraph>` component immediately following a `<Heading>` component would require `1rem` spacing between
+them. For this case, we recommend:
 
 ```
 <div>
-  <Heading>Great Deals</Heading>
+  <Heading level="h2">Great Deals</Heading>
+
   <div style={{paddingTop: '1rem'}}>
-    <Paragraph>See how this great deal can benefit you and your shared lines.</Paragraph>
+    <Paragraph>
+      See how this great deal can benefit you and your shared lines.
+    </Paragraph>
   </div>
 </div>
 ```