Skip to content

Commit

Permalink
Merge pull request #2050 from ember-learn/create-new-guides-version-519
Browse files Browse the repository at this point in the history 
Release v5.10.0
  • Loading branch information
@jaredgalanis
jaredgalanis authored Jul 12, 2024
2 parents 80d89b6 + ceab70a commit 4c54e43
Show file tree
Hide file tree
Showing 189 changed files with 27,477 additions and 1 deletion.
58 changes: 58 additions & 0 deletions guides/v5.9.0/accessibility/application-considerations.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
In this section, you will learn about the configurations and libraries that affect an entire application's accessibility.

## Lang Attribute

Declaring the language of the HTML document allows users to better understand your content.

> 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.
> [WCAG Success Criterion 3.1.1: Intent](https://www.w3.org/WAI/WCAG21/Understanding/language-of-page.html#intent)
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.

```bash
ember new mon-app --lang fr
```

This command will create your application with French defined as the primary language
on the `<html>` element's `lang` attribute.

For existing Ember apps, a developer may edit the `index.html` file or leverage [ember-intl](https://github.com/ember-intl/ember-intl).

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.

![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)

<div class="cta">
<div class="cta-note">
<div class="cta-note-body">
<div class="cta-note-heading">Zoey says...</div>
<div class="cta-note-message">
<p>
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>.
</p>
</div>
</div>
<img src="/images/mascots/zoey.png" role="presentation" alt="">
</div>
</div>

## Accessibility addons

Any addon that will provide UI elements to the application should be evaluated for accessibility before use.

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.

Here are some examples of accessibility-focused addons created by many people throughout the Ember community:

- [ember-a11y-landmarks](https://github.com/ember-a11y/ember-a11y-landmarks) - Ember addon to help with landmark roles for better accessibility
- [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.
- [ember-steps](https://github.com/rwjblue/ember-steps) - Declarative create wizards, tabbed UIs, and more
- [ember-page-title](https://github.com/tim-evans/ember-page-title) - Page title management for Ember.js Apps
- [ember-self-focused](https://github.com/linkedin/self-focused/tree/master/packages/ember-self-focused) - Focus on route on transition
- [ember-keyboard](https://github.com/patience-tema-baron/ember-keyboard) - An Ember.js addon for the painless support of keyboard events
- [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
- [a11y-announcer](https://github.com/ember-a11y/a11y-announcer) - An accessible ember route change announcer
- [ember-template-lint](https://github.com/ember-template-lint/ember-template-lint) - linter for Ember templates
![Template Linting Preview](/images/accessibility/application-considerations/template-lint.png)

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/)
93 changes: 93 additions & 0 deletions guides/v5.9.0/accessibility/components.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
When crafting an accessible component, the first and most important thing is that the component should render valid HTML.

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.

Browsers have implemented the spec in a way that provides functionality for free.
For example, consider this code sample:

```html
<button type="submit">Submit Form</button>
```

Here is what would be provided by the browser that the developer would otherwise need to provide:

- keyboard interactions on interactive elements (i.e., using the `ENTER` key to activate a `<button>` element)
- a machine-readable name
- a place in the `TAB` order of the page
- the intrinsic role of button

If the interactive element would be written another way, such as:

```html
<div>Submit Form</div>
```

The developer would need to write the following additional code:

- add the role of button (`role="button"`)
- add the button to the tab order (`tabindex="0"`)
- add the keyboard functionality (a JavaScript function to activate the associated action when the `ENTER` key is pressed)

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/).

## Focus management in components

Focus is one of the main ways a component can communicate with screen readers.

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.
Developers can use JavaScript to control the focus in their apps, enabling keyboard navigation and usability by screen readers.
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.

This article is a good launching point for learning more about focus: [Keyboard accessibility](https://webaim.org/techniques/keyboard/)

Here are some other tips to get you started:

- There is a difference between browse mode and focus mode in screen readers- see ["Focus Please"](https://codepen.io/melsumner/live/ZJeYoP).
- 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.
- Note: `role="presentation"` or `aria-hidden="true"` should not be used on a focusable element.


## Accessible name

All interactive elements must have an accessible name. But what does that mean, exactly?

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/).

However, the most common methods for providing accessible names can be reviewed here.

### Adding a label to an input element

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:

![Separate input and label elements with a connection established by matching for and id attributes](/images/accessibility/component-considerations/input-for-id.png)

```html
{{#let (unique-id) as |id|}}
<label for={{id}}>Name:</label>
<input id={{id}} name="name" value="" type="text" />
{{/let}}
```

It is also valid to wrap the `<label>` element around the `<input />` element:

![A child input element nested within a parent label element without any for and id attributes](/images/accessibility/component-considerations/input-nested.png)

```html
<label>Name:
<input name="name" value="" type="text" />
</label>
```

However, this option can be a little harder to apply styles to, so both should be tested before determining which approach to use.

<div class="cta">
<div class="cta-note">
<div class="cta-note-body">
<div class="cta-note-heading">Zoey says...</div>
<div class="cta-note-message">
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>.
</div>
</div>
<img src="/images/mascots/zoey.png" role="presentation" alt="">
</div>
</div>
16 changes: 16 additions & 0 deletions guides/v5.9.0/accessibility/index.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
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.

![Ember Loves Accessibility](/images/accessibility/index/a11y-mascots.png)

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.

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.


## Accessibility Strategy

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.

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

Creating a sensible plan for your product up front can save a great deal of stress down the road.
31 changes: 31 additions & 0 deletions guides/v5.9.0/accessibility/learning-resources.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
These accessibility learning resources will provide additional support to the developer looking to improve the quality of the code they write.

- [MDN Web Docs: Accessibility](https://developer.mozilla.org/en-US/docs/Learn/Accessibility)
- [Using ARIA:](https://www.w3.org/TR/using-aria/) a practical guide for developers on how to add accessibility information to HTML elements
- [Web Content Accessibility Guidelines(WCAG) 2.1](https://www.w3.org/TR/WCAG21/)
- [Accessible Rich Internet Applications (ARIA) 1.1](https://www.w3.org/TR/wai-aria-1.1/)
- [How to meet WCAG (Quick Reference)](https://www.w3.org/WAI/WCAG21/quickref/)


## Practical Resources

- [Accessibility Insights](https://accessibilityinsights.io/)- Use FastPass to find common, high-impact issues
- [aXe extension for Chrome](https://chrome.google.com/webstore/detail/axe/lhdoppojpmngadmnindnejefpokejbdd)
- [Accessibility Support](https://a11ysupport.io/)- Find out if your code will work with assistive tech
- [How and where to report accessibility bugs](https://www.digitala11y.com/how-where-to-report-accessibility-bugs/)


### Design

- [ColorSafe](http://colorsafe.co/)- Empowering designers with beautiful and accessible color palettes based on WCAG Guidelines of text and background contrast ratios
- [Accessible Color Palette Builder](https://toolness.github.io/accessible-color-matrix/)


### Writing

- [Plain Language](https://plainlanguage.gov/) - Learn how to write in a way that makes it easier for people to read and understand.


### Other Useful Articles

- [The difference between keyboard and screen reader navigation](https://tink.uk/the-difference-between-keyboard-and-screen-reader-navigation/)
82 changes: 82 additions & 0 deletions guides/v5.9.0/accessibility/page-template-considerations.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
When considering an application's page or view structure, there are a few primary concerns that should be planned for:

- page title
- skip navigation links
- focus management


## Page Title

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.

Consider this format:

`Unique Page Title - Site Title`

<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"/>

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.

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.

For example, if we have a “posts” route, we can set the page title for it like so:


```handlebars {data-filename=app/routes/posts.hbs}
{{page-title "Posts - Site Title"}}
{{outlet}}
```

Extending the example, if we have a “post” route that lives within the “posts” route, we could set its page title like so:

```handlebars {data-filename=app/routes/posts/post.hbs}
{{page-title (concat @model.title " - Site Title")}}
<h1>{{@model.title}}</h1>
```

When your needs become more complex, the following addons facilitate page titles in a more dynamic and maintainable way.

- [ember-cli-head](https://github.com/ronco/ember-cli-head)
- [ember-cli-document-title](https://github.com/kimroen/ember-cli-document-title)

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).

You can test that page titles are generated correctly by asserting on the value of `document.title` in your tests:

```javascript {data-filename=tests/acceptance/posts-test.js}
import { module, test } from 'qunit';
import { visit, currentURL } from '@ember/test-helpers';
import { setupApplicationTest } from 'my-app-name/tests/helpers';

module('Acceptance | posts', function(hooks) {
setupApplicationTest(hooks);

test('visiting /posts', async function(assert) {
await visit('/posts');
assert.equal(document.title, 'Posts - Site Title');
});
});
```

## Skip Navigation Links

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.

<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"/>

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.

To read more about skip links, visit the [MDN docs](https://developer.mozilla.org/en-US/docs/Learn/Accessibility/HTML#Skip_links).


## Focus Management

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).

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:

- [ember-a11y](https://github.com/ember-a11y/ember-a11y)
- [ember-self-focused](https://github.com/linkedin/self-focused/tree/master/packages/ember-self-focused)
- [ember-a11y-refocus](https://github.com/MelSumner/ember-a11y-refocus)
21 changes: 21 additions & 0 deletions guides/v5.9.0/accessibility/testing.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
## Screen Reader and Browser Combinations

It is important to use a screen reader when checking to make sure your application is accessible.

There are assistive technologies (known as screen readers) available for all common desktop platforms and mobile devices.

- VoiceOver, integrated in Apple products
- Narrator, integrated in Windows products
- Orca, available for integration in Ubuntu, otherwise available as a download
- JAWS, proprietary software by Freedom Scientific, available for Windows
- NVDA, open source software, available for Windows
- TalkBack, integrated in Android products

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.

- Firefox & NVDA (Windows)
- IE & JAWS (Windows)
- Edge & Narrator (Windows)
- Safari & VoiceOver (MacOS)

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.
Loading

0 comments on commit 4c54e43

Please sign in to comment.