docs(link): add button link

- move hero to docs helpers
- add tests
- adjust language in Button docs

src/components/Button/Button.md

@@ -1,18 +1,18 @@
 ## Minimal Usage
 
-Provide a function as the `onClick` prop to perform an action when clicked. **Avoid using a button if navigation 
+Provide a function as the `onClick` prop to perform an action when clicked. **Avoid using a button if navigation
 is the button's primary action, as a link is more appropriate.**
 
-### Recommendations
+### Usage Criteria
 
 * Use buttons to move though a transaction.
 * Aim to use only one button per page.
 * Avoid excessively long button text.
 * Make sure the button text describes an action.
-* Avoid disabling buttons. 
-* For buttons used in forms, use inline error messaging to provide feedback rather than a disabled button.
+* Buttons should not be disabled.
+* For buttons used in forms, use inline error messaging to provide feedback.
 
-By default, Buttons will be displayed in the `primary` variant. Use primary buttons for the main action on a page or 
+By default, Buttons will be displayed in the `primary` variant. Use primary buttons for the main action on a page or
 in a form.
 
 ```
@@ -27,7 +27,7 @@ Specify the `variant` to create a button for secondary actions.
 
 ## Sizes
 
-All buttons are inline, with a minimum width of 180px for screens larger than 768. They will occupy 100% width of their parent's at the small viewport and below. Resize your browser window to see this behaviour. 
+All buttons are inline, with a minimum width of 180px for screens larger than 768. They will occupy 100% width of their parent's at the small viewport and below. Resize your browser window to see this behaviour.
 
 
 ## Placing buttons on solid colours
@@ -41,19 +41,3 @@ const PurpleBlock = require('../__docs__/PurpleBlock').default;
   <Button variant="secondary" invert>Get started</Button>
 </PurpleBlock>
 ```
-
-## Placing buttons on images
-
-Use the `outlined` variant when placing a button on top of an image, which will cause the image to show through. You can 
-also `invert` the colour scheme.
-
-Use this variant with caution. There will be accessibility issues if the colour contrast of the image and the button text 
-is too low, including the hover state.
-
-```
-const Hero = require('./__docs__/Hero').default;
-
-<Hero>
-  <Button variant="outlined" invert>Advanced solutions</Button>
-</Hero>
-```

src/components/Link/ButtonLink/ButtonLink.jsx

@@ -24,12 +24,17 @@ const ButtonLink = ({ variant, invert, children, ...rest }) => {
   );
 };
 ButtonLink.propTypes = {
-  variant: PropTypes.oneOf([
-    'primary',
-    'secondary',
-    'outlined'
-  ]),
+  /**
+   * The style.
+   */
+  variant: PropTypes.oneOf(['primary', 'secondary', 'outlined']),
+  /**
+   * Whether or not to invert the variant's color scheme.
+   */
   invert: PropTypes.bool,
+  /**
+   * The label.
+   */
   children: PropTypes.string.isRequired
 };
 ButtonLink.defaultProps = {

src/components/Link/ButtonLink/ButtonLink.md

@@ -1,27 +1,32 @@
 ### Minimal Usage
 
-```
-<Link.Button>Find out how</Link.Button>
-```
+A Button Link is a navigational element that styles itself as a button. Clicking one should navigate to a new "page".
 
-### Variants
+By default, Buttons will be displayed in the `primary` variant. Use primary buttons for the main call to action on a page.
 
 ```
-const PurpleBlock = require('../../__docs__/PurpleBlock').default;
-
-<div>
-  <Link.Button variant="primary">Explore</Link.Button>
-  <Link.Button variant="secondary">Take me there</Link.Button>
-  <br/>
-  <br/>
-  <PurpleBlock>
-    <Link.Button variant="outlined">Find me</Link.Button>
-  </PurpleBlock>
-</div>
+<Link.Button href="http://www.telus.com">Find out how</Link.Button>
 ```
 
-### Inverted Button Links
+### Using Button Links
+
+All Button Links have the same visual appearance as [Button](#button), but are applied differently in certain contexts. Unlike the Button component, Button Link is more appropriate for:
+
+- Call to action
+- Placement atop a complex background such as an image
+
+#### Placing Button Links on images
+
+Use the `outlined` variant when placing a button on top of an image, which will cause the image to show through. You can
+also `invert` the colour scheme.
+
+Use this variant with caution. There will be accessibility issues if the colour contrast of the image and the button text
+is too low, including the hover state.
 
 ```
-<Link.Button invert>Learn more</Link.Button>
+const Hero = require('../../__docs__/Hero').default;
+
+<Hero>
+  <Button variant="outlined" invert>Advanced solutions</Button>
+</Hero>
 ```

src/components/Link/ButtonLink/__tests__/ButtonLink.spec.jsx

@@ -36,52 +36,52 @@ describe('Link.Button', () => {
   });
 
   it('can be presented as one of the allowed variants', () => {
-    let button = doShallow();
-    expect(button).toHaveClassName('primary');
+    let link = doShallow();
+    expect(link).toHaveClassName('primary');
 
-    button = doShallow({ variant: 'primary' });
-    expect(button).toHaveClassName('primary');
+    link = doShallow({ variant: 'primary' });
+    expect(link).toHaveClassName('primary');
 
-    button = doShallow({ variant: 'secondary' });
-    expect(button).toHaveClassName('secondary');
+    link = doShallow({ variant: 'secondary' });
+    expect(link).toHaveClassName('secondary');
 
-    button = doShallow({ variant: 'outlined' });
-    expect(button).toHaveClassName('outlined');
+    link = doShallow({ variant: 'outlined' });
+    expect(link).toHaveClassName('outlined');
   });
 
   it('can be inverted for secondary and outlined variants', () => {
-    const secondaryButton = doShallow({ variant: 'secondary', invert: true });
-    expect(secondaryButton).toHaveClassName('secondaryInverted');
+    const secondaryLink = doShallow({ variant: 'secondary', invert: true });
+    expect(secondaryLink).toHaveClassName('secondaryInverted');
 
-    const outlinedButton = doShallow({ variant: 'outlined', invert: true });
-    expect(outlinedButton).toHaveClassName('outlinedInverted');
+    const outlinedLink = doShallow({ variant: 'outlined', invert: true });
+    expect(outlinedLink).toHaveClassName('outlinedInverted');
   });
 
   it('can not be inverted for primary variant', () => {
-    const button = doShallow({ variant: 'primary', invert: true });
+    const link = doShallow({ variant: 'primary', invert: true });
 
-    expect(button).toHaveClassName('primary');
+    expect(link).toHaveClassName('primary');
     expect(warn).toHaveBeenCalled();
   });
 
   it('can not be disabled', () => {
-    const button = doShallow({ disabled: true });
+    const link = doShallow({ disabled: true });
 
-    expect(button).not.toHaveProp('disabled');
+    expect(link).not.toHaveProp('disabled');
     expect(warn).toHaveBeenCalled();
   });
 
-  it('passes additional attributes to button element', () => {
-    const button = doShallow({ id: 'the-button', tabindex: 1 });
+  it('passes additional attributes to rendered <a> element', () => {
+    const link = doShallow({ id: 'the-link', tabindex: 1 });
 
-    expect(button).toHaveProp('id', 'the-button');
-    expect(button).toHaveProp('tabindex', 1);
+    expect(link).toHaveProp('id', 'the-link');
+    expect(link).toHaveProp('tabindex', 1);
   });
 
   it('does not allow custom CSS', () => {
-    const button = doShallow({ className: 'my-custom-class', style: { color: 'hotpink' } });
+    const link = doShallow({ className: 'my-custom-class', style: { color: 'hotpink' } });
 
-    expect(button).not.toHaveProp('className', 'my-custom-class');
-    expect(button).not.toHaveProp('style');
+    expect(link).not.toHaveProp('className', 'my-custom-class');
+    expect(link).not.toHaveProp('style');
   });
 })

src/components/Button/__docs__/Hero.modules.scss → src/components/__docs__/Hero.modules.scss

@@ -1,4 +1,4 @@
-@import '../../../scss/settings/spacing';
+@import '../../scss/settings/spacing';
 
 .hero {
   display: flex;