Accessibility v4 → v5

New built-in behaviours

Scalability

Adopted relative unit measurement (rem) instead of fixed (px)

Rem units allow for dynamic scaling based on a single root font size and adjust proportionally. Giving greater flexibility over pixels. This is particularly beneficial for users who adjust their browser settings for larger text, as these units scale according to user-defined preferences.

Reference: WCAG 2.2 SC 1.4.4 Resize Text

---

Headings

Automated heading levels

Aria levels are calculated dynamically, based upon the existence of a title on the defined parent and the offset through the tree. For example, if a component has no article or block title, its aria level will be calculated relative to the page heading level 1, this is as the block and article offsets are not applied.

See: Automated aria levels

Reference: WCAG Headings

---

Navigation

Navigation button order

Button order was introduced to ensure the DOM order matches the visual order of the navigation bar. This also gives flexibility in the visual display of the navigation bar. The sorting order can be configured per course.

See: Navigation sorting order on the wiki

Reference: WCAG C27: Making the DOM order match the visual order

Navigation button labels

As part of the navigation button API, button labels were introduced to provide a text label based upon the button aria-label. Icons are a helpful tool to improve perception, but they aren't a replacement for text. Adding a visible text label makes the button’s purpose obvious.

See: Navigation Button API on the wiki

Skip to main content

Added the ability to skip to menu or page main content bypassing the navigation bar. Focus is directed to the main content with the first focusable element typically being the menu or page title.

Reference: WCAG G1: Adding a link at the top of each page that goes directly to the main content area

---

ARIA question field introduced across question components

When focusing on a question group or radiogroup, reading the component displayTitle, body & instruction in reference to the question options is too verbose. The ariaQuestion field provides the option to specify a succinct aria-label for the question with the original aria-labelledby as a fallback.

See: Adds ariaQuestion field to JSON default settings

---

Allow question answer buttons to be keyboard and screen reader accessible

Used by ButtonsView to retrieve question-specific user answer / correct answer text when question _canShowModelAnswer is enabled. When the learner selects the 'show correct answer' / 'hide correct answer' button, a 'live region' gets updated containing the user answer / correct answer aria-label text. Prior to this, the button was inaccessible but still enabled for visual users with question-specific user answer / correct answer provided by marking only (ticks and crosses displayed on answer options).

See: Allow correct answer/hide correct answer buttons to be keyboard/screen reader accessible

---

Support user preference for motion

Some users experience distraction or nausea from animated content. For example, if scrolling a page causes elements to move such as content transitioning into the page. When _isPrefersReducedMotionEnabled is enabled and prefers-reduced-motion is set in the browser (user preference) an is-prefers-reduced-motion class is appended to the html tag.

See: Animations in theme should use reduced motion media queries

Reference: WCAG C39: Using the CSS reduce-motion query to prevent motion

---

Support for semantic quotes

It's important to ensure that the HTML used in Adapt is semantically correct to ensure the content is accessible to as many users as possible. Representing quotes with CSS styling alone is not identified by assistive tech. The text will read as any other body text on the page regardless how different the visual styling is. Adapt styling for <blockquote> and <q> was introduced to Vanilla and a brief explanation of some common HTML elements has been detailed on the wiki.

See: Making quotes semantic to encourage inclusive design, Semantic HTML Quotation on the wiki

Reference: WCAG H49: Using semantic markup to mark emphasized or special text

---

Error message when no input provided for question

For question components, the submit button is now disabled until the learner makes a selection. Note: If you prefer the old behaviour, you can use the instructionError plugin to restore it and display an error reiterating the question instructions on an invalid submission.

See: Error message when no input provided for question

Updated and improved built-in behaviours

Heading attribute helper

The heading attribute helper {{a11y_attrs_heading}} was deprecated in favour of {{a11y_aria_level}} as it's clearer for the handlebars. The helper produces the role and default heading level attribute for an element. The default heading level is taken from the map in config.json: _accessibility._ariaLevels. An absolute value would be "1" or "2" etc. A relative increment would be "@page+1" or "@block+1" (as per Automated heading levels above). They are calculated from ancestor values, respecting both _ariaLevel overrides and not incrementing for missing displayTitle values.

See: heading.hbs example

---

Heading completion settings

• model: _disableAccessibilityState replaced by _isA11yCompletionDescriptionEnabled.
• model: _isA11yCompletionDescriptionEnabled: true Will cause the HeadingView to render the completion description that describes the state of the course to assistive tech.

See: Add _isA11yCompletionDescriptionEnabled to schema and remove legacy _disableAccessibilityState

---

Focus control

Readability, focus and seeking forward

The Adapt Framework has two functions to aid in the allocation of focus, both of which seek forward in the document and assess the readability of elements as they go.

a11y.focusFirst($element) Assigns focus to either the specified element if it is readable or the next readable element. This replaces the deprecated $("selector").focusOrNext().

a11y.findFirstReadable($element) Assigns focus to the first readable element after the specified element. This replaces the deprecated $("selector").focusNext().

These behaviours allow us to more loosely move the screen reader cursor and focus, relying on Adapt Framework to handle the correct allocation for us.

Visible focus

Rather than relying on keyboard detection, :focus-visible is used instead. The :focus pseudo-class always matches the currently-focused element and displays a visible focus ring, which some consider obtrusive. The :focus-visible pseudo-class only matches the focused element if the user needs to be informed where the focus currently is. The :focus-visible pseudo-class respects user agents' selective focus indication behaviour while still allowing focus indicator customisation.

See: MDN :focus vs :focus-visible, Updated focus to focus-visible

Self-disabling buttons

The Adapt Framework occasionally makes use of functionality we call a 'self-disabling button'. The Submit button used in question components is a good example of this.

Using aria-disabled improves discoverability as buttons will not be removed from the focus order of the page. Instead, it signals to assistive tech that a button is disabled whilst reading any associated label, for example “Submit button, unavailable”. Disabled buttons using the disabled attribute are typically ignored by assistive tech meaning a user won't be aware a button exists until it becomes available whilst the button is visually available to a sighted user. Note, developers will still need to use JavaScript to fully disable the functionality of the element while also changing the appearance of the element so sighted users know it is disabled via the .is-disabled class.

See: Switch from disabled to aria-disabled for ButtonsView

Reference: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-disabled, https://css-tricks.com/making-disabled-buttons-more-inclusive/

---

Popups

With browsers and screen readers there are two ways of navigating to content under a modal popup: via tabbing and via the screen reader cursor.

Content restrictions

To prevent users from accessing content outside of the modal popups, Adapt Framework can restrict both the tabbing and screen reader cursor, isolating the user to just the popup content.

a11y.popupOpened($element) restricts the tabbing and screen reader access to just the element provided. This replaces the deprecated Adapt.trigger("popup:opened", $popupElement).

a11y.popupClosed($target) reverts the tabbing and screen reader access and moves the focus to the element provided. This replaces the deprecated Adapt.trigger("popup:closed", $focusTarget).

Tab wrapping

When a modal popup, such as Notify or Drawer, is displayed, tabbing should work the same as it does for pages, in that the focus should circle around the browser UI when you leave the bottom of the content. tabindex="0" was added to {{{a11y_wrap_focus}}} to return focus to the first focusable element within the modal popup.