docs(typography): Edits and cleanup to Text, Paragraph, Strong, Small…

…, and Text.Sup docs

src/components/Notification/__tests__/__snapshots__/Notification.spec.jsx.snap

@@ -23,7 +23,7 @@ exports[`<Notification /> renders 1`] = `
               medium
               mediumFont
               leftAlign
-              "
+            "
           >
             Some content
           </p>

src/components/Typography/Paragraph/Paragraph.jsx

@@ -8,6 +8,8 @@ import styles from './Paragraph.modules.scss'
 import textStyles from '../Text/Text.modules.scss'
 
 /**
+ * Block text as an HTML `<p>` element.
+ *
  * <span class="docs--badge green">new!</span> <span class="docs--badge purple">v0.22.0</span>
  */
 const Paragraph = ({ bold, size, align, invert, children, ...rest }, context) => {
@@ -19,7 +21,7 @@ const Paragraph = ({ bold, size, align, invert, children, ...rest }, context) =>
     ${textStyles[size]}
     ${bold ? textStyles.boldFont : textStyles[`${size}Font`]}
     ${styles[`${align}Align`]}
-    `
+  `
 
   return (
     <p {...safeRest(rest)} className={classes}>
@@ -34,23 +36,23 @@ Paragraph.propTypes = {
    */
   bold: PropTypes.bool,
   /**
-   * Font size.
+   * The font size.
    */
   size: PropTypes.oneOf([
     'small',
     'medium',
     'large'
   ]),
   /**
-   * Align content.
+   * Content alignment.
    */
   align: PropTypes.oneOf([
     'left',
     'center',
     'right'
   ]),
   /**
-   * Invert to appear light on dark backgrounds.
+   * Invert the text color to appear light on dark backgrounds.
    */
   invert: PropTypes.bool,
   /**

src/components/Typography/Paragraph/Paragraph.md

@@ -1,9 +1,23 @@
-### Usage
-
 ```
 <div>
-  <Paragraph>Our commitment to service is demonstrated in everything we do.</Paragraph>
-  <Paragraph>Enjoy your choice of <Link href="#">5 channels</Link>, and up to <Link href="#">23 local and regional channels</Link>. Plus, add Premium channel packs like HBO, TMN &amp; Crave TV for just $20/mo. All delivered via TELUS Internet through the Pik TV media box and Pik TV app.<Text.Sup>2</Text.Sup>
+  <Paragraph>
+    Our commitment to service is demonstrated in everything we do.
+  </Paragraph>
+
+  <Paragraph>
+    Enjoy your choice of <Link href="#">5 channels</Link>, and up to <Link href="#">23 local and regional channels</Link>. Plus, add Premium channel packs like HBO, TMN &amp; Crave TV for just $20/mo. All delivered via TELUS Internet through the Pik TV media box and Pik TV app.<Text.Sup>2</Text.Sup>
   </Paragraph>
 </div>
 ```
+
+### Placing text on dark colours
+
+Use the `invert` prop.
+
+```
+const PurpleBlock = require('../../__docs__/PurpleBlock').default;
+
+<PurpleBlock>
+  <Paragraph invert>Order online and save an extra $150.</Paragraph>
+</PurpleBlock>
+```

src/components/Typography/Paragraph/__tests__/__snapshots__/Paragraph.spec.jsx.snap

@@ -8,7 +8,7 @@ exports[`Paragraph renders 1`] = `
     medium
     mediumFont
     leftAlign
-    "
+  "
 >
   Some content
 </p>

src/components/Typography/Small/Small.jsx

@@ -6,7 +6,7 @@ import safeRest from '../../../utils/safeRest'
 import styles from '../Text/Text.modules.scss'
 
 /**
- * Use for small print, including copyright and legal text
+ * Small print, such as copyright and legal text.
  *
  * <span class="docs--badge green">new!</span> <span class="docs--badge purple">v0.22.0</span>
  */

src/components/Typography/Small/Small.md

@@ -1,5 +1,5 @@
-### Usage
-
 ```
-<Small>Taxes and pay-per-use charges (including long distance, roaming and additional airtime or data) are extra.</Small>
+<Small>
+  Taxes and pay-per-use charges (including long distance, roaming and additional airtime or data) are extra.
+</Small>
 ```

src/components/Typography/Strong/Strong.jsx

@@ -6,7 +6,7 @@ import safeRest from '../../../utils/safeRest'
 import styles from '../Text/Text.modules.scss'
 
 /**
-  * Use to give portions of a sentence added importance
+  * Give portions of a sentence added importance.
   *
   * <span class="docs--badge green">new!</span> <span class="docs--badge purple">v0.22.0</span>
   */

src/components/Typography/Strong/Strong.md

@@ -1,5 +1,5 @@
-### Usage
-
 ```
-<Strong>This text is bold</Strong>
+<Text>
+  <Strong>Your password is not valid.</Strong> It must not be one of your previously used passwords.
+</Text>
 ```

src/components/Typography/Text/Text.jsx

@@ -8,7 +8,7 @@ import TextSub from './TextSub/TextSub'
 import styles from './Text.modules.scss'
 
 /**
- * Produces inline text
+ * Inline text as an HTML `<span>` element.
  *
  * <span class="docs--badge green">new!</span> <span class="docs--badge purple">v0.22.0</span>
  */
@@ -34,7 +34,7 @@ Text.propTypes = {
    */
   bold: PropTypes.bool,
   /**
-   * Font size.
+   * The font size.
    */
   size: PropTypes.oneOf([
     'base',
@@ -43,11 +43,11 @@ Text.propTypes = {
     'large'
   ]),
   /**
-   * Invert span style to appear light on dark backgrounds.
+   * Invert the text color to appear light on dark backgrounds.
    */
   invert: PropTypes.bool,
   /**
-   * The text.
+   * The content. Can be text, other components, or HTML elements.
    */
   children: PropTypes.node.isRequired
 }

src/components/Typography/Text/Text.md

@@ -1,23 +1,17 @@
-### Usage
-
-The Text component can be used within other typography components such as [Paragraph](#paragraph). It is useful for modifying text appearance such as **bold**, or changing text size.
-
 ```
-<Text size="small" bold>Tell us what you think</Text>
+<Text>Tell us what you think</Text>
 ```
 
-### Inherits props from Paragraph
+By default, the Text component will inherit font properties from its parent. Use the props to override this behaviour.
 
 ```
-<Paragraph size="small"><Text>Tell us what you think</Text>  It's in our nature to listen.</Paragraph>
-```
-
-### Invert on dark colours
-
-```
-const PurpleBlock = require('../../__docs__/PurpleBlock').default;
-
-<PurpleBlock>
-  <Text invert>Personal</Text>
-</PurpleBlock>
+<Paragraph>
+  <Text bold>
+    Get Optik TV<Text.Sup>®</Text.Sup> and Internet for $85 per month for 12 months.
+  </Text>
+  <br />
+  <Text size="small">
+    Sign up for 2 years and save BIG on your first 12 months.
+  </Text>
+</Paragraph>
 ```

src/components/Typography/Text/TextSup/TextSup.jsx

@@ -6,12 +6,11 @@ import safeRest from '../../../../utils/safeRest'
 import styles from '../Text.modules.scss'
 
 /**
- * Text that should be displayed higher than the main text (superscript).
- *
- * <span class="docs--badge green">new!</span> <span class="docs--badge purple">v0.22.0</span>
+ * Superscript text an as HTML `<sup>` element.
  *
  * _This component can only be accessed as a name-spaced component: `Text.Sup`._
  *
+ * <span class="docs--badge green">new!</span> <span class="docs--badge purple">v0.22.0</span>
  */
 const TextSup = ({ children, ...rest }) => (
   <sup {...safeRest(rest)} className={styles.sup}>{children}</sup>

src/components/Typography/Text/TextSup/TextSup.md

@@ -1,20 +1,7 @@
-### Usage
-
-The Text 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 Text Sup within a Heading component. Use [Heading.Sup](#headingsup) instead.**
+Only use `Text.Sup` as a child of `Paragraph` or `Text`. Use [`Heading.Sup`](#headingsup) for superscript within headings.
 
 ```
-<div>
-  <div>
-    <Text size="large">Enjoy your choice of <Link href="#">5 channels</Link>, and up to <Link href="#">23 local and regional channels</Link>. Plus, add Premium channel packs like HBO, TMN &amp; Crave TV for just $20/mo. All delivered via TELUS Internet through the Pik TV media box and Pik TV app.<Text.Sup>2</Text.Sup>
-    </Text>
-  </div>
-  <div>
-    <Text size="medium">Enjoy buffer-free streaming any time of day<Text.Sup>2</Text.Sup></Text>
-  </div>
-  <div>
-    <Text size="small">Starting at $75 per month on a 2-year plan<Text.Sup>15</Text.Sup></Text>
-  </div>
-</div>
+<Text>
+  Enjoy buffer-free streaming any time of day<Text.Sup>2</Text.Sup>.
+</Text>
 ```