Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add title and tooltip accessibility information to HTML style guide. #11655

Merged
merged 2 commits into from
Jun 8, 2017
Merged

Add title and tooltip accessibility information to HTML style guide. #11655

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
20cf042
Add title and tooltip accessibility information to HTML style guide.
cjcenizal May 8, 2017
d2a25a2
Add sections on native interactive elements and tab order.
cjcenizal Jun 8, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 47 additions & 3 deletions style_guides/html_style_guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ This makes the attributes easier to scan and compare across similar elements.
The closing bracket should be on its own line. This allows attributes to be shuffled and edited without having to move the bracket around. It also makes it easier to scan vertically and match opening and closing brackets. This format
is inspired by the positioning of the opening and closing parentheses in [Pug/Jade](https://pugjs.org/language/attributes.html#multiline-attributes).

```
```html
<div
attribute1="value1"
attribute2="value2"
Expand All @@ -21,10 +21,54 @@ is inspired by the positioning of the opening and closing parentheses in [Pug/Ja

If the element doesn't have children, add the closing tag on the same line as the opening tag's closing bracket.

```
```html
<div
attribute1="value1"
attribute2="value2"
attribute3="value3"
></div>
```
```

## 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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure how to apply these guidelines, is there a recommended way to implement tooltips like this?
Placement/showing/hiding should probably be handled by a directive, no?

We already have the tooltip directive from ui-boostrap, and the kbn-tooltip directive that wraps that, but neither of those follow these guidelines.

Copy link
Contributor Author

@cjcenizal cjcenizal May 9, 2017 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure either, to be honest. We'd need to spend some time figuring out a solution to this as part of our accessibility initiative, but it's also not currently on our list of priorities. I think it's OK to have this in our guidelines even if we don't currently follow it or have a way to implement it -- the information is accurate, and worth implementing when possible or updating if we decide it's impossible to achieve.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm uncomfortable putting rules in the style guide for which we don't yet have a clear path on implementation.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@BigFunger Here's an example of how we'd implement a tooltip with this guidance: https://codepen.io/cjcenizal/pen/aWqRVQ. Does this help?

I think we really need to have this accessibility information somewhere that's accessible (sorry) to everyone, so that we know where we want to go, even if we're not there yet. It's just a way of defining a goal first, and then finding a path there second.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is the intended path in regards to the other two ways (besides the title attribute) that are already being used within Kibana that @spalger mentioned?

Copy link
Contributor Author

@cjcenizal cjcenizal May 10, 2017 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As far as I can tell, we have two options:

  1. Update each implementation to adhere to the guidelines.
  2. Replace each implementation with one which adheres to the guidelines.

We'd need to dedicate time to investigating each option and deciding which path to pursue.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have used aria-describedby in the past with great success.


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
<div
class="kuiTooltip"
role="tooltip"
id="visualizationsTooltip"
>
Visualizations help you make sense of your data.
</div>

<button aria-describedby="visualizationsTooltip">
Visualizations
</button>
```

### 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"`.