WebsightWhat it asks for, in plain English
Every interactive control needs three things that software can read: a name (what it is called), a role (what kind of thing it is: button, checkbox, tab, slider) and, where it has one, its current state or value (checked, expanded, 40 per cent). Changes to the state must be exposed too, so a screen reader can say 'Notifications, switch, on' and then 'off' when it changes.
Native HTML gives you all of this for free: a button element is a button, an input of type checkbox has a checked state, a select has a value. The criterion bites when you build controls out of div and span with CSS and JavaScript. Then you have to add the role, the name and the state yourself with ARIA, and keep the state attributes updated as the control is used.
It also covers frames: each iframe needs a title so people can tell what is inside it.
This is an independent explanation. The binding wording is the W3C Recommendation, and the W3C's own Understanding 4.1.2 page has the full intent, techniques and definitions.
Who it affects
A screen reader user reaches a clickable div styled as a button and hears only 'Save' with no hint it can be pressed, or reaches a custom toggle and cannot tell whether it is on.
Someone using voice control says "click Save" and nothing happens, because the element has no role and no accessible name the software can match.
A switch-access user stepping through controls one at a time gets no feedback that a custom checkbox has been ticked.
Example
<div class="btn">Save</div>
<div class="toggle on">
<span class="knob"></span>
</div>
<span>Email alerts</span>Both look right and work with a mouse. A screen reader hears 'Save' as plain text and nothing at all for the toggle.
<button type="button">Save</button>
<button type="button" role="switch" aria-checked="true">
<span class="knob" aria-hidden="true"></span>
Email alerts
</button>Announced: 'Save, button' and 'Email alerts, switch, on'. Your script must update aria-checked each time the switch flips.
How to check it
- Turn on a screen reader (VoiceOver, NVDA or similar) and Tab to each custom control: tabs, menus, toggles, sliders, accordions, icon buttons.
- Listen for three things: a name, a role (button, checkbox, tab) and a state where it has one (expanded, selected, checked).
- Operate the control and check the announced state changes with it.
- Check every iframe has a title attribute that says what it contains.
What Websight checks for 4.1.2
Websight runs these automated checks for 4.1.2:
aria-allowed-attr
Every ARIA role comes with a short list of attributes it understands.
A
aria-braillelabel must have a matching text label
aria-braille-equivalent
aria-braillelabel and aria-brailleroledescription let you give a braille display a shorter or contracted version of a control's name or role.
A
ARIA attributes must follow the conditions of the element's role
aria-conditional-attr
A few ARIA attributes are allowed on a role only under conditions.
A
Deprecated ARIA roles must not be used
aria-deprecated-role
ARIA retires roles from time to time.
A
aria-label must not be used on div, span or p without a role
aria-prohibited-attr
aria-label and aria-labelledby only work on elements that can have a name: controls, landmarks, images, headings, tables and similar.
A
Required ARIA attributes must be provided for the role
aria-required-attr
Some ARIA roles only make sense with a state or value attached.
A
ARIA roles must be valid
aria-roles
The role attribute only accepts names from the ARIA list: dialog, button, tab, listbox and so on.
A
Tabs must have an accessible name
aria-tab-name
Every element with role="tab" needs a name: the words a screen reader speaks when the tab gets focus and the words a voice control user says to pick it.
A
Tooltips must have an accessible name
aria-tooltip-name
An element with role="tooltip" needs a name, which is normally just the text inside it.
A
ARIA attributes must have valid values
aria-valid-attr-value
Each ARIA attribute accepts a particular kind of value: true or false, a number, a word from a short list, or the id of another element.
A
ARIA attributes must have valid names
aria-valid-attr
Browsers only act on attribute names that exist in the ARIA specification.
A
ids used by ARIA and labels must be unique
duplicate-id-aria
aria-labelledby, aria-describedby, aria-controls and the label for attribute all work by id.
A
Form fields must have labels
label
Every input and textarea needs a label that is programmatically tied to it, not just sitting nearby.
A
Select menus must have an accessible name
select-name
A select element is a drop-down list of choices.
A
Input buttons must have discernible text
input-button-name
An input element with type="submit", type="button" or type="reset" draws a button whose text comes from its value attribute.
A
ARIA input fields must have an accessible name
aria-input-field-name
When a div or span is given a form role such as textbox, combobox, listbox, slider or spinbutton, assistive technology treats it as a field.
A
ARIA toggle fields must have an accessible name
aria-toggle-field-name
Elements with role="switch", role="checkbox", role="radio", role="menuitemcheckbox" or role="menuitemradio" are toggles: they are on or off, checked or not.
A
Image buttons must have alternative text
input-image-alt
An input with type="image" is a submit button that looks like a picture, often a magnifying glass or an arrow.
A
Image map areas must have alternative text
area-alt
An image map lets one picture have several clickable regions, each defined by an area element with an href.
A
Hidden elements must not contain anything you can Tab to
aria-hidden-focus
aria-hidden="true" tells screen readers to ignore an element, but it does not stop the Tab key reaching the links and buttons inside.
A
Links must have text a screen reader can announce
link-name
Every link needs text that a screen reader can announce and a voice control user can say.
A
Buttons must have a name that says what they do
button-name
A button needs a name that assistive technology can announce.
A
Expandable sections need a summary with words in it
summary-name
The summary element is the clickable heading of a details element, the browser's built-in expand and collapse control.
A
Do not put one control inside another
nested-interactive
A button, a tab, a switch and similar controls are announced as one thing; whatever is inside them is treated as their label, not as separate controls.
A
ARIA buttons, links and menu items need a name
aria-command-name
When you give an element role="button", role="link" or role="menuitem", you are promising assistive technology that it is a control.
A
Frames must have a title
frame-title
An iframe is a window onto another page: a map, a video, a booking form, a payment field.
A
Frames on the same page must have different titles
frame-title-unique
If a page has several frames, each needs its own title.
A
Never hide the whole page with aria-hidden
aria-hidden-body
aria-hidden="true" tells assistive technology to ignore an element and everything inside it.
axe-core also has a rule for 4.1.2 that Websight does not run (marked experimental or deprecated):
Websight runs axe's button name, link name, ARIA role, ARIA attribute and ARIA state checks: it catches controls with no accessible name, invalid roles, missing required ARIA attributes, and aria-labelledby pointing at ids that do not exist. It cannot tell whether a state actually updates when the control is used, or whether the name is any good.
Practical tips
- Use the native element first. A button, a details element or an input of type range need no ARIA at all.
- If you must use ARIA, follow the pattern for that widget exactly and keep the state attributes in sync with what is on screen.
- Hide purely visual parts (icons, knobs) with aria-hidden so they do not add noise to the name.
Other criteria in guideline 4.1, Compatible
- 4.1.1 Parsing (level A)
- 4.1.3 Status Messages (level AA)