From 36bf83346eb143a0e5b03a73e030e564282898bd Mon Sep 17 00:00:00 2001 From: Yuan Gao Date: Tue, 29 Aug 2017 16:21:21 -0700 Subject: [PATCH 1/5] docs(a11y): Adding accessibility sections to datepicker, menu, slide toggle, slider, snackbar and toolbar --- src/lib/datepicker/datepicker.md | 3 +++ src/lib/menu/menu.md | 4 ++++ src/lib/slide-toggle/slide-toggle.md | 8 ++++++++ src/lib/slider/slider.md | 4 ++++ src/lib/snack-bar/snack-bar.md | 4 ++++ src/lib/toolbar/toolbar.md | 4 ++++ 6 files changed, 27 insertions(+) diff --git a/src/lib/datepicker/datepicker.md b/src/lib/datepicker/datepicker.md index a0d624f8d01f..e917422c76ce 100644 --- a/src/lib/datepicker/datepicker.md +++ b/src/lib/datepicker/datepicker.md @@ -228,3 +228,6 @@ application root module. }) export class MyApp {} ``` +### Accessibility +The input box for datepicker should have a placeholder or be given a meaningful label via +`aria-label` or `aria-labelledby`. diff --git a/src/lib/menu/menu.md b/src/lib/menu/menu.md index ff082c83cc75..8a3969a1ed57 100644 --- a/src/lib/menu/menu.md +++ b/src/lib/menu/menu.md @@ -98,3 +98,7 @@ that should trigger the sub-menu: - RIGHT_ARROW: Opens the menu item's sub-menu - LEFT_ARROW: Closes the current menu, if it is a sub-menu. - ENTER: 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`. diff --git a/src/lib/slide-toggle/slide-toggle.md b/src/lib/slide-toggle/slide-toggle.md index 8364d85c96df..7f0ffc79fb52 100644 --- a/src/lib/slide-toggle/slide-toggle.md +++ b/src/lib/slide-toggle/slide-toggle.md @@ -22,3 +22,11 @@ and `ReactiveFormsModule`. ### Theming The color of a `` 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 `` uses an internal `` to provide an accessible +experience. This internal checkbox receives focus and is automatically labelled by the text content +of the `` element. + +Slide toggles without text or labels should be given a meaningful label via `aria-label` or +`aria-labelledby`. diff --git a/src/lib/slider/slider.md b/src/lib/slider/slider.md index b2b06ab4272b..d64fb7daf111 100644 --- a/src/lib/slider/slider.md +++ b/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`. diff --git a/src/lib/snack-bar/snack-bar.md b/src/lib/snack-bar/snack-bar.md index 5e2ac1b1fa2c..326048ab0517 100644 --- a/src/lib/snack-bar/snack-bar.md +++ b/src/lib/snack-bar/snack-bar.md @@ -72,3 +72,7 @@ export class MessageArchivedComponent { constructor(@Inject(MD_SNACK_BAR_DATA) public data: any) { } } ``` +### Accessibility +A Snackbar automatically goes away after a short time, so you can't count on the user seeing the +message or having a chance to press the button. For this reason, you should consider offering an +alternate way to perform any Snackbar action. diff --git a/src/lib/toolbar/toolbar.md b/src/lib/toolbar/toolbar.md index eb7189923d0f..1a86a417e91c 100644 --- a/src/lib/toolbar/toolbar.md +++ b/src/lib/toolbar/toolbar.md @@ -49,3 +49,7 @@ easily accomplished with `display: flex`: The color of a `` 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 +Toolbar items without text or labels should be given a meaningful label via `aria-label` or +`aria-labelledby`. From d61ae3252af067c92cee531d3e595062a0543e9d Mon Sep 17 00:00:00 2001 From: Yuan Gao Date: Tue, 29 Aug 2017 16:28:54 -0700 Subject: [PATCH 2/5] address comments --- src/lib/snack-bar/snack-bar.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/lib/snack-bar/snack-bar.md b/src/lib/snack-bar/snack-bar.md index 326048ab0517..0c48eb0ea901 100644 --- a/src/lib/snack-bar/snack-bar.md +++ b/src/lib/snack-bar/snack-bar.md @@ -73,6 +73,6 @@ export class MessageArchivedComponent { } ``` ### Accessibility -A Snackbar automatically goes away after a short time, so you can't count on the user seeing the +A snack-bar automatically goes away after a short time, so you can't count on the user seeing the message or having a chance to press the button. For this reason, you should consider offering an -alternate way to perform any Snackbar action. +alternate way to perform any snack-bar action. From 665cf7aaebe4076fa3e3a2d282935a6a85543bcf Mon Sep 17 00:00:00 2001 From: Yuan Gao Date: Wed, 30 Aug 2017 10:20:23 -0700 Subject: [PATCH 3/5] add docs for datepicker keyboard --- src/lib/datepicker/datepicker.md | 53 ++++++++++++++++++++++++++++++-- src/lib/snack-bar/snack-bar.md | 7 +++-- src/lib/toolbar/toolbar.md | 10 ++++-- 3 files changed, 63 insertions(+), 7 deletions(-) diff --git a/src/lib/datepicker/datepicker.md b/src/lib/datepicker/datepicker.md index e917422c76ce..d7188b26eeff 100644 --- a/src/lib/datepicker/datepicker.md +++ b/src/lib/datepicker/datepicker.md @@ -229,5 +229,54 @@ application root module. export class MyApp {} ``` ### Accessibility -The input box for datepicker should have a placeholder or be given a meaningful label via -`aria-label` or `aria-labelledby`. +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: + +`ALT` + `DOWN_ARROR`: trigger calendar dialog + +`ESCAPE`: close calendar dialog + + +In month view: + +`LEFT_ARROW`, `RIGHT_ARROW`, `UP_ARROW`, `DOWN_ARROW`: navigate through days + +`HOME`: focus the first day of the month + +`END`: focus the last day of the month + +`PAGE_UP`: goes to previous month + +`ALT` + `PAGE_UP`: goes to previous year + +`PAGE_DOWN`: goes to next month + +`ALT` + `PAGE_DOWN`: goes to next year + +`ENTER`: select current focused date + + +In year view: + +`LEFT_ARROW`, `RIGHT_ARROW`, `UP_ARROW`, `DOWN_ARROW`: navigate through months + +`HOME`: focus the first month of the year + +`END`: focus the last month of the year + +`PAGE_UP`: goes to previous year + +`ALT` + `PAGE_UP`: goes to previous 10 years + +`PAGE_DOWN`: goes to next year + +`ALT` + `PAGE_DOWN`: goes to next 10 years + +`ENTER`: select current focused month diff --git a/src/lib/snack-bar/snack-bar.md b/src/lib/snack-bar/snack-bar.md index 0c48eb0ea901..a468dfa3718a 100644 --- a/src/lib/snack-bar/snack-bar.md +++ b/src/lib/snack-bar/snack-bar.md @@ -73,6 +73,7 @@ export class MessageArchivedComponent { } ``` ### Accessibility -A snack-bar automatically goes away after a short time, so you can't count on the user seeing the -message or having a chance to press the button. For this reason, you should consider offering an -alternate way to perform any snack-bar action. +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). diff --git a/src/lib/toolbar/toolbar.md b/src/lib/toolbar/toolbar.md index 1a86a417e91c..cfc2879b0c17 100644 --- a/src/lib/toolbar/toolbar.md +++ b/src/lib/toolbar/toolbar.md @@ -51,5 +51,11 @@ use a neutral background color based on the current theme (light or dark). This `'primary'`, `'accent'`, or `'warn'`. ### Accessibility -Toolbar items without text or labels should be given a meaningful label via `aria-label` or -`aria-labelledby`. +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 `
` +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`. From c3b52424eb7865c9533c457bbcfb9153230b676d Mon Sep 17 00:00:00 2001 From: Yuan Gao Date: Wed, 30 Aug 2017 10:41:05 -0700 Subject: [PATCH 4/5] use table for shortcuts --- src/lib/datepicker/datepicker.md | 63 +++++++++++++++----------------- 1 file changed, 30 insertions(+), 33 deletions(-) diff --git a/src/lib/datepicker/datepicker.md b/src/lib/datepicker/datepicker.md index d7188b26eeff..a355a7809167 100644 --- a/src/lib/datepicker/datepicker.md +++ b/src/lib/datepicker/datepicker.md @@ -239,44 +239,41 @@ should have a placeholder or be given a meaningful label via `aria-label`, `aria #### Keyboard shortcuts The keyboard shortcuts to handle datepicker are: -`ALT` + `DOWN_ARROR`: trigger calendar dialog - -`ESCAPE`: close calendar dialog +| Shortcut | Action | +|----------------------|-----------------------------------| +| `ALT` + `DOWN_ARROW` | Open the calendar pop-up | +| `ESCAPE` | Close the calendar pop-up | In month view: -`LEFT_ARROW`, `RIGHT_ARROW`, `UP_ARROW`, `DOWN_ARROW`: navigate through days - -`HOME`: focus the first day of the month - -`END`: focus the last day of the month - -`PAGE_UP`: goes to previous month - -`ALT` + `PAGE_UP`: goes to previous year - -`PAGE_DOWN`: goes to next month - -`ALT` + `PAGE_DOWN`: goes to next year - -`ENTER`: select current focused date +| Shortcut | Action | +|----------------------|-----------------------------------| +| `LEFT_ARROW` | Goes to previous day | +| `RIGHT_ARROW` | Goes to next day | +| `UP_ARROW` | Goes to previous 7 days | +| `DOWN_ARROW` | Goes to next 7 days | +| `HOME` | Focus the first day of the month | +| `END` | Focus the last day of the month | +| `PAGE_UP` | Goes to previous month | +| `ALT` + `PAGE_UP` | Goes to previous year | +| `PAGE_DOWN` | Goes to next month | +| `ALT` + `PAGE_DOWN` | Goes to next year | +| `ENTER` | Select current date | In year view: -`LEFT_ARROW`, `RIGHT_ARROW`, `UP_ARROW`, `DOWN_ARROW`: navigate through months - -`HOME`: focus the first month of the year - -`END`: focus the last month of the year - -`PAGE_UP`: goes to previous year - -`ALT` + `PAGE_UP`: goes to previous 10 years - -`PAGE_DOWN`: goes to next year - -`ALT` + `PAGE_DOWN`: goes to next 10 years - -`ENTER`: select current focused month +| Shortcut | Action | +|----------------------|-----------------------------------| +| `LEFT_ARROW` | Goes to previous month | +| `RIGHT_ARROW` | Goes to next month | +| `UP_ARROW` | Goes to previous 6 months | +| `DOWN_ARROW` | Goes to next 6 months | +| `HOME` | Focus the first month of the year | +| `END` | Focus the last month of the year | +| `PAGE_UP` | Goes to previous year | +| `ALT` + `PAGE_UP` | Goes to previous 10 years | +| `PAGE_DOWN` | Goes to next year | +| `ALT` + `PAGE_DOWN` | Goes to next 10 years | +| `ENTER` | Select current month | From 1e7c679cc77a0edc827decaaa5cae0d109b8987d Mon Sep 17 00:00:00 2001 From: Yuan Gao Date: Wed, 30 Aug 2017 11:05:11 -0700 Subject: [PATCH 5/5] changes to go . --- src/lib/datepicker/datepicker.md | 60 ++++++++++++++++---------------- 1 file changed, 30 insertions(+), 30 deletions(-) diff --git a/src/lib/datepicker/datepicker.md b/src/lib/datepicker/datepicker.md index a355a7809167..ee7093c5f4d0 100644 --- a/src/lib/datepicker/datepicker.md +++ b/src/lib/datepicker/datepicker.md @@ -239,41 +239,41 @@ should have a placeholder or be given a meaningful label via `aria-label`, `aria #### 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 | +| Shortcut | Action | +|----------------------|-------------------------------------| +| `ALT` + `DOWN_ARROW` | Open the calendar pop-up | +| `ESCAPE` | Close the calendar pop-up | In month view: -| Shortcut | Action | -|----------------------|-----------------------------------| -| `LEFT_ARROW` | Goes to previous day | -| `RIGHT_ARROW` | Goes to next day | -| `UP_ARROW` | Goes to previous 7 days | -| `DOWN_ARROW` | Goes to next 7 days | -| `HOME` | Focus the first day of the month | -| `END` | Focus the last day of the month | -| `PAGE_UP` | Goes to previous month | -| `ALT` + `PAGE_UP` | Goes to previous year | -| `PAGE_DOWN` | Goes to next month | -| `ALT` + `PAGE_DOWN` | Goes to next year | -| `ENTER` | Select current date | +| 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` | Goes to previous month | -| `RIGHT_ARROW` | Goes to next month | -| `UP_ARROW` | Goes to previous 6 months | -| `DOWN_ARROW` | Goes to next 6 months | -| `HOME` | Focus the first month of the year | -| `END` | Focus the last month of the year | -| `PAGE_UP` | Goes to previous year | -| `ALT` + `PAGE_UP` | Goes to previous 10 years | -| `PAGE_DOWN` | Goes to next year | -| `ALT` + `PAGE_DOWN` | Goes to next 10 years | -| `ENTER` | Select current month | +| 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 |