From ccd8a2e38deef51997b8b4e0dbdc1d23f6de8fb3 Mon Sep 17 00:00:00 2001 From: Ryan Oglesby Date: Tue, 26 Sep 2017 10:04:59 -0400 Subject: [PATCH] docs(headings): Edits and cleanup to the DisplayHeading and Heading docs --- .../DisplayHeading/DisplayHeading.jsx | 6 ++-- .../DisplayHeading/DisplayHeading.md | 9 ++--- .../DisplayHeadingSup/DisplayHeadingSup.jsx | 2 +- .../DisplayHeadingSup/DisplayHeadingSup.md | 8 ++--- src/components/Typography/Heading/Heading.jsx | 13 +++---- src/components/Typography/Heading/Heading.md | 36 +++++-------------- .../Heading/HeadingSup/HeadingSup.jsx | 2 +- .../Heading/HeadingSup/HeadingSup.md | 23 +++--------- .../Heading/__tests__/Heading.spec.jsx | 5 ++- src/components/Typography/Typography.md | 17 ++++++--- 10 files changed, 43 insertions(+), 78 deletions(-) diff --git a/src/components/Typography/DisplayHeading/DisplayHeading.jsx b/src/components/Typography/DisplayHeading/DisplayHeading.jsx index c9d5d768c9..be449d23bb 100644 --- a/src/components/Typography/DisplayHeading/DisplayHeading.jsx +++ b/src/components/Typography/DisplayHeading/DisplayHeading.jsx @@ -12,7 +12,7 @@ const getClassName = invert => ( ) /** - * Used for big page headings. + * Large page titles. Renders an HTML `

` element. * * new! v0.22.0 */ @@ -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 } diff --git a/src/components/Typography/DisplayHeading/DisplayHeading.md b/src/components/Typography/DisplayHeading/DisplayHeading.md index c78701f362..e4ef3d26d4 100644 --- a/src/components/Typography/DisplayHeading/DisplayHeading.md +++ b/src/components/Typography/DisplayHeading/DisplayHeading.md @@ -1,10 +1,5 @@ -### Minimal usage +Use as an overlay on Hero, Promo or Headline blocks. ``` -Great Deals +Smartphones ``` - -#### Usage criteria - -- Display Heading outputs an `h1` tag. -- Use as an overlay on hero, promo or headline blocks. diff --git a/src/components/Typography/DisplayHeading/DisplayHeadingSup/DisplayHeadingSup.jsx b/src/components/Typography/DisplayHeading/DisplayHeadingSup/DisplayHeadingSup.jsx index 3f6f9c7cb7..2434567163 100644 --- a/src/components/Typography/DisplayHeading/DisplayHeadingSup/DisplayHeadingSup.jsx +++ b/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 `` element. * * new! v0.22.0 * diff --git a/src/components/Typography/DisplayHeading/DisplayHeadingSup/DisplayHeadingSup.md b/src/components/Typography/DisplayHeading/DisplayHeadingSup/DisplayHeadingSup.md index 1640accc07..c90a2eb20d 100644 --- a/src/components/Typography/DisplayHeading/DisplayHeadingSup/DisplayHeadingSup.md +++ b/src/components/Typography/DisplayHeading/DisplayHeadingSup/DisplayHeadingSup.md @@ -1,7 +1,5 @@ -### Usage - -The Display Heading Sup component wraps text in a `` tag. It assures proper font sizes are rendered depending on the parent font size. - ``` - Great Deals1 + + TELUS Optik TV® + ``` diff --git a/src/components/Typography/Heading/Heading.jsx b/src/components/Typography/Heading/Heading.jsx index 1519fe4ff5..a79c85e552 100644 --- a/src/components/Typography/Heading/Heading.jsx +++ b/src/components/Typography/Heading/Heading.jsx @@ -18,7 +18,7 @@ const getClassName = (level, invert) => { } /** - * Used for page headings. + * Page headings. Renders an HTML `` element. * * new! v0.22.0 */ @@ -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 } diff --git a/src/components/Typography/Heading/Heading.md b/src/components/Typography/Heading/Heading.md index 395f2025c7..eac441eeb8 100644 --- a/src/components/Typography/Heading/Heading.md +++ b/src/components/Typography/Heading/Heading.md @@ -1,35 +1,15 @@ -### Minimal Usage - -The Heading component outputs an `h1` tag by default. - ``` -Great Deals +
+ Heading level 1 + Heading level 2 + Heading level 3 + Heading level 4 +
``` #### 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 - -``` -
- Great Deals - Great Deals - Great Deals - Great Deals -
-``` - -### Invert on dark colours - -``` -const PurpleBlock = require('../../__docs__/PurpleBlock').default; - - - Great Deals - -``` +- For Hero overlays, Headlines, or Promo blocks, use [`DisplayHeading`](#displayheading). diff --git a/src/components/Typography/Heading/HeadingSup/HeadingSup.jsx b/src/components/Typography/Heading/HeadingSup/HeadingSup.jsx index e1c2caf910..2911ebca9e 100644 --- a/src/components/Typography/Heading/HeadingSup/HeadingSup.jsx +++ b/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 `` element. * * new! v0.22.0 * diff --git a/src/components/Typography/Heading/HeadingSup/HeadingSup.md b/src/components/Typography/Heading/HeadingSup/HeadingSup.md index 614f3252a3..4ee332273d 100644 --- a/src/components/Typography/Heading/HeadingSup/HeadingSup.md +++ b/src/components/Typography/Heading/HeadingSup/HeadingSup.md @@ -1,23 +1,8 @@ -### Usage - -The Heading Sup component wraps text in a `` 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.** - - ```
-
- Optik TV® - Optik TV® - Optik TV® - Optik TV® -
-
- TELUS Pik TV™ - TELUS Pik TV™ - TELUS Pik TV™ - TELUS Pik TV™ -
+ TELUS Pik TV™ + TELUS Pik TV™ + TELUS Pik TV™ + TELUS Pik TV™
``` diff --git a/src/components/Typography/Heading/__tests__/Heading.spec.jsx b/src/components/Typography/Heading/__tests__/Heading.spec.jsx index 7f02016d3f..dc4a697a8b 100644 --- a/src/components/Typography/Heading/__tests__/Heading.spec.jsx +++ b/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( - Go home + Go home ) it('renders', () => { diff --git a/src/components/Typography/Typography.md b/src/components/Typography/Typography.md index e3fc850dd1..caf8e7a1e8 100644 --- a/src/components/Typography/Typography.md +++ b/src/components/Typography/Typography.md @@ -1,16 +1,23 @@ -Typography components replace standard HTML dom (preferring `` over ``) in order to provide maintainable font sizes and styles. +Typography components replace standard HTML dom (`` instead of `

`) 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 `` component immediately following a `` component would require `1rem` spacing between them. For this case, we recommend: +For example, a `` component immediately following a `` component would require `1rem` spacing between +them. For this case, we recommend: ```

- Great Deals + Great Deals +
- See how this great deal can benefit you and your shared lines. + + See how this great deal can benefit you and your shared lines. +
```