Skip to content

Commit 55486a2

Browse files
MelSumnerMelSumner
committed
changing the accessibility page to an accessibility section
1 parent 26136d3 commit 55486a2

9 files changed

+195
-130
lines changed

‎guides/release/accessibility/application-considerations.md

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# Application Considerations
2+
3+
There are a few application considerations
4+
5+
## Optional feature: application template wrapper
6+
7+
If you are using the [application template wrapper](https://emberjs.com/blog/2018/02/16/ember-3-1-beta-released.html#toc_new-optional-feature-application-template-wrapper) enabled (default state), then you will need to add certain aria roles to your [landmark regions](https://www.w3.org/WAI/PF/aria/roles#landmark_roles), even if you are using native HTML elements, because those regions are not the direct child descendant of the body element (they are the children of the div that wraps the Ember app).
8+
9+
If you disable the [application template wrapper](https://emberjs.com/blog/2018/02/16/ember-3-1-beta-released.html#toc_new-optional-feature-application-template-wrapper), you will not need to add role attributes to your landmark regions when they are the direct descendant of the body element, and they are using native HTML elements. This is the preferred approach for accessible applications.
10+
11+
To disable this feature:
12+
13+
```bash
14+
ember feature:disable application-template-wrapper
15+
```
16+
17+
**Application Template Wrapper Disabled** _(preferred)_
18+
19+
```hbs
20+
<body>
21+
<header></header>
22+
<main></main>
23+
<footer></footer>
24+
</body>
25+
```
26+
27+
**Application Template Wrapper Enabled**
28+
29+
```hbs
30+
<body>
31+
<div class="ember-view">
32+
<header role="banner"></header>
33+
<main role="main"></main>
34+
<footer role="contentinfo"></footer>
35+
</div>
36+
</body>
37+
```
38+
39+
<div class="cta">
40+
<div class="cta-note">
41+
<div class="cta-note-body">
42+
<div class="cta-note-heading">Zoey says...</div>
43+
<div class="cta-note-message">
44+
To learn more about landmark roles and how to use them: <a href="https://www.w3.org/WAI/PF/aria/roles#landmark_roles">https://www.w3.org/WAI/PF/aria/roles#landmark_roles</a>. Still need more help? Visit the #topic-a11y channel in <a href="https://emberjs.com/community/">the community chat</a>.
45+
</div>
46+
</div>
47+
<img src="/images/mascots/zoey.png" role="presentation" alt="">
48+
</div>
49+
</div>
50+
51+
## Ember applications vs role=''application''
52+
53+
An important thing to note in this section is this: "application" in Ember development and "application" in landmark roles have two _very_ different meanings.
54+
55+
The <abbr title="too long; didn't read">TL;DR</abbr>? Don't use `role="application"` until you have done your research and know exactly how it is to be used correctly (if at all). There are **very** few use cases where the role of application is appropriate.
56+
57+
Read more about it: [https://a11yproject.com/posts/how-to-use-application-role/](https://a11yproject.com/posts/how-to-use-application-role/)
58+
59+
## Accessibility addons
60+
61+
Any addon that will provide UI elements to the application should be evaluated for accessibility before use.
62+
63+
There are some existing Ember addons that may help you make your app more accessible. Each addon should be evaluated for its own usefulness and merit- you may find in some instances, that it would be better to implement the ideas presented in the addon in your own application.
64+
65+
- [ember-a11y-landmarks](https://github.com/ember-a11y/ember-a11y-landmarks) - Ember addon to help with landmark roles for better accessibility
66+
- [ember-component-focus](https://github.com/ember-a11y/ember-component-focus) - A mixin for adding methods to your Ember components that help you manage the currently focused element.
67+
- [ember-gestures](https://github.com/html-next/ember-gestures) - Ember Gestures provides an easy way to use gestures by making it simple to define and use HammerJS managers and recognizers throughout your app.
68+
- [ember-steps](https://github.com/rwjblue/ember-steps) - Declarative create wizards, tabbed UIs, and more
69+
- [ember-page-title](https://github.com/tim-evans/ember-page-title) - Page title management for Ember.js Apps
70+
- [ember-self-focused](https://github.com/linkedin/self-focused/tree/master/packages/ember-self-focused) - Focus on route on transition
71+
- [ember-keyboard](https://github.com/patience-tema-baron/ember-keyboard) - An Ember.js addon for the painless support of keyboard events
72+
- [ember-a11y-testing](https://github.com/ember-a11y/ember-a11y-testing) - A suite of accessibility tests that can be run within the Ember testing framework
73+
- [a11y-announcer](https://github.com/ember-a11y/a11y-announcer) - An accessible ember route change announcer
74+
- [ember-template-lint](https://github.com/ember-template-lint/ember-template-lint) - linter for Ember templates

‎guides/release/accessibility/component-considerations.md

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Component Considerations
2+
3+
When crafting an accessible component, the first and most important thing is that the component should render valid HTML.
4+
5+
Both the HTML and ARIA specifications have been written in a way that make them work together. Semantic HTML provides the necessary _context_ to screen readers.
6+
7+
Browsers have implemented the spec in a way that provides functionality for free.
8+
For example, consider this code sample:
9+
10+
```html
11+
<button>Submit Form</button>
12+
```
13+
14+
Here is what would be provided by the browser that the developer would otherwise need to provide:
15+
16+
- keyboard interactions on interactive elements (i.e., using the `ENTER` key to activate a `<button>` element)
17+
- a machine-readable name
18+
- a place in the `TAB` order of the page
19+
- the intrinsic role of button
20+
21+
If the interactive element would be written another way, such as:
22+
23+
```html
24+
<div>Submit Form</div>
25+
```
26+
27+
The developer would need to write the following additional code:
28+
29+
- add the role of button (`role="button"`)
30+
- add the button to the tab order (`tabindex="0")
31+
- add the keyboard functionalty (a javascript function to activate the associated action when the `ENTER` key is pressed)
32+
33+
Read more: ["Just use a button"](https://developer.paciellogroup.com/blog/2011/04/html5-accessibility-chops-just-use-a-button/).
34+
35+
## Focus management in components
36+
37+
Focus management is a large part of how a component's code coordinates with the code that runs screen readers.
38+
39+
- There is a difference between browse mode and focus mode in screen readers- see ["Focus Please"](https://codepen.io/melsumner/live/ZJeYoP).
40+
- Focus should return from whence it came- for example, if a `<button>` element opens a modal, the focus should then be returned to that same trigger button once the modal is closed.
41+
- Note: `role="presentation"` or `aria-hidden="true"` should not be used on a focusable element.
42+
43+
44+
## Accessible name
45+
46+
All interactive elements must have an accessible name. But what does that mean, exactly?
47+

‎guides/release/accessibility/index.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Intro to Accessibility
2+
3+
Ember provides a few ways to help developers more easily produce accessible applications, and this section of the guides will more explicitly assist with that.
4+
5+
Accessibility should be considered at the start of a project, whether that project has named accessibility an explicit goal or not. Since no one can predict anyone else's future (including whether or not they will need assistive technology at some point), and because in many places around the world it is legally required to make websites digitally accessible, accessibility should be thought about in the same way as performance- a necessity for any web-based product.
6+
7+
Additionally, it causes less churn to decide to implement basic accessibility considerations at the start of the project, than trying to add it on later or pivoting mid-project. Semantic HTML doesn't take any additional time to write than non-semantic markup, provides a lower cognitive burden for development, typically produces less markup which will help an application be more performant, and is better for SEO.
8+
9+
## Accessibility Strategy
10+
11+
"100% accessible"- what does that mean? From a practical perspective, accessibility really looks more like 90% coding to the spec and 10% filing browser bugs (or keeping track of existing browser bugs). Keep in mind that if a workaround for a browser bug is implemented, an internal tracking issue in the product backlog should be also filed so as to provide the reminder to follow up on browser bugs at a later date.
12+

‎guides/release/accessibility/learning-resources.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Learning Resources
2+
3+
These accessibility learning resources will provide additional support to the developer looking to improve the quality of the code they write.
4+
5+
- [MDN Web Docs: Accessibility](https://developer.mozilla.org/en-US/docs/Learn/Accessibility)
6+
- [Using ARIA:](https://www.w3.org/TR/using-aria/) a practical guide for developers on how to add accessibility information to HTML elements
7+
- [Web Content Accessibility Guidelines(WCAG) 2.1](https://www.w3.org/TR/WCAG21/)
8+
- [Accessible Rich Internet Applications (ARIA) 1.1](https://www.w3.org/TR/wai-aria-1.1/)
9+
- [How to meet WCAG (Quick Reference)](https://www.w3.org/WAI/WCAG21/quickref/)

‎guides/release/accessibility/page-template-considerations.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Page Template Considerations
2+
3+
When considering an application's page or view structure, there are two primary areas that should be planned for: focus management and skip links.
4+
5+
## Focus Management
6+
7+
No single-page application framework provides the appropriate route-level focus for assistive technology. This is primarily due to
8+
9+
In Ember, there is an attempt to address this shortcoming with [RFC 433](https://github.com/emberjs/rfcs/pull/433); in the meantime there are a few addons that exist to help provide page or view-level focus for your application. All options should be evaluated to determine which is the appropriate use case for your application:
10+
11+
- [ember-a11y](https://github.com/ember-a11y/ember-a11y)
12+
- [ember-self-focused](https://github.com/linkedin/self-focused/tree/master/packages/ember-self-focused)
13+
- [ember-a11y-refocus](https://github.com/MelSumner/ember-a11y-refocus)

‎guides/release/accessibility/testing.md

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Testing Considerations
2+
3+
## Screen Reader and Browser Combinations
4+
5+
It is important to use a screen reader when checking to make sure your application is accessible.
6+
7+
There are assistive technologies (known as screen readers) available for all common desktop platforms and mobile devices.
8+
9+
- VoiceOver, integrated in Apple products
10+
- Narrator, integrated in Windows products
11+
- Orca, available for integration in Ubuntu, otherwise available as a download
12+
- JAWS, proprietary software by Freedom Scientific, available for Windows
13+
- NVDA, open source software, available for Windows
14+
- TalkBack, integrated in Android products
15+
16+
While developing and testing for conformance, keep in mind that there are well-known screen reader and browser combinations that were developed in a way that work well together; using combinations different than these may produce false-positive results. It should be noted that these may change over time, so periodic review of this list is recommended.
17+
18+
- Firefox & NVDA (Windows)
19+
- IE & JAWS (Windows)
20+
- Edge & Narrator (Windows)
21+
- Safari & VoiceOver (MacOS)
22+
23+
The absolute best method for learning how a screen reader works is using one yourself! It might feel a little awkward at first, but understanding how to use a screen reader (and other assistive technology) will help you become a more skilled developer.

‎guides/release/pages.yml

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -283,5 +283,19 @@
283283
pages:
284284
- title: Syntax Conversion Guide
285285
url: index
286-
- title: Accessibility Guide
287-
url: accessibility-guide
286+
- title: Accessibility
287+
url: accessibility
288+
pages:
289+
- title: Intro to Accessibility
290+
- url: index
291+
- title: Application Considerations
292+
- url: application-considerations
293+
- title: Page Template Considerations
294+
- url: page-template-considerations
295+
- title: Component Considerations
296+
- url: component-considerations
297+
- title: Testing Considerations
298+
- url: testing
299+
- title: Learning Resources
300+
- url: learning-resources
301+

0 commit comments

Comments
 (0)