Button and link a11y docs

UNRELEASED.md

@@ -26,8 +26,8 @@ Use [the changelog guidelines](https://git.io/polaris-changelog-guidelines) to f
 
 ### Documentation
 
+- Added accessibility documentation for the button and link components ([#924](https://github.com/Shopify/polaris-react/pull/924))
 - Added accessibility recommendations for the text field and autocomplete components ([#968](https://github.com/Shopify/polaris-react/pull/968))
-- Added all props example to `Card` in the [style guide](https://polaris.shopify.com) ([#939](https://github.com/Shopify/polaris-react/pull/939))
 
 ### Development workflow
 

src/components/Button/README.md

@@ -30,7 +30,7 @@ keywords:
 
 # Button
 
-Buttons are used to make common actions immediately visible and easy to perform with one click or tap. Merchants can use it to navigate, or take action.
+Buttons are used to make common actions immediately visible and easy to perform with one click, tap, or keypress. Merchants can use them to navigate or to take action.
 
 ---
 
@@ -289,3 +289,129 @@ Use when a button has been pressed and the associated action is in progress.
 
 - To learn how to combine or lay out multiple buttons, [use the button group component](/components/actions/button-group)
 - To embed an action into a line of text, [use the link component](/components/navigation/link)
+
+---
+
+## Accessibility
+
+<!-- content-for: android -->
+
+See Material Design and development documentation about accessibility for Android:
+
+- [Accessible design on Android](https://material.io/design/usability/accessibility.html)
+- [Accessible development on Android](https://developer.android.com/guide/topics/ui/accessibility/)
+
+<!-- /content-for -->
+
+<!-- content-for: ios -->
+
+See Apple’s Human Interface Guidelines and API documentation about accessibility for iOS:
+
+- [Accessible design on iOS](https://developer.apple.com/design/human-interface-guidelines/ios/app-architecture/accessibility/)
+- [Accessible development on iOS](https://developer.apple.com/accessibility/ios/)
+
+<!-- /content-for -->
+
+<!-- content-for: web -->
+
+Buttons can have different states that are visually and programmatically conveyed to merchants.
+
+- Use the `ariaControls` prop to add an `aria-controls` attribute to the button. Use the attribute to point to the unique `id` of the content that the button manages.
+- If a button expands or collapses adjacent content, then use the `ariaExpanded` prop to add the `aria-expanded` attribute to the button. Set the value to convey the current expanded (`true`) or collapsed (`false`) state of the content.
+- Use the `disabled` prop to set the `disabled` state of the button. This prevents merchants from being able to interact with the button, and conveys its inactive state to assistive technologies.
+- Use the `pressed` prop to add an `aria-pressed` attribute and enable a pressed style to the button.
+
+#### Navigation
+
+Merchants generally expect buttons to submit data or take action, and for links to navigate. If navigation is required for the button component, use the `url` prop. The control will output an anchor styled as a button, instead of a button in HTML, to help convey this difference.
+
+For more information on making accessible links, see the [link component](/components/navigation/link).
+
+### Labeling
+
+The `accessibilityLabel` prop adds an `aria-label` attribute to the button, which can be accessed by assistive technologies like screen readers. Typically, this label text replaces the visible text on the button for merchants who use assistive technology.
+
+Use `accessibilityLabel` for a button if:
+
+- The button’s visible text doesn’t adequately convey the purpose of the button to non-visual merchants
+- The button has no text and relies on an icon alone to convey its purpose
+
+To help support merchants who use speech activation software as well as sighted screen reader users, make sure that the `aria-label` text includes any button text that’s visible. Mismatches between visible and programmatic labeling can cause confusion, and might prevent voice recognition commands from working.
+
+When possible, give the button visible text that clearly conveys its purpose without the use of `accessibilityLabel`. When no additional content is needed, duplicating the button text with `accessibilityLabel` isn’t necessary.
+
+<!-- usageblock -->
+
+#### Do
+
+```jsx
+<Button>Edit shipping address</Button>
+```
+
+```jsx
+<Heading>Shipping address</Heading>
+<Button accessibilityLabel="Edit shipping address">Edit</Button>
+```
+
+#### Don’t
+
+```jsx
+<Button accessibilityLabel="Change your shipping address">Edit</Button>
+```
+
+```jsx
+<Button accessibilityLabel="Edit">Edit</Button>
+```
+
+<!-- end -->
+
+#### External links
+
+When you use the button component to create a link to an external resource:
+
+- Use the `external` prop to make the link open in a new tab (or window, depending on the merchant’s browser settings)
+- Use the `icon` prop to add the `external` icon to the button
+- Use the `accessibilityLabel` prop to include the warning about opening a new tab in the button text for non-visual screen reader users
+
+For more information on making accessible links, see the [link component](/components/navigation/link).
+
+<!-- usageblock -->
+
+#### Do
+
+```jsx
+<Button
+  accessibilityLabel="Terms and conditions (opens a new window)"
+  icon="external"
+  url="http://example.com"
+  external
+>
+  Terms and conditions
+</Button>
+```
+
+#### Don’t
+
+```jsx
+<Button url="http://example.com" external>Terms and conditions</Button>
+<Button url="http://example.com" external>
+  Terms and conditions
+</Button>
+```
+
+<!-- end -->
+
+### Keyboard support
+
+Buttons use browser defaults for keyboard interactions.
+
+- Give buttons keyboard focus with the <kbd>tab</kbd> key (or <kbd>shift</kbd> + <kbd>tab</kbd> when tabbing backwards)
+- Activate buttons with the <kbd>enter</kbd>/<kbd>return</kbd> key or the <kbd>space</kbd> key
+
+#### Custom key events
+
+Use the `onKeyDown`, `onKeyPress`, and `onKeyUp` props to create custom events for buttons. With these props, you can use buttons to create complex, custom interactions like drag-and-drop interfaces.
+
+Since these props introduce non-standard features to buttons, make sure to include accessible instructions so that merchants can understand how to use these features.
+
+<!-- /content-for -->

src/components/Link/README.md

@@ -97,3 +97,68 @@ Use for text links that are the same color as the surrounding text.
 ## Related components
 
 - To create navigational actions that aren’t part of a line of text, [use the button component](/components/actions/button)
+
+---
+
+## Accessibility
+
+<!-- content-for: web -->
+
+Use the `url` prop to give the link component a valid `href` value. This allows the element to be identified as a link to assistive technologies and gives it default keyboard support.
+
+### Submitting data
+
+Merchants generally expect links to navigate, and not to submit data or take action. If you need a component that doesn’t have a URL associated with it, then use the [button component](/components/actions/button) instead.
+
+### Labeling
+
+Give links text that clearly describes their purpose.
+
+To provide consistency and clarity:
+
+- Use the same text for links that navigate to the same content
+- Use different text for links that navigate to different content
+
+<!-- usageblock -->
+
+#### Do
+
+```jsx
+<Link url="https://help.shopify.com/manual">fulfilling orders</Link>
+```
+
+#### Don’t
+
+```jsx
+<Link>fulfilling orders</Link>
+```
+
+#### Don’t
+
+```jsx
+<Link url="https://help.shopify.com/manual">fulfilling orders</Link>
+```
+
+```jsx
+<Link url="https://help.shopify.com/manual">order fulfillment section</Link>
+```
+
+<!-- end -->
+
+#### External links
+
+Use the `external` prop to make the link open in a new tab (or window, depending on the merchant’s browser settings). Open a page in a new tab only when opening a page in the same tab might disrupt the merchant’s workflow.
+
+To make the external link functionality clear to all merchants:
+
+- Use the [icon component](/components/images-and-icons/icon) to add the `external` icon to the link
+- Use the `accessibilityLabel` on the icon prop to include the warning about opening a new tab in the button text for non-visual screen reader users
+
+### Keyboard support
+
+Links use browser defaults for keyboard interaction.
+
+- Give links keyboard focus with the <kbd>tab</kbd> key (or <kbd>shift</kbd> + <kbd>tab</kbd> when tabbing backwards)
+- Activate links with the <kbd>enter</kbd>/<kbd>return</kbd> key
+
+<!-- /content-for -->