diff --git a/src/lib/autocomplete/autocomplete.md b/src/lib/autocomplete/autocomplete.md index b3e7e4ece279..cee71e488c8d 100644 --- a/src/lib/autocomplete/autocomplete.md +++ b/src/lib/autocomplete/autocomplete.md @@ -95,3 +95,10 @@ desired display value. Then bind it to the autocomplete's `displayWith` property ``` + +### Accessibility +The input for autocomplete without text or labels should be given a meaningful label via +`aria-label` or `aria-labelledby`. + +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. diff --git a/src/lib/chips/chips.md b/src/lib/chips/chips.md index 58727d319162..7ae60fe5523c 100644 --- a/src/lib/chips/chips.md +++ b/src/lib/chips/chips.md @@ -38,3 +38,7 @@ also gain focus when clicked, ensuring keyboard navigation starts at the appropr The selected color of an `` can be changed by using the `color` property. By default, chips use a neutral background color based on the current theme (light or dark). This can be changed to `'primary'`, `'accent'`, or `'warn'`. + +### Accessibility +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`. diff --git a/src/lib/dialog/dialog.md b/src/lib/dialog/dialog.md index 0df81ac0ec1a..f2d42df5f1cd 100644 --- a/src/lib/dialog/dialog.md +++ b/src/lib/dialog/dialog.md @@ -126,3 +126,22 @@ that the AOT compiler knows to create the `ComponentFactory` for it. }) export class AppModule() {} ``` + +### Accessibility +By default, each dialog has `role="dialog"` on the root element. The role can be changed to +`alertdialog` via the `MdDialogConfig` when opening. + +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. diff --git a/src/lib/expansion/expansion.md b/src/lib/expansion/expansion.md index c228a9784b36..14ad08aaacee 100644 --- a/src/lib/expansion/expansion.md +++ b/src/lib/expansion/expansion.md @@ -98,3 +98,12 @@ panel can be expanded at a given time: ``` + +### Accessibility +The expansion-panel aims to mimic the experience of the native `
` and `` 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. Because the header acts as a button, +additional interactive elements should not be put inside of the header. diff --git a/src/lib/input/input.md b/src/lib/input/input.md index d131cfb760b2..e3626c1fa6d4 100644 --- a/src/lib/input/input.md +++ b/src/lib/input/input.md @@ -150,3 +150,13 @@ Here are the available global options: | Name | Type | Description | | ----------------- | -------- | ----------- | | errorStateMatcher | Function | Returns a boolean specifying if the error should be shown | + +### Accessibility +The `mdInput` directive works with native `` to provide an accessible experience. + +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 `