docs(button): add prop docs

packages/react/src/components/Button/Button.js

@@ -107,6 +107,7 @@ Button.propTypes = {
     PropTypes.string,
     PropTypes.elementType,
   ]),
+
   /**
    * Specify the content of your Button
    */
@@ -205,6 +206,8 @@ Button.defaultProps = {
   disabled: false,
   kind: 'primary',
   size: 'default',
+  tooltipAlignment: 'center',
+  tooltipPosition: 'top',
 };
 
 export default Button;

packages/react/src/components/Button/Button.mdx

@@ -2,7 +2,7 @@ import { Story, Props, Source, Preview } from '@storybook/addon-docs/blocks';
 import { withKnobs, boolean, select, text } from '@storybook/addon-knobs';
 import * as stories from './Button-story.js';
 import Button from '../Button';
-import { Add16, AddFilled16, Search16 } from '@carbon/icons-react';
+import { Add16, Delete16 } from '@carbon/icons-react';
 
 # Button
 
@@ -46,8 +46,7 @@ buttons.
 When an action required by the user has more than one option, always use a a
 negative action `Button` (secondary) paired with a positive action `Button`
 (primary) in that order. Negative action buttons will be on the left. Positive
-action buttons should be on the right. When these two types buttons are paired
-in the correct order, they will automatically space themselves apart.
+action buttons should be on the right.
 
 <Preview>
   <Story id="button--set-of-buttons" />
@@ -56,7 +55,7 @@ in the correct order, they will automatically space themselves apart.
 ## Skeleton state
 
 You can use the `ButtonSkeleton` component to render a skeleton variant of a
-button. This is useful to display on initial page load to indicate tousers that
+button. This is useful to display on initial page load to indicate to users that
 content is being loaded.
 
 <Preview>
@@ -73,11 +72,12 @@ button element.
 ### Button `as`
 
 This prop allows you to specify a different element to be rendered as a
-`Button`.
+`Button`. You may also need to add a [role](#button-role) for accessibility if
+an element other than a `button` is rendered.
 
 ```jsx
-<Button as="a" href="https://www.carbondesignsystem.com/">
-  Navigate
+<Button as="div" role="button">
+  I'm a div tag
 </Button>
 ```
 
@@ -91,6 +91,112 @@ for layout.
 <Button className="custom-class">Submit</Button>
 ```
 
+### Button `hasIconOnly`
+
+Use this prop to render the icon-only variant of `Button`. First you'll pass in
+the `renderIcon` prop to tell the `Button` which icon to render. Next, you'll
+need to specify the `iconDescription` ([read more](#button-icondescription)),
+which is used to populate the tooltip that is shown when the icon button is
+interacted with, as well as internal `aria-label` for screen-readers. Lastly,
+you can configure both the `tooltipAlignment`
+([read more](#button-tooltipalignment)) and `tooltipPosition`
+([read more](#button-tooltipposition)) props to tell the `Button` where your
+tooltip should be rendered. These props default to `center` and `bottom`,
+respectively.
+
+<Button hasIconOnly renderIcon={Add16} iconDescription="Add" />
+
+```jsx
+<Button hasIconOnly renderIcon={Add16} iconDescription="Add" />
+```
+
+### Button `href`
+
+This prop allows you to specify an address to navigate to on click. This will
+change the underlying `Button` element to be rendered as an `a` anchor element.
+
+<Button href="https://www.carbondesignsystem.com">Navigate</Button>
+
+```jsx
+<Button href="https://www.carbondesignsystem.com">Navigate</Button>
+```
+
+### Button `iconDescription`
+
+If using the `hasIconOnly` prop, `iconDescription` becomes a required prop for
+accessibility reasons. The text provided here populates the internal
+`aria-label` tag on the icon, as well as provides text to be shown when the icon
+button is interacted with.
+
+```jsx
+<Button hasIconOnly renderIcon={Add16} iconDescription="Add" />
+```
+
+### Button `kind`
+
+Carbon has five types of buttons, `primary`, `secondary`, `tertiary`, `ghost`,
+and `danger`. If no `kind` is specified, a `primary` button will be rendered.
+For more information on when to use each variant, check out the
+[design documentation](https://www.carbondesignsystem.com/components/button/usage#overview)
+
+<Button>Primary</Button> <Button kind="secondary">Secondary</Button> <Button kind="tertiary">
+  Tertiary{' '}
+</Button> <Button kind="danger">Danger</Button> <Button kind="ghost">
+  Ghost
+</Button>
+
+```jsx
+<Button>Primary</Button>
+<Button kind="secondary">Secondary</Button>
+<Button kind="tertiary">Tertiary</Button>
+<Button kind="danger">Danger</Button>
+<Button kind="ghost">Ghost</Button>
+```
+
+### Button `renderIcon`
+
+This prop is used to tell `Button` which icon should be rendered inside the
+button. Before you pass in the icon, you'll need to import the icon(s) you would
+like to render, like so:
+
+```js
+import { Add16, Delete16 } from '@carbon/icons-react';
+```
+
+Once the icons are imported, you can pass them directly in to the `Button`
+component. Keep in mind, you will also need to add an `iconDescription` to help
+with screen-reader support if you use the `renderIcon` prop. If you are trying
+to render icon-only buttons, please refer to the section on the
+[hasIconOnly](#button-hasicononly) prop
+
+<Button renderIcon={Add16} iconDescription="Add">
+  Add
+</Button> <Button renderIcon={Delete16} kind="danger" iconDescription="Delete">
+  Delete
+</Button>
+
+```jsx
+<Button renderIcon={Add16} iconDescription="Add">Add</Button>
+<Button renderIcon={Delete16} kind="danger"  iconDescription="Delete">Delete</Button>
+```
+
+### Button `role`
+
+If you use the [as](#button-as) prop to render a non-button as a button, you may
+need to add a `role` for accessibility reasons. Adding `role="button"` will make
+an element appear as a button control to a screen reader. Check out the
+[References](#references) section for more information.
+
+<Button as="div" role="button">
+  a11y Button
+</Button>
+
+```jsx
+<Button as="div" role="button">
+  a11y Button
+</Button>
+```
+
 ### Button `size`
 
 This prop specifies which size the `Button` should be rendered at. Valid values
@@ -107,14 +213,72 @@ are `field`, `small`, and `default`. If no `size` is specified, it renders as
 <Button size="small">Submit</Button>
 ```
 
+### Button `tooltipAlignment`
+
+The `tooltipAlignment` prop is used to change where the tooltip text and caret
+is rendered in relation to the `Button`. Accepted options are `start`, `center`,
+and `end`. The default alignment is `center`.
+
+<Button
+  hasIconOnly
+  renderIcon={Add16}
+  iconDescription="Add to selection"
+  tooltipAlignment="start"
+/> <Button hasIconOnly renderIcon={Add16} iconDescription="Add to selection" /> <Button
+  hasIconOnly
+  renderIcon={Add16}
+  iconDescription="Add to selection"
+  tooltipAlignment="end"
+/>
+
+```jsx
+<Button hasIconOnly renderIcon={Add16} iconDescription="Add to selection" tooltipAlignment="start" />
+<Button hasIconOnly renderIcon={Add16} iconDescription="Add to selection" />
+<Button hasIconOnly renderIcon={Add16} iconDescription="Add to selection" tooltipAlignment="end"/>
+```
+
+### Button `tooltipPosition`
+
+When using an icon-only button, you may be in a situation where you need to
+change where the tooltip is positioned on the screen. `tooltipPosition` takes in
+a position and will render the tooltip accordingly. Accepted options are `top`,
+`bottom`, `left`, and `right`. The default is position is `top`.
+
+<Button hasIconOnly renderIcon={Add16} iconDescription="Add" /> <Button
+  hasIconOnly
+  renderIcon={Add16}
+  iconDescription="Add"
+  tooltipPosition="right"
+/> <Button
+  hasIconOnly
+  renderIcon={Add16}
+  iconDescription="Add"
+  tooltipPosition="bottom"
+/> <Button
+  hasIconOnly
+  renderIcon={Add16}
+  iconDescription="Add"
+  tooltipPosition="left"
+/>
+
+```jsx
+<Button hasIconOnly renderIcon={Add16} iconDescription="Add" />
+<Button hasIconOnly renderIcon={Add16} iconDescription="Add" tooltipPosition="right"/>
+<Button hasIconOnly renderIcon={Add16} iconDescription="Add" tooltipPosition="bottom"/>
+<Button hasIconOnly renderIcon={Add16} iconDescription="Add" tooltipPosition="left" />
+```
+
 ## References
 
-<!--
-A place for references, links, or a way clarify points made earlier
-in the documentation.
--->
+- [MDN: ARIA button role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/button_role)
+- [W3: Role attribute](https://www.w3.org/WAI/PF/HTML/wiki/RoleAttribute)
+- [W3: ARIA button role example](https://www.w3.org/TR/2016/WD-wai-aria-practices-1.1-20160317/examples/button/button.html)
 
 ## Feedback
 
 Help us improve these docs by
 [editing this file on GitHub](https://github.com/carbon-design-system/carbon/edit/master/packages/react/src/components/Accordion/Accordion.stories.mdx)
+
+```
+
+```