Web Components punch list

Considerations for web component and custom control design:

If your control has the stuff below covered, excellent! If not then please implement it before shouting to the world about it being the next big thing. Or at least document its deficits and provide a health warning that the control is incomplete and not fit to use in production.

design considerationdescriptionYes/No
focusableCan you get to the control via the keyboard? Refer to Providing Keyboard Focus
keyboard operableCan you use the control with the keyboard? Refer to Keyboard Navigation
touch operableCan you use the control with touch gestures? With assistive technology enabled?
expected operationCan you operate the control using the standard keys (Refer to ARIA Widget Design Patterns) and/or touch gestures for the control type?
clear indication of focusCan you easily see it when the control has focus? Refer to Visible Focus (WCAG2)
labelThe control has a text label that is exposed as an accessible name in accessibility APIs
roleThe control has an appropriate role exposed in accessibility APIs
states and propertiesThe control has any UI states and properties that it has exposed in accessibility APIs
color contrast The control label/description/icon is perceivable/usable for low vision users (Use a color contrast checker.)
high contrast modeThe control is perceivable/usable when High Contrast Mode is enabled (e.g. Windows HC mode)

Take note:

The ARIA design patterns provide a most excellent and comprehensive set of requirements, for expected keyboard interaction and what role, state and property information needs to be exposed, for a large variety of custom controls.

Accessibility APIs

If the term accessibility APIs has you scratching your head, read Why accessibility APIs matter by the one and only Marco Zehe.

The accessibility tree

Tree of accessible objects that represents the structure of the user interface (UI). Each node in the accessibility tree represents an element in the UI as exposed through the accessibility API; for example, a push button, a check box, or container.

Example baseline test using the native HTML button element

Most of the considerations listed below do not need to be checked for a native HTML button as you get them for free (thanks to the browser implementers). If you build a custom control (for example, a custom button web component) you need to add most of this stuff yourself.

design considerationdescriptionYes/No
focusableUsing a test file attempt to tab to the control. (except when it is disabled)yes
operableUsing a test file attempt to make something happen (except when it is disabled)yes
expected operationButtons have standard expected keystrokes (enter or space) that will make something happen. Using a test file ensure that controls works as expected. (except when it is disabled)yes
indication of focusUsing a test file, can you see the control is focused? (except when it is disabled)yes
labelDefault method for providing an accessible name for button is via text content child of button element (there are others, whatever you use you you need to end up with an acc name exposed). You can check it using aViewer or other accessibility object inspection tool.yes
roleDefault role for <button> is already provided by browser (role:button). You can check it using aViewer or other accessibility object inspection toolyes
states and propertiesThe control has any UI states and properties that it has exposed in accessibility APIs. Standard states and properties for <button> are already provided by browser (focusable, focused, unavailable [if disabled attribute used). You can check them using aViewer or other accessibility object inspection tool.yes
color contrastCheck that contrast between the label/description/icon and its background is perceivable/usable for low vision users. Use a color contrast checker.yes
high contrast modeMost OS’s have a high contrast mode. Windows High Contrast Mode for example. enable the high contrast preference and ensure that controls are still understandable.yes


Obect Inspection tools such as aViewer can be used to test that your custom controls are exposing the correct information via accessibility APIs.

aVIEWER UI displaying information about a button element. It shows that the button has a correct accessible name and role and state.

Some Other Object inspection tools:

A personal opinion

Further reading


Categories: Development

About Steve Faulkner

Steve is the Technical Director at TPGi. He joined TPGi in 2006 and was previously a Senior Web Accessibility Consultant at vision australia. He is the creator and lead developer of the Web Accessibility Toolbar accessibility testing tool. Steve is a member of several groups, including the W3C Web Platforms Working Group and the W3C ARIA Working Group.