docs(a11y): add accessibility sections to datepicker, menu, slide … (a…

…ngular#6710)

src/lib/datepicker/datepicker.md

@@ -229,3 +229,52 @@ application root module.
 })
 export class MyApp {}
 ```
+### Accessibility
+The `MdDatepickerInput` directive adds `aria-haspopup` attribute to the native input element, and it
+triggers a calendar dialog with `role="dialog"`.
+
+`MdDatepickerIntl` includes strings that are used for `aria-label`s. The datepicker input
+should have a placeholder or be given a meaningful label via `aria-label`, `aria-labelledby` or
+`MdDatepickerIntl`.
+
+#### Keyboard shortcuts
+The keyboard shortcuts to handle datepicker are:
+
+| Shortcut             | Action                              |
+|----------------------|-------------------------------------|
+| `ALT` + `DOWN_ARROW` | Open the calendar pop-up            |
+| `ESCAPE`             | Close the calendar pop-up           |
+
+
+In month view:
+
+| Shortcut             | Action                              |
+|----------------------|-------------------------------------|
+| `LEFT_ARROW`         | Go to previous day                  |
+| `RIGHT_ARROW`        | Go to next day                      |
+| `UP_ARROW`           | Go to same day in the previous week |
+| `DOWN_ARROW`         | Go to same day in the next week     |
+| `HOME`               | Go to the first day of the month    |
+| `END`                | Go to the last day of the month     |
+| `PAGE_UP`            | Go to previous month                |
+| `ALT` + `PAGE_UP`    | Go to previous year                 |
+| `PAGE_DOWN`          | Go to next month                    |
+| `ALT` + `PAGE_DOWN`  | Go to next year                     |
+| `ENTER`              | Select current date                 |
+
+
+In year view:
+
+| Shortcut             | Action                              |
+|----------------------|-------------------------------------|
+| `LEFT_ARROW`         | Go to previous month                |
+| `RIGHT_ARROW`        | Go to next month                    |
+| `UP_ARROW`           | Go to previous 6 months             |
+| `DOWN_ARROW`         | Go to next 6 months                 |
+| `HOME`               | Go to the first month of the year   |
+| `END`                | Go to the last month of the year    |
+| `PAGE_UP`            | Go to previous year                 |
+| `ALT` + `PAGE_UP`    | Go to previous 10 years             |
+| `PAGE_DOWN`          | Go to next year                     |
+| `ALT` + `PAGE_DOWN`  | Go to next 10 years                 |
+| `ENTER`              | Select current month                |

src/lib/menu/menu.md

@@ -98,3 +98,7 @@ that should trigger the sub-menu:
 - <kbd>RIGHT_ARROW</kbd>: Opens the menu item's sub-menu
 - <kbd>LEFT_ARROW</kbd>: Closes the current menu, if it is a sub-menu.
 - <kbd>ENTER</kbd>: Activates the focused menu item
+
+### Accessibility
+Menu triggers or menu items without text or labels should be given a meaningful label via
+`aria-label` or `aria-labelledby`.

src/lib/slide-toggle/slide-toggle.md

@@ -22,3 +22,11 @@ and `ReactiveFormsModule`.
 ### Theming
 The color of a `<md-slide-toggle>` can be changed by using the `color` property. By default, 
 slide-toggles use the theme's accent color. This can be changed to `'primary'` or `'warn'`.  
+
+### Accessibility
+The `<md-slide-toggle>` 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-slide-toggle>` element.
+
+Slide toggles without text or labels should be given a meaningful label via `aria-label` or
+`aria-labelledby`.

src/lib/slider/slider.md

@@ -85,3 +85,7 @@ The slider has the following keyboard bindings:
 | Page down   | Decrement the slider value by 10 steps.                                            |
 | End         | Set the value to the maximum possible.                                             |
 | Home        | Set the value to the minimum possible.                                             |
+
+### Accessibility
+Sliders without text or labels should be given a meaningful label via `aria-label` or
+`aria-labelledby`.

src/lib/snack-bar/snack-bar.md

@@ -72,3 +72,8 @@ export class MessageArchivedComponent {
   constructor(@Inject(MD_SNACK_BAR_DATA) public data: any) { }
 }
 ```
+### Accessibility
+Snack-bar messages are announced via an `aria-live` region. Focus is not moved to
+the snack-bar element, as this would be disruptive to a user in the middle of a
+workflow. For any action offered in the snack-bar, the application should offer the
+user an alternative way to perform the action (typically via keyboard shortcut).

src/lib/toolbar/toolbar.md

@@ -49,3 +49,13 @@ easily accomplished with `display: flex`:
 The color of a `<md-toolbar>` can be changed by using the `color` property. By default, toolbars
 use a neutral background color based on the current theme (light or dark). This can be changed to 
 `'primary'`, `'accent'`, or `'warn'`.  
+
+### Accessibility
+By default, the toolbar 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.
+
+Generally, the toolbar is used as a header where `role="header"` would be appropriate.
+
+Only if the use-case of the toolbar match that of role="toolbar", the user should add the role and
+an appropriate label via `aria-label` or `aria-labelledby`.