Skip to content

Commit f64dd65

Browse files
MinThaMieMinThaMie
committed
v6.7.0
1 parent 1793370 commit f64dd65

File tree

1,185 files changed

+226000
-1
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

1,185 files changed

+226000
-1
lines changed

‎guides/v6.6.0/accessibility/application-considerations.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
In this section, you will learn about the configurations and libraries that affect an entire application's accessibility.
2+
3+
## Lang Attribute
4+
5+
Declaring the language of the HTML document allows users to better understand your content.
6+
7+
> Both assistive technologies and conventional user agents can render text more accurately when the language of the Web page is identified. Screen readers can load the correct pronunciation rules. Visual browsers can display characters and scripts correctly. Media players can show captions correctly. As a result, users with disabilities will be better able to understand the content.
8+
> [WCAG Success Criterion 3.1.1: Intent](https://www.w3.org/WAI/WCAG21/Understanding/language-of-page.html#intent)
9+
10+
A primary language should be defined on the `<html>` element's `lang` attribute. For new apps, you can use the `--lang` option on the `ember new` command to set the language for a new application.
11+
12+
```bash
13+
ember new mon-app --lang fr
14+
```
15+
16+
This command will create your application with French defined as the primary language
17+
on the `<html>` element's `lang` attribute.
18+
19+
For existing Ember apps, a developer may edit the `index.html` file or leverage [ember-intl](https://github.com/ember-intl/ember-intl).
20+
21+
The `html` element may not have multiple `lang` _values_. If an element contains content in a language different from the primary, then you can provide the element its own `lang` attribute.
22+
23+
![For example, the HTML tag may have a lang of "es" while a paragraph may have a lang of "en"](/images/accessibility/application-considerations/lang.png)
24+
25+
<div class="cta">
26+
<div class="cta-note">
27+
<div class="cta-note-body">
28+
<div class="cta-note-heading">Zoey says...</div>
29+
<div class="cta-note-message">
30+
<p>
31+
To learn more about the lang attribute and how to use it: <a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang">https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang</a>. Unsure which language subtag to use? Try <a href="https://r12a.github.io/app-subtags/">the Language Subtag Lookup tool</a>.
32+
</p>
33+
</div>
34+
</div>
35+
<img src="/images/mascots/zoey.png" role="presentation" alt="">
36+
</div>
37+
</div>
38+
39+
## Accessibility addons
40+
41+
Any addon that will provide UI elements to the application should be evaluated for accessibility before use.
42+
43+
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.
44+
45+
Here are some examples of accessibility-focused addons created by many people throughout the Ember community:
46+
47+
- [ember-a11y-landmarks](https://github.com/ember-a11y/ember-a11y-landmarks) - Ember addon to help with landmark roles for better accessibility
48+
- [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.
49+
- [ember-steps](https://github.com/rwjblue/ember-steps) - Declarative create wizards, tabbed UIs, and more
50+
- [ember-page-title](https://github.com/tim-evans/ember-page-title) - Page title management for Ember.js Apps
51+
- [ember-self-focused](https://github.com/linkedin/self-focused/tree/master/packages/ember-self-focused) - Focus on route on transition
52+
- [ember-keyboard](https://github.com/patience-tema-baron/ember-keyboard) - An Ember.js addon for the painless support of keyboard events
53+
- [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
54+
- [a11y-announcer](https://github.com/ember-a11y/a11y-announcer) - An accessible ember route change announcer
55+
- [ember-template-lint](https://github.com/ember-template-lint/ember-template-lint) - linter for Ember templates
56+
![Template Linting Preview](/images/accessibility/application-considerations/template-lint.png)
57+
58+
While there are quite a few moving parts, here's a cheat sheet to get you started: [Accessibility Cheat Sheet](https://moritzgiessmann.de/accessibility-cheatsheet/)

‎guides/v6.6.0/accessibility/components.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
When crafting an accessible component, the first and most important thing is that the component should render valid HTML.
2+
3+
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.
4+
5+
Browsers have implemented the spec in a way that provides functionality for free.
6+
For example, consider this code sample:
7+
8+
```html
9+
<button type="submit">Submit Form</button>
10+
```
11+
12+
Here is what would be provided by the browser that the developer would otherwise need to provide:
13+
14+
- keyboard interactions on interactive elements (i.e., using the `ENTER` key to activate a `<button>` element)
15+
- a machine-readable name
16+
- a place in the `TAB` order of the page
17+
- the intrinsic role of button
18+
19+
If the interactive element would be written another way, such as:
20+
21+
```html
22+
<div>Submit Form</div>
23+
```
24+
25+
The developer would need to write the following additional code:
26+
27+
- add the role of button (`role="button"`)
28+
- add the button to the tab order (`tabindex="0"`)
29+
- add the keyboard functionality (a JavaScript function to activate the associated action when the `ENTER` key is pressed)
30+
31+
This is just one example of how developers can use HTML's built in features to improve accessibility and reduce the need for custom code. Read more here: ["Just use a button"](https://developer.paciellogroup.com/blog/2011/04/html5-accessibility-chops-just-use-a-button/).
32+
33+
## Focus management in components
34+
35+
Focus is one of the main ways a component can communicate with screen readers.
36+
37+
For example, when you hit tab on a page or click on a form field, a blue border usually appears around the element. This kind of behavior is part of focus.
38+
Developers can use JavaScript to control the focus in their apps, enabling keyboard navigation and usability by screen readers.
39+
For example, if there is a button that launches a modal with interactive elements in it, that button's click handler needs to contain code that brings focus to the new content.
40+
41+
This article is a good launching point for learning more about focus: [Keyboard accessibility](https://webaim.org/techniques/keyboard/)
42+
43+
Here are some other tips to get you started:
44+
45+
- There is a difference between browse mode and focus mode in screen readers- see ["Focus Please"](https://codepen.io/melsumner/live/ZJeYoP).
46+
- 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.
47+
- Note: `role="presentation"` or `aria-hidden="true"` should not be used on a focusable element.
48+
49+
50+
## Accessible name
51+
52+
All interactive elements must have an accessible name. But what does that mean, exactly?
53+
54+
Because the code that is written must be readable by other machines (assistive tech like screen readers, for example), there is documentation about how this accessible name is determined: [Accessible Name and Description Computation](https://www.w3.org/TR/accname-1.1/).
55+
56+
However, the most common methods for providing accessible names can be reviewed here.
57+
58+
### Adding a label to an input element
59+
60+
Every `<input>` element should have an associated `<label>` element. To do this, the `<input>` element's `id` attribute value should be the same as the `for` attribute value on the `<label>`. Ember has a built-in `unique-id` helper that can generate unique ids that you can use like this:
61+
62+
![Separate input and label elements with a connection established by matching for and id attributes](/images/accessibility/component-considerations/input-for-id.png)
63+
64+
```html
65+
{{#let (unique-id) as |id|}}
66+
<label for={{id}}>Name:</label>
67+
<input id={{id}} name="name" value="" type="text" />
68+
{{/let}}
69+
```
70+
71+
It is also valid to wrap the `<label>` element around the `<input />` element:
72+
73+
![A child input element nested within a parent label element without any for and id attributes](/images/accessibility/component-considerations/input-nested.png)
74+
75+
```html
76+
<label>Name:
77+
<input name="name" value="" type="text" />
78+
</label>
79+
```
80+
81+
However, this option can be a little harder to apply styles to, so both should be tested before determining which approach to use.
82+
83+
<div class="cta">
84+
<div class="cta-note">
85+
<div class="cta-note-body">
86+
<div class="cta-note-heading">Zoey says...</div>
87+
<div class="cta-note-message">
88+
To dig deeper into accessible input patterns in Ember check out the <a href="https://emberjs-1.gitbook.io/ember-component-patterns/form-components/input">ember-component-patterns article on Input Fields</a>.
89+
</div>
90+
</div>
91+
<img src="/images/mascots/zoey.png" role="presentation" alt="">
92+
</div>
93+
</div>

‎guides/v6.6.0/accessibility/index.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
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.
2+
3+
![Ember Loves Accessibility](/images/accessibility/index/a11y-mascots.png)
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+
10+
## Accessibility Strategy
11+
12+
Digital accessibility regulations vary from country to country, but most at least point to the [WAI-ARIA](https://www.w3.org/WAI/) specification for compliance.
13+
14+
"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.
15+
16+
Creating a sensible plan for your product up front can save a great deal of stress down the road.

‎guides/v6.6.0/accessibility/learning-resources.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
These accessibility learning resources will provide additional support to the developer looking to improve the quality of the code they write.
2+
3+
- [MDN Web Docs: Accessibility](https://developer.mozilla.org/en-US/docs/Learn/Accessibility)
4+
- [Using ARIA:](https://www.w3.org/TR/using-aria/) a practical guide for developers on how to add accessibility information to HTML elements
5+
- [Web Content Accessibility Guidelines(WCAG) 2.1](https://www.w3.org/TR/WCAG21/)
6+
- [Accessible Rich Internet Applications (ARIA) 1.1](https://www.w3.org/TR/wai-aria-1.1/)
7+
- [How to meet WCAG (Quick Reference)](https://www.w3.org/WAI/WCAG21/quickref/)
8+
9+
10+
## Practical Resources
11+
12+
- [Accessibility Insights](https://accessibilityinsights.io/)- Use FastPass to find common, high-impact issues
13+
- [aXe extension for Chrome](https://chrome.google.com/webstore/detail/axe/lhdoppojpmngadmnindnejefpokejbdd)
14+
- [Accessibility Support](https://a11ysupport.io/)- Find out if your code will work with assistive tech
15+
- [How and where to report accessibility bugs](https://www.digitala11y.com/how-where-to-report-accessibility-bugs/)
16+
17+
18+
### Design
19+
20+
- [ColorSafe](http://colorsafe.co/)- Empowering designers with beautiful and accessible color palettes based on WCAG Guidelines of text and background contrast ratios
21+
- [Accessible Color Palette Builder](https://toolness.github.io/accessible-color-matrix/)
22+
23+
24+
### Writing
25+
26+
- [Plain Language](https://plainlanguage.gov/) - Learn how to write in a way that makes it easier for people to read and understand.
27+
28+
29+
### Other Useful Articles
30+
31+
- [The difference between keyboard and screen reader navigation](https://tink.uk/the-difference-between-keyboard-and-screen-reader-navigation/)

‎guides/v6.6.0/accessibility/page-template-considerations.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
When considering an application's page or view structure, there are a few primary concerns that should be planned for:
2+
3+
- page title
4+
- skip navigation links
5+
- focus management
6+
7+
8+
## Page Title
9+
10+
Each page (what is rendered for a unique URL) should have a page title. This page title should be unique to that page, and should accurately reflect what that page does.
11+
12+
Consider this format:
13+
14+
`Unique Page Title - Site Title`
15+
16+
<img width="675px" title="Page Title Example" alt="A visual representation of page title in the browser's tab" src="/images/accessibility/page-template-considerations/page-title.png"/>
17+
18+
Note that the unique page title is first. This is because it is the most important piece of information from a contextual perspective. Since a user with a screen reader can interrupt the screen reader as they wish, it introduces less fatigue when the unique page title is first, but provides the additional guidance if it is desired.
19+
20+
A simple way to add page titles is to use the `page-title` helper which comes from the [ember-page-title](https://github.com/ember-cli/ember-page-title) addon that is installed by default in new apps. We can use this helper to set the page title at any point in any template.
21+
22+
For example, if we have a “posts” route, we can set the page title for it like so:
23+
24+
25+
```handlebars {data-filename=app/routes/posts.hbs}
26+
{{page-title "Posts - Site Title"}}
27+
28+
{{outlet}}
29+
```
30+
31+
Extending the example, if we have a “post” route that lives within the “posts” route, we could set its page title like so:
32+
33+
```handlebars {data-filename=app/routes/posts/post.hbs}
34+
{{page-title (concat @model.title " - Site Title")}}
35+
36+
<h1>{{@model.title}}</h1>
37+
```
38+
39+
When your needs become more complex, the following addons facilitate page titles in a more dynamic and maintainable way.
40+
41+
- [ember-cli-head](https://github.com/ronco/ember-cli-head)
42+
- [ember-cli-document-title](https://github.com/kimroen/ember-cli-document-title)
43+
44+
To evaluate more addons to add/manage content in the `<head>` of a page, view this category on [Ember Observer](https://emberobserver.com/categories/header-content).
45+
46+
You can test that page titles are generated correctly by asserting on the value of `document.title` in your tests:
47+
48+
```javascript {data-filename=tests/acceptance/posts-test.js}
49+
import { module, test } from 'qunit';
50+
import { visit, currentURL } from '@ember/test-helpers';
51+
import { setupApplicationTest } from 'my-app-name/tests/helpers';
52+
53+
module('Acceptance | posts', function(hooks) {
54+
setupApplicationTest(hooks);
55+
56+
test('visiting /posts', async function(assert) {
57+
await visit('/posts');
58+
assert.equal(document.title, 'Posts - Site Title');
59+
});
60+
});
61+
```
62+
63+
## Skip Navigation Links
64+
65+
A skip navigation link, or skip link, is a useful feature for users who want to bypass content that is repeated on multiple pages (i.e., a site header). This can especially helpful to users with assistive technology, who have to browse website content in a more linear fashion, but it can also be useful for power users who prefer to navigate websites only using a keyboard.
66+
67+
<img width="675px" title="Skip Main Content Example" alt="A visual representation of how the skip link works in the browser" src="/images/accessibility/page-template-considerations/skip-main-content.png"/>
68+
69+
To implement a skip link in an application, add an anchor element as close as possible after the opening `<body>` element, and have it link to the beginning of the page's main content area.
70+
71+
To read more about skip links, visit the [MDN docs](https://developer.mozilla.org/en-US/docs/Learn/Accessibility/HTML#Skip_links).
72+
73+
74+
## Focus Management
75+
76+
No single-page application framework provides the appropriate route-level focus for assistive technology in a default manner. This is primarily due to the way `pushState` works, and the lack of an event hook for JavaScript frameworks to tell assistive technology that the page content has changed. This *also* means that the focus is unchanged on route navigation, which in some cases means that it would be lost entirely (if the element that previously had focus is now gone).
77+
78+
Most frameworks have some mechanism for adding the missing functionality to an application. In Ember, there is an attempt to address these two specific shortcomings 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:
79+
80+
- [ember-a11y](https://github.com/ember-a11y/ember-a11y)
81+
- [ember-self-focused](https://github.com/linkedin/self-focused/tree/master/packages/ember-self-focused)
82+
- [ember-a11y-refocus](https://github.com/MelSumner/ember-a11y-refocus)

‎guides/v6.6.0/accessibility/testing.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
## Screen Reader and Browser Combinations
2+
3+
It is important to use a screen reader when checking to make sure your application is accessible.
4+
5+
There are assistive technologies (known as screen readers) available for all common desktop platforms and mobile devices.
6+
7+
- VoiceOver, integrated in Apple products
8+
- Narrator, integrated in Windows products
9+
- Orca, available for integration in Ubuntu, otherwise available as a download
10+
- JAWS, proprietary software by Freedom Scientific, available for Windows
11+
- NVDA, open source software, available for Windows
12+
- TalkBack, integrated in Android products
13+
14+
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.
15+
16+
- Firefox & NVDA (Windows)
17+
- IE & JAWS (Windows)
18+
- Edge & Narrator (Windows)
19+
- Safari & VoiceOver (MacOS)
20+
21+
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.

0 commit comments

Comments
 (0)