address comments

Author: tinayuangao

src/lib/autocomplete/autocomplete.md

@@ -100,5 +100,5 @@ desired display value. Then bind it to the autocomplete's `displayWith` property
 The input for autocomplete without text or labels should be given a meaningful label via
 `aria-label` or `aria-labelledby`.
 
-Autocomplete trigger sets `aria-owns` to the autocomplete's id, and sets `aria-activedescendant` to
-the active option's id.
+Autocomplete trigger is given `role="combobox"`. The trigger sets `aria-owns` to the autocomplete's
+id, and sets `aria-activedescendant` to the active option's id.

src/lib/chips/chips.md

@@ -40,5 +40,5 @@ use a neutral background color based on the current theme (light or dark). This
 `'primary'`, `'accent'`, or `'warn'`.
 
 ### Accessibility
-Chips have role="option", while the chip list has `role="listbox"`. The chip input should have a
-placeholder or be given a meaningful label via `aria-label` or `aria-labelledby`.
+A chip-list behaves as a `role="listbox"`, with each chip being a `role="option"`. The chip input
+should have a placeholder or be given a meaningful label via `aria-label` or `aria-labelledby`.

src/lib/dialog/dialog.md

@@ -128,8 +128,20 @@ export class AppModule() {}
 ```
 
 ### Accessibility
-The dialog has `role="dialog"`, and dialog role can be overwritten to `alertdialog` in the
-appropriate context.
+By default, each dialog has `role="dialog"` on the root element. The role can be changed to
+`alertdialog` via the `MdDialogConfig` when opening.
 
-The dialog will focus on the first tabbable element when opened,
-and restore focus to the element that was focused before the dialog opened when closed.
+The `aria-label`, `aria-labelledby`, and `aria-describedby` attributes can all be set to the
+dialog element via the `MdDialogConfig` as well. Each dialog should typically have a label
+set via `aria-label` or `aria-labelledby`.
+
+#### Focus management
+By default, the first tabbable element within the dialog will receive focus upon open.
+
+Tabbing through the elements of the dialog will keep focus inside of the dialog element,
+wrapping back to the first tabbable element when reaching the end of the tab sequence.
+
+#### Keyboard interaction
+By default pressing the escape key will close the dialog. While this behavior can
+be turned off via the `disableClose` option, users should generally avoid doing so
+as it breaks the expected interaction pattern for screen-reader users.

src/lib/expansion/expansion.md

@@ -100,8 +100,10 @@ panel can be expanded at a given time:
 ```
 
 ### Accessibility
+The expansion-panel aims to mimic the experience of the native `<details>` and `<summary>` elements.
 The expansion panel header has `role="button"`. The expansion panel header has attribute
 `aria-controls` with the expansion panel's id as value.
 
 The expansion panel headers are buttons. Users can use the keyboard to activate the expansion panel
-header to switch between expanded state and collapsed state.
+header to switch between expanded state and collapsed state. Because the header acts as a button,
+additional interactive elements should not be put inside of the header.

src/lib/input/input.md

@@ -154,7 +154,7 @@ Here are the available global options:
 ### Accessibility
 The `mdInput` directive works with native `<input>` to provide an accessible experience.
 
-If a placeholder attributed is added to the input, or a `md-placeholder` element is added
+If a placeholder attribute is added to the input, or a `md-placeholder` element is added
 in the form field, the placeholder text will automatically be used as the label for the input.
 If there's no placeholder specified, `aria-label`, `aria-labelledby` or `<label for=...>` should be
 added.

src/lib/table/table.md

@@ -48,6 +48,9 @@ and selection).
 
 ### Accessibility
 Tables without text or labels should be given a meaningful label via `aria-label` or
-`aria-labelledby`.
+`aria-labelledby`. The `aria-readonly` defaults to `true` if it's not set.
 
-Table's default role is 'grid', and it can be changed through `role` attribute.
+Table's default role is `grid`, and it can be changed to `treegrid` through `role` attribute.
+
+`md-table` does not manage any focus/keyboard interaction on its own. Users can add desired
+focus/keyboard interactions in their application.

src/lib/tabs/tabs.md

@@ -81,5 +81,14 @@ the `active` property to determine which tab is currently active. The correspond
 `<router-outlet>` can be placed anywhere in the view.
 
 ### Accessibility
-`MdTabNav`s without text or labels should be given a meaningful label via `aria-label` or
-`aria-labelledby`.
+Tabs without text or labels should be given a meaningful label via `aria-label` or
+`aria-labelledby`. For `MdTabNav`, the `<nav>` element should have a label as well.
+
+
+#### Keyboard shortcuts
+
+| Shortcut             | Action                     |
+|----------------------|----------------------------|
+| `LEFT_ARROW`         | Move focus to previous tab |
+| `RIGHT_ARROW`        | Move focus to next tab     |
+| `SPACE` or 'ENTER'   | Switch to focused tab      |