From e893d6dd4d2d04aa968b1f57ac7f1db4324c8676 Mon Sep 17 00:00:00 2001 From: Tim Roes Date: Tue, 8 Aug 2017 18:17:55 +0200 Subject: [PATCH 1/9] Initial version of a11y guide --- STYLEGUIDE.md | 1 + style_guides/accessibility_guide.md | 108 ++++++++++++++++++++++++++++ 2 files changed, 109 insertions(+) create mode 100644 style_guides/accessibility_guide.md diff --git a/STYLEGUIDE.md b/STYLEGUIDE.md index a71ad9cce0183..d43919b6c32b5 100644 --- a/STYLEGUIDE.md +++ b/STYLEGUIDE.md @@ -10,6 +10,7 @@ recommended for the development of all Kibana plugins. - [HTML](style_guides/html_style_guide.md) - [API](style_guides/api_style_guide.md) - [Architecture](style_guides/architecture_style_guide.md) +- [Accessibility](style_guides/acecssibility_guide.md) ## Filenames diff --git a/style_guides/accessibility_guide.md b/style_guides/accessibility_guide.md new file mode 100644 index 0000000000000..c252857c84745 --- /dev/null +++ b/style_guides/accessibility_guide.md @@ -0,0 +1,108 @@ +# Accessibility (A11Y) Guide + +This document provides some technical guidelines how to prevent several common +accessibility issues. + +## Interactive elements + +### Use ` +``` + ### Don't create keyboard traps **TL;DR** *If you can't leave an element with Tab again, it needs a special interaction model.* @@ -106,3 +134,23 @@ easily put this role to. [wcag/113](https://github.com/w3c/wcag/issues/113), [html-aria/118](https://github.com/w3c/html-aria/issues/18), [aria/85](https://github.com/w3c/aria/issues/85) + +## Miscellaneous + +### Don't use the `title` attribute + +**TL;DR** *Don't use the `title` attribute, use tooltips, `aria-label`, etc. instead.* + +The `title` has no clear role within the accessibility standards. +[See the HTML5 spec](http://w3c.github.io/html/dom.html#the-title-attribute) for more information. + +To provide supplementary, descriptive information about a form control, button, link, or other element, +that should also be visible to non vision impaired users, use a tooltip component instead. + +If you need a label only for screen readers use `aria-label`. + +**Additional reading:** + +* https://www.paciellogroup.com/blog/2010/11/using-the-html-title-attribute/ +* https://www.paciellogroup.com/blog/2012/01/html5-accessibility-chops-title-attribute-use-and-abuse/ +* https://www.deque.com/blog/text-links-practices-screen-readers/ diff --git a/style_guides/html_style_guide.md b/style_guides/html_style_guide.md index 415e12e802c43..e2809794a153d 100644 --- a/style_guides/html_style_guide.md +++ b/style_guides/html_style_guide.md @@ -82,53 +82,3 @@ similar elements which appear sequentially in the markup. ```html
hi
``` - -## Accessibility - -### Don't use the `title` attribute - -The `title` has no clear role within the accessibility standards. -[See the HTML5 spec](http://w3c.github.io/html/dom.html#the-title-attribute) for more information. - -To provide supplementary, descriptive information about a form control, button, link, or other element, use -a tooltip component instead. - -Additional reading: - -* https://www.paciellogroup.com/blog/2010/11/using-the-html-title-attribute/ -* https://www.paciellogroup.com/blog/2012/01/html5-accessibility-chops-title-attribute-use-and-abuse/ -* https://www.deque.com/blog/text-links-practices-screen-readers/ - -### Tooltips - -Elements which act as tooltips should have the `role="tooltip"` attribute and an ID to which the -described element can point to with the `aria-describedby` attribute. For example: - -```html - - - -``` - -### Prefer `button` and `a` when making interactive elements keyboard-accessible - -If something is meant to be clickable, favor using a `button` or `a` tag before over the `kui-accessible-click` directive or `KuiKeyboardAccessible` component. These tools are useful as they augment non-clickable elements with `onkeypress` and `onkeyup` handlers, allowing non-clickable elements to become keyboard accessible. However, `button` and `a` tags provide this functionality natively. - -### Use `tabindex` to make elements tabbable - -When added to the tab order, elements become focusable via non-sticky-mode keyboard navigation. -To add an element to the tab order, you must add an `id` attribute as well as a `tabindex` attribute. - -You should only use `tabindex="0"` to add an element to the tab flow or `tabindex="-1"` to remove an -otherwise focusable element from the focus flow (use with care). -You should never use a value greater than 0, since tabindex is a global counter for the whole -webpage and not scoped to parent elements, so you would need to manage a globally meaningful order -across all elements in the whole source code. From 9dc78d8303ce988f3828c4f44d981a469a4aea7e Mon Sep 17 00:00:00 2001 From: Tim Roes Date: Wed, 9 Aug 2017 11:15:22 +0200 Subject: [PATCH 3/9] Add PR feedback --- style_guides/accessibility_guide.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/style_guides/accessibility_guide.md b/style_guides/accessibility_guide.md index 66860f4d80444..01185544b306d 100644 --- a/style_guides/accessibility_guide.md +++ b/style_guides/accessibility_guide.md @@ -7,13 +7,18 @@ accessibility issues. ### Use ` +``` + +If the actual name for that element is already present in another element, +you can use `aria-labelledby` to reference the id of that element: + +```html +
Date Picker
+ +``` + +### Label every form element + +You should add a label for every form element: + +```html + + +``` + +If one label references multiple form elements, you can use the reverse logic +and add `aria-labelledby` to all form elements: + +```html + + + + +``` + +You should always prefer the ` + ``` If the actual name for that element is already present in another element, @@ -24,7 +24,7 @@ you can use `aria-labelledby` to reference the id of that element: ```html
Date Picker
- + ``` ### Label every form element From ec437528fc1566f4abfbf0e30f056f35cf122423 Mon Sep 17 00:00:00 2001 From: Tim Roes Date: Fri, 11 Aug 2017 19:52:13 +0200 Subject: [PATCH 9/9] Correct typo --- style_guides/accessibility_guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/style_guides/accessibility_guide.md b/style_guides/accessibility_guide.md index 43f2647dd6d50..2ccc5c9f7ad69 100644 --- a/style_guides/accessibility_guide.md +++ b/style_guides/accessibility_guide.md @@ -200,7 +200,7 @@ actual main area of the page (and skip all headers, navigations, etc.). #### `
` The `
` element, can be used to mark a region on the page, so that it -appears in the landmark navigation. The section element therefor needs to have +appears in the landmark navigation. The section element therefore needs to have an *accessible name*, i.e. you should add an `aria-label`, that gives a short title to that section of the page.