Awesome

ember-a11y-landmarks

The ember-a11y-landmarks addon helps you assign the role attribute that should go on landmark tags like <header> and <nav>, without needing to learn the intricacies of when to add roles or what they should be. A landmark is a special kind of semantic HTML tag that Assistive technology(AT) uses to parse a page correctly.

When is this addon needed? In a typical Ember app, almost everything gets wrapped in a <div>, but this can be confusing to tools like screen readers. The Assistive Technology expects that either landmark elements are direct descendants of the <body> element or that they have a particular role attribute. ember-a11y-landmarks handles this problem for you.

How this addon works

This addon helps add the correct roles to the following elements:

tagName	role
header	banner
nav	navigation
aside	complementary
main	main
form	form
footer	contentinfo

While semantic landmark tags are best for accessibility, some developers may be faced with working on an app that uses div tags instead. For those cases, this addon provides a way to add roles to a div element until they can be refactored (see Div Usage).

ember install ember-a11y-landmarks

Landmark Tag Usage

This addon is used like a block component. Just set the tagName attribute to header, nav, aside, main, form, or footer, and put your content inside the block. For example, here's a header:

<A11yLandmark @tagName="header">
    This is my header content
</A11yLandmark>

The resulting markup in the DOM will have the correct tag type and the role that should be used for that tag:

<header id="ember337" role="banner" class="ember-view">
    This is my header content
</header>

Div Usage

If a developer must use a div instead of a semantic tag like <header>, define landmarkRole instead of tagname. You can look up the correct landmark role in the How this addon works table. Here's a header example:

  <A11yLandmark @landmarkRole="banner">
      This is my header content (that should be refactored later to go inside a real header tag)
  </A11yLandmark>

In the DOM markup, this will result in a div with the specified role:

<div id="ember337" role="banner" class="ember-view">
     This is my header content (that should be refactored later to go inside a real header tag)
</div>

Form/Search Usage

If defining a form, no additional landmarkRole is required. However, if the form will be used as a search, then the landmarkRole value should be set to search.

Form:

<A11yLandmark @tagName="form">
    ...
</A11yLandmark>

Search:

<A11yLandmark @tagName="form" @landmarkRole="search">
    ...
</A11yLandmark>

Contributions

Contributions to this project are encouraged.

Compatibility

Ember.js v3.12 or above
Ember CLI v2.13 or above
Node.js v10 or above