diff --git a/style_guides/html_style_guide.md b/style_guides/html_style_guide.md index fc1b106d78f3f..15213e221fba6 100644 --- a/style_guides/html_style_guide.md +++ b/style_guides/html_style_guide.md @@ -59,4 +59,48 @@ If the element doesn't have children, add the closing tag on the same line as th attribute2="value2" attribute3="value3" > -``` \ No newline at end of file +``` + +## 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. If you don't know which number to use for the tab index, or if you simply want to add it to the general flow of the document, use `tabindex="0"`. \ No newline at end of file