fix(website): add button docs (#51)

* fix(website): add button docs

* fix: add storybook to anchor and header

* fix: link line break

packages/paste-website/src/components/shortcodes/component-header/index.tsx

@@ -19,10 +19,15 @@ const ComponentHeaderBasic: React.FC<{name: string}> = ({name}) => (
   </>
 );
 
+const ExternalLink = styled.a`
+  margin-right: ${themeGet('space.space20')};
+`;
+
 interface ComponentHeaderProps {
   children?: React.ReactElement;
   name: string;
   githubUrl: string;
+  storybookUrl: string;
   data?: [
     {
       node: {
@@ -50,7 +55,7 @@ const PackageLabel = styled.dt(getPackageItemStyles, {
   width: '80px',
 });
 
-const ComponentHeader: React.FC<ComponentHeaderProps> = ({name, githubUrl, data}) => {
+const ComponentHeader: React.FC<ComponentHeaderProps> = ({name, githubUrl, storybookUrl, data}) => {
   if (data == null || data[0] == null || data[0].node == null) {
     return <ComponentHeaderBasic name={name} />;
   }
@@ -72,7 +77,8 @@ const ComponentHeader: React.FC<ComponentHeaderProps> = ({name, githubUrl, data}
         <Box mb="space20">
           <PackageLabel>Sources</PackageLabel>
           <PackageValue>
-            <a href={githubUrl}>Github</a>
+            <ExternalLink href={githubUrl}>Github</ExternalLink>
+            {storybookUrl != null ? <ExternalLink href={storybookUrl}>Storybook</ExternalLink> : null}
           </PackageValue>
         </Box>
         <Box mb="space20">

packages/paste-website/src/pages/components/anchor/index.mdx

@@ -26,6 +26,7 @@ export const pageQuery = graphql`
 <ComponentHeader
   name={props.pageContext.frontmatter.title}
   githubUrl="https://github.com/twilio-labs/paste/tree/master/packages/paste-core/components/anchor"
+  storybookUrl="https://twilio-labs.github.io/paste/?path=/story/components-anchor--default"
   data={props.data.allPasteComponent.edges}
 />
 
@@ -119,6 +120,12 @@ import {Anchor} from '@twilio-paste/anchor';
 </Anchor>`}
 </LivePreview>
 
+
+### Storybook
+
+[View Anchor in Storybook](https://twilio-labs.github.io/paste/?path=/story/components-anchor--default)
+
+
 ### Props
 
 | Prop           | Type                                   | Description                                                                         | Default   |

packages/paste-website/src/pages/components/button/index.mdx

@@ -6,6 +6,7 @@ description: Buttons are hot
 
 import {graphql} from 'gatsby';
 import {Button} from '@twilio-paste/button';
+import {DoDont, Do, Dont} from '../../../components/DoDont';
 
 export const pageQuery = graphql`
   {
@@ -25,16 +26,225 @@ export const pageQuery = graphql`
 <ComponentHeader
   name="Button"
   githubUrl="https://github.com/twilio-labs/paste/tree/master/packages/paste-core/components/button"
+  storybookUrl="https://twilio-labs.github.io/paste/?path=/story/components-button--text-only"
   data={props.data.allPasteComponent.edges}
 />
 
-## Installation
+
+## Guidelines
+
+### About buttons
+
+A button communicates that users can trigger an action. Places you’d use 
+a button include:
+* Submitting a form
+* Closing a modal
+* Moving to the next step in a flow
+A button can contain an icon and/or text. See Composing a button below 
+for more detailed guidelines.
+
+
+### Button vs. Anchor (Link)
+
+**TL;DR** If pressing the trigger results in a URL change, or that resultant 
+page makes sense as a whole new browser tab use an **Anchor** element. 
+Everything else is a **Button**.
+
+It may not be immediately obvious but the semantic distinction between an 
+anchor and button HTML element is extremely important to learn. Without 
+realising it the decision can cause significant usability problems due to 
+the in-built behaviours, interactions and expectations that come with each. 
+
+For example, an anchor element will perform its action when clicked and 
+when the enter key is pressed. A button element will perform its action 
+when clicked and when the enter and spacebar keys are pressed. When 
+holding the control or command key an anchor will open a new browser 
+tab, a button will not.
+
+
+You should:
+
+* Use an **Anchor** when you are **navigating the user** to a new page or 
+place on the page
+* Use a **Button** when the user is **performing an action**. An action always 
+happens on the same page as the trigger
+
+If you need to link to content, you can use our [Anchor component](/components/anchor).
+
+
+### Accessibility
+
+For accessibility, the distinction becomes even more important, 
+especially for those who are using Assistive Technology (A.T.) such as 
+screen readers and dictation software. Here are some quick tips:
+
+* Correctly choosing between an anchor or button element will help inform A.T. 
+users what will happen next. Will I be taken to an entirely new page or will 
+something happen on the current page?
+* Choose button text that clearly describes the action that is about to happen
+* Don’t repeat the same button text on the same page. Try not to have 20 
+“edit” buttons, add clarifying text, even if it’s visually hidden, to 
+fully describe the action. E.g. “edit home address”, “add new phone number”
+* Don’t communicate with color alone. When choosing a destructive button, 
+make sure the button text also indicates the action is destructive
+* Try not to use anchors that look like buttons. Voice dictation users will 
+struggle with these as they may say “click button” but the software can’t 
+tell what the anchor looks like visually
+
+### Examples 
+
+
+<LivePreview scope={{Button}} language="jsx">
+  {`<div>
+  <Button variant="primary">
+    Submit
+  </Button>
+
+  <Button variant="secondary">
+    Submit
+  </Button>
+
+  <Button variant="destructive" size="small">
+    Submit
+  </Button>
+
+  <Button variant="link">
+    Submit
+  </Button>
+
+  <Button variant="destructive_link">
+    Submit
+  </Button>
+
+  <Button variant="reset" size="reset">
+    Submit
+  </Button>
+</div>`}
+</LivePreview>
+
+
+##### Primary button
+Use a primary button to indicate the most prominent action a customer would
+make on a screen. It should be a safe and if possible, reversible action 
+without much cost.
+
+Try to use only one primary button on a screen. Using multiple might be 
+distracting.
+
+
+##### Secondary button
+The secondary button is the most frequently used button.
+
+Use a secondary button to indicate an action that should be easy for a customer 
+to make but isn’t the most prominent on a screen. It should be a safe and if 
+possible, reversible action without much cost.
+
+##### Destructive button
+A destructive button indicates a destructive action, such as “Delete” or 
+“Remove”, that might be difficult to reverse. If possible, give users 
+the ability to undo the action, or at least, confirm the action.
+
+##### Icon-only button
+Use icon-only buttons sparingly.
+
+They should be used only in compact UI situations. Use an icon that can 
+only convey a single action.
+
+##### Link-style button
+Use link-style buttons when other types of buttons may be too distracting.
+
+##### Small button
+Use small buttons sparingly, only when needed for vertical density. 
+Guidelines for using variants in small buttons are the same as in 
+their default size.
+
+
+### States
+
+##### Loading
+Use the loading state if the action doesn’t happen instantly. 
+The button is also disabled in this state.
+
+However, the loading state may make an action appear to take longer 
+than it does and doesn’t communicate what’s preventing the action 
+from completing. Use it when you can’t move the user to the next state.
+
+##### Disabled
+Use the disabled state sparingly.
+
+The customer shouldn't have to guess why a button is disabled. 
+It should be immediately obvious to the customer why a button 
+might be disabled (*e.g.*, if it follows a single empty text 
+field). Otherwise, show the button in its default state, then 
+provide helpful error text after it's pressed.
+
+
+
+### Composing a button
+In most cases, you’ll use a text-only button.
+
+Button text should:
+* Use sentence case (“Log in”, not “Log In”)
+* Clearly indicate what’ll happen when a user presses it.
+* Start with a verb, except for a common action like “Done.”
+* Be concise without sacrificing clarity and user confidence.
+
+Pair text with an icon only if the icon clarifies the meaning of 
+the button. Use no more than one icon before text and one icon after text.
+
+
+### When to use a button
+Use a button to indicate that users can trigger an action.
+
+In general, align buttons to the direction of the text (*e.g.*, 
+left-aligned in English) for easy scannability.
+
+When moving customers through a sequence, place the primary button in 
+the direction of the movement (e.g., a “Next” button goes on the 
+right in an English-language flow).
+
+
+<DoDont>
+  <Do>
+    Prioritize actions on a screen. Only one primary button should be used 
+    on each screen so users are clear about what the intended action is.
+  </Do>
+  <Dont>
+    Don’t use many primary buttons on a screen, which may distract users.
+  </Dont>
+</DoDont>
+
+<DoDont>
+  <Do>
+    Use the right variant to communicate meaning and hierarchy.
+  </Do>
+  <Dont>
+    Don’t use a button variant for an action it’s not intended for.
+  </Dont>
+</DoDont>
+
+
+<DoDont>
+  <Do>
+    Write button text that is clear, starts with a verb, and 
+    helps users confidently trigger an action.
+  </Do>
+  <Dont>
+    Don’t use product or brand icons in buttons since they don’t communicate action.
+  </Dont>
+</DoDont>
+
+
+
+## API
+
+### Installation
 
 ```bash
 yarn add @twilio-paste/button
 ```
 
-## Usage
+### Usage
 
 ```jsx
 import {Button} from '@twilio-paste/button';
@@ -44,11 +254,9 @@ import {Button} from '@twilio-paste/button';
 </Button>
 ```
 
-<LivePreview scope={{Button}} language="jsx">
-  {`<Button onClick={() => {console.log('clicked!')}} variant="secondary" size="small">
-  Submit
-</Button>`}
-</LivePreview>
+### Storybook
+
+[View Button in Storybook](https://twilio-labs.github.io/paste/?path=/story/components-button--text-only)
 
 ### Props
 

packages/paste-website/src/pages/components/index.mdx

@@ -18,19 +18,14 @@ import {Breadcrumb, BreadcrumbItem} from '../../components/breadcrumb';
   Components
 </Heading>
 
-<P>
-  The components listed here are on our roadmap.  Only a few of them are available today.
-</P>
-
-<P>
-  If you’re planning on using an alpha or beta component, please check in with the Paste team through the <strong>#help-design-system</strong> channel on Slack.
-</P>
-
-<P>
-  Don't see a component you need listed here? <Anchor href="https://github.com/twilio-labs/paste/issues">Create an issue on GitHub</Anchor>, and we'll evaluate it. Not all component
-  requests are accepted for the design system. We’ll have guidelines soon for what to do if your component isn’t
-  supported.
-</P>
+The components listed here are on our roadmap.  Only a few of them are available today.
+
+If you’re planning on using an alpha or beta component, please check in with the Paste team through the <strong>#help-design-system</strong> channel on Slack.
+
+Don't see a component you need listed here? [Create an issue on GitHub](https://github.com/twilio-labs/paste/issues), and we'll evaluate it. Not all component
+requests are accepted for the design system. We’ll have guidelines soon for what to do if your component isn’t
+supported.
+
 
 <ComponentOverviewTable componentsList={props.data.allPasteComponent.edges} />