index.rst (20276B)
1 ======================= 2 Accessibility Inspector 3 ======================= 4 5 The Accessibility Inspector provides a means to access important information exposed to assistive technologies on the current page via the accessibility tree, allowing you to check what's missing or otherwise needs attention. This article takes you through the main features of the Accessibility Inspector and how to use it. 6 7 A (very) brief guide to accessibility 8 ************************************* 9 10 Accessibility is the practice of making your websites usable by as many people as possible. This means trying your best to not lock anyone out of accessing information because of any disability they may have, or any other personal circumstances such as the device they are using, the speed of their network connection, or their geographic location or locale. You can find more extensive information in the `Accessibility <https://developer.mozilla.org/en-US/docs/Web/Accessibility>`_ section of MDN Web Docs. 11 12 Here we are mainly talking about exposing information to people with visual disabilities — this is done via the `accessibility APIs <https://www.smashingmagazine.com/2015/03/web-accessibility-with-accessibility-api/>`_ available inside web browsers, which expose information on what roles the different elements on your page play (e.g., are they just text, or are they buttons, links, form elements, etc.?). 13 14 Semantic DOM elements have roles assigned to them by default that hint at what their purpose is. Sometimes, however, you need to use some non-semantic markup (e.g., `div <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div>`_ s) to build a complex custom control, and the control won't have a default role that reflects its purpose. In such a situation, you can use `WAI-ARIA <https://developer.mozilla.org/en-US/docs/Learn/Accessibility/WAI-ARIA_basics>`_ role attributes to provide your own roles. 15 16 Roles and other information exposed by browser accessibility APIs are presented in a hierarchical structure called the accessibility tree. This is a bit like the DOM tree, except that it contains a more limited set of elements and slightly different information about them. 17 18 Assistive technologies like screenreaders use this information to find out what's on a web page, tell their users what's there, and enable them to interact with the page. The Accessibility Inspector also uses this information to provide valuable accessibility debugging capabilities in the DevTools. 19 20 21 Accessing the Accessibility Inspector 22 ************************************* 23 24 When you first open any of the other Developer Tools, the accessibility features are turned off (unless you've already got them turned on in another browser tab, or got the Firefox accessibility engine started already, e.g., you might be a screenreader user or tester). 25 26 The accessibility inspector is automatically enabled when you do one of the following: 27 28 29 - Choose **Accessibility** in the **Tools > Browser Tools** menu. 30 - Select the **Accessibility** tab in the Developer Tools toolbox. 31 - Right-click in the main browser window, and choose **Inspect Accessibility Properties** in the context menu. 32 - Right-click an item in the HTML pane of the :doc:`Page Inspector <../page_inspector/index>`, and choose **Show Accessibility Properties** in the context menu. 33 34 35 Once activated, the accessibility engine remains running until you close the Developer Tools toolbox. 36 37 .. note:: 38 39 The accessibility engine runs in the background when the accessibility features are turned on. When enabled it may affect the metrics from other panels such as :doc:`Memory <../memory/index>` and :doc:`Performance <../performance/index>`, and have some impact onoverall browser performance. 40 41 42 If you don't wish to allow the accessibility features to be automatically enabled, you can use the `Configuration Editor <https://support.mozilla.org/en-US/kb/about-config-editor-firefox>`__ (also known as ``about:config``) to define the preference ``devtools.accessibility.auto-init.enabled``, and set it to ``False``. 43 44 If you don't wish to use the accessibility features at all, you can use the `Configuration Editor <https://support.mozilla.org/en-US/kb/about-config-editor-firefox>`__ to set the preference ``devtools.accessibility.enabled`` to ``False``. If you do this, the methods listed above for activating the Accessibility Inspector do nothing. 45 46 47 Features of the Accessibility panel 48 *********************************** 49 50 The enabled accessibility panel looks like so: 51 52 .. image:: accessibility-inspector-tabbing_order.png 53 :class: border 54 :alt: Shows issue checker toolbar with "contrast" and "text label" options 55 56 57 On the left-hand side, there is a tree diagram representing all the items in the accessibility tree for the current page. Items with nested children have arrows that can be clicked to reveal the children, so you can move deeper into the hierarchy. Each item has two properties listed: 58 59 60 - *Role* — the role this item has on the page (e.g., ``pushbutton``, or ``footer``). This can be either a default role provided by the browser, or a role given to it via a WAI-ARIA ``role`` attribute. 61 - *Name* — the name this item has on the page. The name depends on the element; for example, the name of most text elements is their ``textContent``, whereas form elements' names are the contents of their associated `label <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/label>`_. 62 63 64 On the right-hand side, you can see further information about the currently selected item. The listed properties are as follows: 65 66 67 - *name* — the item's name, as described above. 68 - *role* — the item's role, as described above. 69 - *actions* — a list of actions that can be performed on the item, for example, a pushbutton would have "Press" listed, while a link would have "Jump" listed. 70 - *value* — the value of the item. This can mean different things depending on the type of the item; for example, a form input (role: entry) would have a value of whatever is entered in the input, whereas a link's value would be the URL in the corresponding ``<a>`` element's ``href``. 71 - *DOMNode* — the type of DOM node that the item in the accessibility tree represents. You can click on the "target" icon that comes after it to select the node in the :doc:`Page Inspector <../page_inspector/index>`. Hovering over the "target" icon highlights the DOM node in the page content. 72 73 .. image:: dom-node-target-icon.png 74 :alt: DOMNode property in accessibility inspector with target icon highlighted 75 76 - *description* — any further description provided on the element, usually by the content of a title attribute. 77 - *keyboardShortcut* — any keyboard shortcut that is available to activate the element, as specified in an ``accessKey`` attribute. 78 - *childCount* — the number of child items the current item has in the accessibility tree hierarchy. 79 - *indexInParent* — an index value indicating what number child the item is, inside its parent. If the item is the first item inside its parent, it has a value of 0. If it is the second, it has a value of 1. And so on. 80 - *states* — a list of the different accessibility-relevant states that can apply to the current item. For example, one of the links in one demo has states of focusable, linked, selectable text, opaque, enabled, and sensitive. For a full list of internal states, see Gecko states. 81 - *relations* — a list of the accessibility-relevant relationships between this item and other items. For example, in a form, an entry item could have a "labelled by" relation with a label item, which in turn has a "label for" relation to the entry item. 82 - *attributes* — a list of all the accessibility-relevant attributes that are applied to the item. This can include style-related attributes such as margin-left and text-indent, and other useful states for accessibility information, such as draggable and level (e.g., what heading level is it, in the case of headings). For a full list of possible attributes, see Gecko object attributes. 83 84 85 .. note:: 86 The exposed information is the same across all platforms — the inspector exposes Gecko's accessibility tree, rather than information from the platform accessibility layer. 87 88 89 Keyboard controls 90 ----------------- 91 92 The *Accessibility* tab is fully keyboard-accessible: 93 94 - You can tab between *Check for Issues*, *Simulate*, *Show tabbing order*, and left and right panels. 95 - When one of the panels is focused, you can move the focus up and down items using the up and down arrow keys, and use the left and right arrow keys to expand and collapse expandable rows (e.g., different hierarchy levels of the accessibility tree). 96 97 98 Print accessibility tree to JSON 99 -------------------------------- 100 101 You can print the contents of the accessibility tree to JSON by right-clicking on an entry in the Accessibility tab and selecting **Print to JSON:** 102 103 .. image:: accessibility-inspector-print_tree_to_json.png 104 :alt: Print to JSON right-click menu in left panel 105 :class: border 106 107 When you do, you will get a new tab with the selected accessibility tree loaded into the JSON viewer: 108 109 .. image:: accessibility_json.png 110 :alt: Accessibility tree loaded in new tab JSON viewer 111 :class: center 112 113 Once opened, you can save or copy the data as necessary. The JSON viewer can also show you the raw JSON data on a separate tab in the viewer. 114 115 116 Show web page tabbing order 117 --------------------------- 118 119 People who are unable to navigate a page with the mouse or a trackpad can use the :kbd:`tab` key to toggle through focusable items on the page (i.e. buttons, links, form controls).The order that items are focused is one of the most important aspects of web accessibility, as it allows keyboard users to properly navigate a web page — if the tab order is incorrect, the page may be confusing! 120 121 Firefox can enable a visual overlay showing the tabbing order. This provides a high-level overview of how the page will be navigated using the :kbd:`tab` key, which may highlight problems more effectively than tabbing through the elements. The overlay is toggled on/off using the**Show Tabbing Order** checkbox. 122 123 .. image:: accessibility-inspector-show_tab_order.png 124 :alt: Accessibility inspector and page with checkbox Show tab order selected. 125 :class: border 126 127 128 All focusable items have a numbered marker and the currently focused item is highlighted in a different color. In some cases the marker may be hidden by other elements, as is true for items 1 and 2 in the page below. 129 130 .. image:: accessibility-inspector-hidden_items.png 131 :alt: A page where some of the markers for selection items are hidden 132 :class: center 133 134 These become visible in the overlay when the item is the current item. 135 136 .. image:: accessibility-inspector-hidden_item_revealed.png 137 :alt: Shows a hidden selection item in the tabbing order overlay when it is selected. 138 :class: center 139 140 141 .. note:: 142 143 The overlay reflects the tab order at the time that the checkbox is selected (i.e. it is not dynamic). If a user does anything that adds items to the tab order (e.g. opens a visual element that contains more links), these new items will not be reflected in the overlay until the Accessibility Inspector is re-launched. 144 145 146 Check for accessibility issues 147 ------------------------------ 148 149 You can check for accessibility issues by clicking the drop-down menu next to: **Check for issues**. The available menu items include: 150 151 152 - **None** — Don't show the possible list of issues. 153 - **All Issues** — Check for all types of issues. 154 - **Contrast** — Check for `issues with visual contrast. <https://developer.mozilla.org/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable/Color_contrast>`_ 155 - **Keyboard** — Check for `issues with navigating via a keyboard. <https://developer.mozilla.org/en-US/docs/Web/Accessibility/Understanding_WCAG/Keyboard>`_ 156 - **Text Labels** — Check for `issues with missing text labels. <https://developer.mozilla.org/en-US/docs/Web/Accessibility/Understanding_WCAG/Text_labels_and_names>`_ 157 158 159 When you select one of the menu items, Firefox scans your document for the type of issues you selected. Depending on the size and complexity of your document, this may take a few seconds. When the scan is complete, the left side of the Accessibility Inspector panel displays only the items that have that type of issue. In the right side of the panel, the *Checks* subpanel lists the specific issue with the selected node. For each type of issue, there is a **Learn more** link to further information on *MDN Web Docs* about the issue. 160 161 162 .. image:: accessibility-inspector-check_for_issues.png 163 :alt: Accessibility Inspector - Showing the options when you select the Check for Issues button 164 :class: border 165 166 167 The menu items act as toggles. Select the item to view that type of issue; select the item again to clear the display of issues of that type. 168 169 Issues with a particular item are always displayed in the *Checks* subpanel as you browse the tree. The **Check for issues** menuitems are a quick way to view all and only those items that have issues. 170 171 172 Simulate 173 -------- 174 175 The Accessibility Inspector offers, a :doc:`simulator <simulation/index>` that lets you see what a web page would look like to users with various forms of *color vision deficiency* (better known as "color blindness"), as well as *contrast sensitivity loss*. 176 177 178 Notable related features 179 ************************ 180 181 When the accessibility features are turned on, there are a number of useful additional features available in the DevTools, which are detailed below: 182 183 Context menu options 184 -------------------- 185 186 An extra context menu option is added, both for the general context menu on the web page when right-clicking a UI feature, and the HTML pane of the page inspector when right-clicking a DOM element: 187 188 .. image:: web-page-context-menu.png 189 :alt: context menu in the browser viewport, with a highlighted option: Inspect Accessibility Properties 190 :class: border 191 192 193 .. image:: dom-inspector-context-menu.png 194 :alt: context menu in the DOM inspector, with a highlighted option: Show Accessibility Properties 195 :class: border 196 197 When you choose the *Inspect Accessibility Properties*/*Show Accessibility Properties* context menu options, the *Accessibility* tab is immediately opened to show the corresponding accessibility tree item and its properties. 198 199 .. note:: 200 201 Some DOM elements do not have accessibility properties — in that case, the *Inspect Accessibility Properties*/*Show Accessibility Properties* context menu item is grayed out. 202 203 204 Highlighting of UI items 205 ------------------------ 206 207 In the Accessibility tab, when the mouse hovers over accessibility items, you can see a semi-transparent highlight appear over the UI items they relate to, if appropriate. The role and name of the item will be shown in a small information bar along with color contrast information if appropriate. This is useful for determining how the items in the accessibility tree relate to the UI items on the actual page. 208 209 In the following example, you can see that the image has been highlighted and its role, graphic, name, "Road, Asphalt, Sky, Clouds, Fall", and the color contrast ratio, 3.46, appears in the information bar above it. 210 211 .. image:: image_accessibility.png 212 :alt: image has been highlighted and graphic, "Road, Asphalt, Sky, Clouds, Fall", and Contrast:3.46 warning sign, appears in the information bar above it 213 :class: border 214 215 216 Color contrast 217 ~~~~~~~~~~~~~~ 218 219 Contrast ratio information is particularly useful when you are designing the color palette for your website because if the contrast is not sufficient, readers with visual impairments such as low vision or color blindness will be unable to read the text. See `Color contrast <https://developer.mozilla.org/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable/Color_contrast>`_ for details about recommended contrast ratios. 220 221 For example: 222 223 .. image:: screen_shot_2019-01-29_at_10.11.13.png 224 :alt: A screenshot of color contrast highlighter with warning sign where text contrast if below the AA WCAG threshold. 225 :class: center 226 227 The color contrast in the image above is 2.86, so potentially not enough contrast to make it easy to read. Notice the warning symbol that indicates that the contrast fails to meet the acceptable contrast ratio. 228 229 Viewing this information for some foreground text that has a complex background image (e.g. a gradient) gives you a range of color contrast values. For example: 230 231 .. image:: screen_shot_2019-01-29_at_10.21.07.png 232 :alt: A screenshot of color contrast highlighter with checked sign where for text over gradient background with contrast satisfying the AAA WCAG guidelines. 233 :class: center 234 235 236 In this example, the contrast ranges from 4.72 to 5.98. The numbers are followed by AAA and a checkmark in green, indicating that the large text has a contrast ratio of 4.5:1 or more, meeting the criteria for enhanced contrast, or Level AAA. 237 238 See `Color contrast <https://developer.mozilla.org/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable/Color_contrast>`_ for more information on color contrast. 239 240 241 Accessibility picker 242 -------------------- 243 244 Like the element picker button on the :ref:`Page Inspector <page-inspector-how-to-select-an-element-with-the-node-picker>`, the *Accessibility* tab's element picker button allows you to hover and select UI items on the current page to highlight objects in the accessibility tree. 245 246 The accessibility tab element picker looks slightly different from the Page Inspector HTML pane picker, as shown below: 247 248 .. image:: dom-inspector-picker.png 249 :alt: highlighted DOM inspector picker button, with a tooltip saying Pick an element from the page 250 :class: border 251 252 253 .. image:: accessibility-inspector-picker.png 254 :alt: highlighted accessibility inspector button, with a tooltip saying Pick accessible object from the page 255 :class: border 256 257 258 When you "perform a pick", you see the accessibility object highlighted in the accessibility tree, and the picker is then deactivated. Note, however, that if you hold the :kbd:`Shift` key down when "performing a pick", you can "preview" the accessibility object in the tree (and its properties in the right-hand pane), but then continue picking as many times as you like(the picker does not get cancelled) until you release the :kbd:`Shift` key. 259 260 When the picker is activated, you can also deactivate it by pressing the picker button a second time, or pressing the :kbd:`Esc` key. 261 262 263 Typical use cases 264 ***************** 265 266 The Accessibility Inspector is very useful for spotting accessibility problems at a glance. For a start, you can investigate items that don't have a proper text equivalent — images without ``alt`` text and form elements without proper labels have a ``name`` property of ``null``, for example. 267 268 .. image:: use-case-no-label.png 269 :alt: A form input highlighted in the UI, with information about it shown in the accessibility inspector to reveal that it has no label — it has a name property of null 270 :class: border 271 272 273 It is also very handy for verifying semantics — you can use the *Inspect Accessibility Properties* context menu option to quickly see whether an item has the correct role set on it (e.g., whether a button is really a button, or a link is really a link). 274 275 .. image:: use-case-fake-button.png 276 :alt: A UI element that looks like a button, with information about it shown in the accessibility inspector to reveal that it isn't a button, it is a section element. It has a name property of null 277 :class: border 278 279 280 See also 281 ******** 282 283 - `Accessibility tutorials <https://developer.mozilla.org/en-US/docs/Learn/Accessibility>`_ 284 - `Web accessibility overview <https://developer.mozilla.org/en-US/docs/Web/Accessibility>`_ 285 - `Practical debugging information <https://developer.mozilla.org/en-US/docs/Learn/Tools_and_testing/Cross_browser_testing/Accessibility>`_ 286 - `Understanding WCAG <https://developer.mozilla.org/en-US/docs/Web/Accessibility/Understanding_WCAG>`_ 287 - `WAI-ARIA basics <https://developer.mozilla.org/en-US/docs/Learn/Accessibility/WAI-ARIA_basics>`_ 288 - `Accessibility APIs: A Key To Web Accessibility <https://www.smashingmagazine.com/2015/03/web-accessibility-with-accessibility-api/>`_ by Léonie Watson