docs(a11y): Add a11y docs to button, button toggle, checkbox, progress spinner/ba… (#6402)

* Add a11y docs to button, button toggle, checkbox, progress spinner/bar, radio button and grid list

* address comments

* address comments

* address comments

* fix typo

src/lib/button-toggle/button-toggle.md

@@ -15,8 +15,15 @@ mode the values of the the toggles are not used, the `md-button-toggle-group` do
 and `ngModel` is not supported.
 
 ### Accessibility
-The button-toggles will present themselves as either checkboxes or radio-buttons based on the 
+The button-toggles will present themselves as either checkboxes or radio-buttons based on the
 presence of the `multiple` attribute. 
 
+For button toggles containing only icons, each button toggle should be given a meaningful label via
+`aria-label` or `aria-labelledby`.
+
+For button toggle groups, each group should be given a meaningful label via `aria-label` or
+`aria-labelledby`.
+
+
 ### Orientation
 The button-toggles can be rendered in a vertical orientation by adding the `vertical` attribute.

src/lib/button/button.md

@@ -31,3 +31,12 @@ to capitalize buttons automatically via `text-transform: uppercase`, because it
 certain locales. It is also worth noting that using ALL CAPS in the text itself causes issues for
 screen-readers, which will read the text character-by-character. We leave the decision of how to
 approach this to the consuming app.
+
+### Accessibility
+Angular Material uses native `<button>` and `<a>` elements to ensure an accessible experience by
+default. The `<button>` element should be used for any interaction that _performs an action on the
+current page_. The `<a>` element should be used for any interaction that _navigates to another
+view_.
+
+Buttons or links containing only icons (such as `md-fab`, `md-mini-fab`, and `md-icon-button`) should
+be given a meaningful label via `aria-label` or `aria-labelledby`.

src/lib/checkbox/checkbox.md

@@ -26,3 +26,11 @@ remove the indeterminate state.
 ### Theming
 The color of a `<md-checkbox>` can be changed by using the `color` property. By default, checkboxes
 use the theme's accent color. This can be changed to `'primary'` or `'warn'`.  
+
+### Accessibility
+The `<md-checkbox>` uses an internal `<input type="checkbox">` to provide an accessible experience.
+This internal checkbox receives focus and is automatically labelled by the text content of the
+`<md-checkbox>` element.
+
+Checkboxes without text or labels should be given a meaningful label via `aria-label` or
+`aria-labelledby`.

src/lib/grid-list/grid-list.md

@@ -41,3 +41,12 @@ however, more rows will simply be added for it the tile to fill.
 
 A header and footer can be added to an `md-grid-tile` using the `md-grid-tile-header` and
 `md-grid-tile-footer` elements respectively.
+
+### Accessibility
+By default, the grid-list assumes that it will be used in a purely decorative fashion and thus sets
+no roles, ARIA attributes, or keyboard shortcuts. This is equivalent to having a sequence of `<div>`
+elements on the page. Any interactive content within the grid-list should be given an appropriate
+accessibility treatment based on the specific workflow of your application.
+
+If the grid-list is used to present a list of _non-interactive_ content items, then the grid-list
+element should be given `role="list"` and each tile should be given `role="listitem"`.

src/lib/progress-bar/progress-bar.md

@@ -28,3 +28,6 @@ In both "indeterminate" and "query" modes, the `value` property is ignored.
 ### Theming
 The color of a progress-bar can be changed by using the `color` property. By default, progress-bars
 use the theme's primary color. This can be changed to `'accent'` or `'warn'`.  
+
+### Accessibility
+Each progress bar should be given a meaningful label via `aria-label` or `aria-labelledby`.

src/lib/progress-spinner/progress-spinner.md

@@ -21,3 +21,6 @@ In "indeterminate" mode, the `value` property is ignored.
 ### Theming
 The color of a progress-spinner can be changed by using the `color` property. By default, 
 progress-spinners use the theme's primary color. This can be changed to `'accent'` or `'warn'`.
+
+### Accessibility
+Each progress spinner should be given a meaningful label via `aria-label` or `aria-labelledby`.

src/lib/radio/radio.md

@@ -27,3 +27,10 @@ Individual radio-buttons inside of a radio-group will inherit the `name` of the
 ### Use with `@angular/forms`
 `<md-radio-group>` is compatible with `@angular/forms` and supports both `FormsModule`
 and `ReactiveFormsModule`.
+
+### Accessibility
+The `<md-radio-button>` uses an internal `<input type="radio">` to provide an accessible experience.
+This internal radio button receives focus and is automatically labelled by the text content of the
+`<md-radio-button>` element.
+
+Radio button groups should should be given a meaningful label via `aria-label` or `aria-labelledby`.