Developers FAQ

(Vastauksia ohjelmistokehittäjille, teksti on englanniksi)    

1. Screenreaders

  1. The desktop SC I am using for testing will not focus all of the content on the page when I navigate the page from top to bottom. Why?

There are two common reasons for this.

Incorrect SC use

Are you using the screen reader correctly? Both NVDA (Windows) and VoiceOver (macOS) can be used to either “jump” from one interactive element to another (similar to visual keyboard navigation with the tabulator key), or to navigate the page in the DOM order element by element, exposing all of the page content including passive text and images.

For the latter use mode, which should be employed in testing, you MUST NOT use the tabulator (TAB) key. Instead, you must command the SC to advance element by element. On NVDA, you do this with the up/down arrow keys. On VO, you use VO+Right/Left arrow keys by default.

NOTE: If the SC is in the Forms aka input mode (NVDA), or has delved inside a container (VO), you have to first return to the normal navigation mode before you can proceed along the page. To do this, on NVDA press ESC or NVDA+Space; on VO, press Shift+VO+Up Arrow or Shift+VO+Down Arrow to ascend and descend (step by step) to/from a container.

Aria-hidden

There may be content on your page that has been specifically hidden from assistive technology. Look for elements with aria-hidden=”true” attributes. If the content should be exposed to assistive technology, remove the aria-hidden attribute.

2.     Working with content

  1. How do I hide content from assistive technology without hiding it visually or removing it from the page?

Use the aria-hidden=”true” attribute. The DOM tree inside the element, and the element itself, will be made non-existing and inaccessible to screenreaders.

<div class=”embedded-interactive-map” aria-hidden=”true”> <iframe><..</iframe></div>

Note: You cannot make an element unfocusable to keyboard users (navigating the web page with the tabulator key) by using aria-hidden. The attribute only affects assistive technology, and keyboard navigation is not a form of assistive technology.

  1. How do I make an element focusable or unfocusable for keyboard users?

Use the tabindex attribute. Tabindex=”0” will mark the element as part of the page focus order. It can then be tabbed into with a keyboard. Tabindex”-1”, in turn, makes the element unfocusable for keyboard users.

Tabindex=”-1” elements can still be programmatically focused (e.g. by Javascript HTMLElement.focus() method). They can also be focused by screen readers.

To make content only available to pointer device users (mouse, touch), use both tabindex=”-1” and aria-hidden=”true” together.

  1. What is the difference between ALT=”” and aria-hidden=”true”?

The ALT attribute is used on <img> tags. When the attribute has an empty string or has no value, assistive technology hides the image as if it did not exist on the page.

Aria-hidden, unlike ALT, can be used with any tag. An <img> tag can, of course, contain both attributes. In some situations, this can be useful: The image can be hidden from screen readers without having to give it an empty ALT text.

<a href=”…”>Visit our sponsor SomeCompany<img alt=”Logo: SomeCompanyName” aria-hidden=”true”></a>

Here, the image alt is shown to visual users in case the image fails to load (pointing at an external resource, perhaps), but screen reader users will not perceive the image due to its aria-hidden status. This is done because the logo image has no informative purpose and is aimed only at visual users. Removing unnecessary parts makes the link easier to comprehend for a screen reader user.

One could also write:

<a href=”…”>Visit our sponsor: SomeCompany<img alt=””></a>

This, too, hides the image from screen readers, but will not display ALT for text-only browser users or when the image fails to load. That is, the image is treated as decorative.

Both methods are sound. The choice between the two is a service design decision.

  1. I use the <svg> tag for images, but screenreaders will not read the ALT attribute. How do I solve this?

The ALT attribute can only be used with the <img> tag. On <svg>, you can use the following attributes to provide an accessible name for screen readers:

  • role=”img”
  • aria-label=”The image ALT”.
  1. How do screen readers regard CSS display:none and CSS visibility:hidden?

Visually, both methods remove content from the web page, yet are not interchangeable: Visibility:hidden elements will retain their space on the page, as if they were only made inactive and transparent, whereas display:none elements are altogether removed from the page.

Screenreaders, however, will treat both definitions similarly: Content marked with either property will be completely hidden from the user.

  1. What do I need to take into account when embedding content as frames?

Frames have to be named (WCAG 1.3.1). The correct way to do this is with a title attribute: <iframe title=”Video: How to do XYZ” src=”…”>

When using the <frame> tag, provide also a noframes alternative if possible (https://www.w3.org/WAI/wcag-curric/noframes.htm).

  1. What is the difference between role=”alert” and aria-live? Why should I use one over the other?
  • Role=”alert” acts as a live announcement in the same fashion as a live region would. SC will announce it even when the element is unfocused.
  • Role=”alert” need no pre-set live region. The alert is announced immediately when an element is given the attribute or when an element with the attribute is inserted in the DOM. It can, therefore, be used spontaneously and without a preparation.
  • Role=”alert” interjects the SC, which will provide the announcement at once.
  • To this end, SC will also describe the announcement as alert or a high-priority announcement. It should, therefore, not be used for routine live messages.
  • Use a live region if you can utilize a pre-set region that hosts announcements the user would expect. For instance, announcing how many search results were/are being produced during a search that updates the page content in real time, would not necessitate an alert, as the live region exists on the page naturally and conveys information of normal priority.

<div aria-live=”polite”>5 results found.</div>

However, inserting an error notification spontaneously on the page could, In turn, be a use case for role=”alert”.

Some example use cases are found on the demo page on the following elements: Spinners, Notifications, Log, Combobox.

  1. Where in the banner should the “jump to content” link be placed?

Rule #1: Place it as the very first user-visible element on the page. In other words, there should be no links, images or text preceding it.

Rule #2: Make sure the link is wrapped inside a landmark or landmark-equal container. In practice, this means the link should be contained within a <header> or <div role=”banner”>. Otherwise, some accessibility checkers will complain that the page features content which lies without a landmarked region. Users are little affected by that issue, though.

  1. My links have an icon attached to them designating them as external links or links that open a specific kind of a document. How do I define the anchor tag so that screen reader users understand it correctly?

A number of methods are available. Below is a simple technique employed on the demo page.

Using aria-label:
<a href=”…” aria-label=”Siteimprove (link points outside this web site).” style=”…”> Siteimprove <img src=”…” class=”ExternalTextLinkSymbol” alt=””></a>

A similar result can be achieved by employing a visually hidden extension to the link text, which a screen reader exposes, as it will not heed CSS styling:
<a href=”…” style=”…”>Siteimprove<span class=”visually-hidden” >(Link points outside this web site)</span><img src=”…” class=”external-link-symbol” alt=””></a>.

Rationale:

  • The icon has an empty ALT to conceal it from screen readers. The user in this case need not be described that there is an image attached to the link, since the image is only a visual indicator aimed at visual users.
  • Instead, the link as a whole has an aria-label (approach 1), which defines how the link Is described to assistive technology. That the link has a non-standard role, is told in the aria label. Hence, the icon is now unnecessary for screen readers.
  • Similarly, the second approach appends the non-standard role description to the link text. Now, it is unnecessary to repeat that description in the image element.
  • The benefit here is that the link is made atomic: There is a single link with a single description, even though technically the link comprises two parts (text and image). This has implications on how assistive technology describes the link; see below.

Compare: Let us use the following (very logical) code instead:

<a href=”…” class=”…”> Siteimprove <img src=”…” class=”…” alt=”External link”></a>

Here, the icon has an ALT text describing the information it conveys. Hence, the link is described in two parts in much the same way it is perceived visually. This makes a lot of sense and is correct.

However, from this definition follows that some screen readers will faithfully expose the link as comprising two different elements – “Siteimprove” and “External link” – because there is both a link text and an image element.  While this is perfectly fine from WCAG point of view, in practice users may find a link described in this fashion less easy to understand when they navigate the page element by element.

The reason is that some screen readers will only announce the first link part when the link is focused in element-by-element navigation. The second part, the image and its ALT about an external status, is, correspondingly, announced only after the user navigates forward along the page. This, in turn, usually happens after the user has already decided whether to click the link or not, as they cannot, of course, “see” ahead and know that the link still “continues”. This, however, has to do with the fashion in which some screenreaders work, and is not the fault of the developer. Technically, the link is correctly defined.

The latter method, that of using the image ALT, is therefore OK, but the author of this FAQ prefers the first two approaches, of an “atomic” link description with a tailored link text or an aria-label, given the unambiguity the atomic type of definition offers to all screen reader users.

  1. I need to place a link to a list of references in a text paragraph. How do I describe the link to assistive technology?

In a situation similar to the below:

This is a text paragraph. Here lies a sentence that will feature an anchor link pointing at a reference [1].

(At the bottom of the text/page)

[1] Article XYZ, Author, 2020. Available online: Link to article

[2] Keynote at a webinar XYZ, Speaker, Event, 2020. Link to a recording.

[3] …

You can define the reference link in the paragraph like so:

<a href=”#ref01” aria-label=”Reference: Article XYZ.” onmouseover=”…” >[1]</a>

That is, you can systematically inject an aria-label with the prefix “Reference” (or similar) and e.g. the title of the reference (spliced off the first comma, etc.) as the link’s description. This will be more informative to the assistive technology users than mere “[1]“, and is easy enough to automate.

4.     Single Page Applications

  1. How can I make screenreaders announce a new page title when I update the title tag to reflect a change in the page context in my SPA?

Please see the Single Page Apps guide for implementation ideas

5.     Tailor-built web page elements

  1. What is the difference between <button aria-pressed=”true”/”false”> (or role”=button” with aria-pressed) and input type=”checkbox” (or role=”checkbox”)?

From assistive technology point of view, there is little to no semantic difference between a toggle button (aria-pressed) and a checkbox. Both can assume a on/off value and are described as checked/pressed or unchecked/not pressed by screen readers.

The terms used do vary, though. For instance, both NVDA and VoiceOver describe the unpressed toggle button status somewhat vaguely, yet make it very clear whether a checkbox is checked or not. Moreover, users are much more familiar with the checkbox role and its pertinent vocabulary than the more rarely used toggle button element.

For these reasons, it is recommended to use the checkbox pattern unless there is a specific reason to prefer a toggle button. Visually, both elements can look the same, as their role and value can be defined independently.

The demo page contains a toggle button example in the Aria live log element. The same button could just as well be described as a checkbox for assistive technology by simply altering tis role and value attributes, like so:

<span role=”button” aria-pressed=”true”>…

<span role=”checkbox” aria-checked=”true”>…

Or even:

<button role=”checkbox” aria-checked=”true”>…

<img role=”checkbox” aria-checked=”true”>…

Etc.

Alkuperäinen versio: Tero Pesonen / Siteimprove
Luotu: 4.3.2021