{"id":"l-a11y-3-4","courseId":"web-accessibility","lang":"en","kind":"lesson","summary":"Build disclosure, tabs and menu button widgets that follow the ARIA Authoring Practices Guide, with the right roles, states and keyboard behaviour, and know when not to.","html":"

Ticketly’s line-up section has three tabs, Friday, Saturday and Sunday, built from styled buttons that swap panels on click. With a mouse it is fine. With a screen reader it is a row of three unrelated buttons, nothing says which day is showing, and the panels change silently. There is no <tabs> element in HTML, so this is ARIA’s home ground.

\n

The ARIA Authoring Practices Guide

\n

The ARIA Authoring Practices Guide (APG), published by the W3C, describes about thirty common widget patterns: accordion, combobox, dialog, disclosure, listbox, menu button, tabs, tree and more. For each one it lists the roles, states and properties, and the exact keyboard interaction users expect. Screen reader users learn these conventions across thousands of sites, so following them means your widget behaves the way they already know.

\n

Two cautions. The APG examples are demonstrations, not production components, so test them in your context. And the APG itself says to prefer native HTML where it exists. That rules out a surprising number of custom widgets.

\n

Disclosure: show and hide

\n

The simplest pattern is a button that shows and hides a region, such as Ticketly’s FAQ answers. If the design allows it, native <details> and <summary> give you the whole thing with no script:

\n
HTML
<details>\n  <summary>How do refunds work?</summary>\n  <p>You can get a full refund up to 14 days before the festival.</p>\n</details>
\n

When you need a custom version, the essential state is aria-expanded on the button:

\n
HTML
<h3>\n  <button type=\"button\" aria-expanded=\"false\" aria-controls=\"refunds\">How do refunds work?</button>\n</h3>\n<div id=\"refunds\" hidden>\n  <p>You can get a full refund up to 14 days before the festival.</p>\n</div>
\n
JavaScript
button.addEventListener('click', () => {\n  const open = button.getAttribute('aria-expanded') === 'true';\n  button.setAttribute('aria-expanded', String(!open));\n  panel.hidden = open;\n});
\n

The screen reader announces “How do refunds work?, button, collapsed”, then “expanded”. Wrapping the button in a heading keeps the FAQ questions in heading navigation.

\n

Tabs

\n

The tabs pattern has more moving parts:

\n\n

That last point uses a technique called roving tabindex. Only the selected tab has tabindex="0"; the others have tabindex="-1". The whole tablist is one Tab stop, and the arrow-key handler moves focus and the 0 between tabs.

\n
\n Three tabs: Friday with tabindex minus one, Saturday selected with tabindex zero, Sunday with tabindex minus one. Arrow keys move between tabs; the Tab key goes from the selected tab down into the Saturday panel.\n \n Friday\n tabindex=-1\n \n Saturday\n tabindex=0\n \n Sunday\n tabindex=-1\n \n \n ← → arrows\n \n Tab\n \n tabpanel \"Saturday\" (line-up, set times)\n
Roving tabindex in Ticketly’s day tabs
\n

Here is Ticketly’s version:

\n
ticketly/lineup.html
<div role=\"tablist\" aria-label=\"Festival days\">\n  <button type=\"button\" role=\"tab\" id=\"tab-fri\" aria-selected=\"true\" aria-controls=\"panel-fri\">Friday</button>\n  <button type=\"button\" role=\"tab\" id=\"tab-sat\" aria-selected=\"false\" aria-controls=\"panel-sat\" tabindex=\"-1\">Saturday</button>\n  <button type=\"button\" role=\"tab\" id=\"tab-sun\" aria-selected=\"false\" aria-controls=\"panel-sun\" tabindex=\"-1\">Sunday</button>\n</div>\n<div role=\"tabpanel\" id=\"panel-fri\" aria-labelledby=\"tab-fri\" tabindex=\"0\">…</div>\n<div role=\"tabpanel\" id=\"panel-sat\" aria-labelledby=\"tab-sat\" tabindex=\"0\" hidden>…</div>\n<div role=\"tabpanel\" id=\"panel-sun\" aria-labelledby=\"tab-sun\" tabindex=\"0\" hidden>…</div>
\n
ticketly/tabs.js
const tabs = [...document.querySelectorAll('[role=\"tab\"]')];\n\nfunction select(tab) {\n  for (const t of tabs) {\n    const on = t === tab;\n    t.setAttribute('aria-selected', String(on));\n    t.tabIndex = on ? 0 : -1;\n    document.getElementById(t.getAttribute('aria-controls')).hidden = !on;\n  }\n  tab.focus();\n}\n\ntabs.forEach((tab) => tab.addEventListener('click', () => select(tab)));\n\ndocument.querySelector('[role=\"tablist\"]').addEventListener('keydown', (event) => {\n  const i = tabs.indexOf(event.target);\n  const moves = { ArrowRight: i + 1, ArrowLeft: i - 1, Home: 0, End: tabs.length - 1 };\n  if (!(event.key in moves) || i === -1) return;\n  event.preventDefault();\n  select(tabs[(moves[event.key] + tabs.length) % tabs.length]);\n});
\n

This uses automatic activation: arrowing to a tab shows its panel immediately, which the APG recommends when panels display without delay. If a panel has to load data, use manual activation instead: arrows only move focus, and Enter or Space selects. The panels get tabindex="0" because they contain no focusable elements of their own; that gives Tab somewhere to land.

\n\n

Menu button, and when not to use it

\n

The APG menu button pattern is a button with aria-haspopup="menu" and aria-expanded that opens an element with role="menu" containing role="menuitem" children. Arrow keys move through the items, Escape closes the menu and returns focus to the button. It is right for application-style action menus, such as Ticketly’s “⋯” menu on a booking with “Download tickets”, “Transfer” and “Cancel booking”.

\n

It is wrong for website navigation. The menu role tells screen readers to expect desktop-application behaviour: they switch interaction modes and announce items as menu items, not links. For a header “Events” dropdown full of links, use a disclosure: a button with aria-expanded that reveals an ordinary list of links. Simpler code, and it behaves the way users of websites expect.

\n\n

Section 3 has made Ticketly operable. Section 4 turns to what people see and read, starting with colour and contrast.

\n","toc":[{"id":"sec-1","text":"The ARIA Authoring Practices Guide","level":2},{"id":"sec-2","text":"Disclosure: show and hide","level":2},{"id":"sec-3","text":"Tabs","level":2},{"id":"sec-4","text":"Menu button, and when not to use it","level":2}],"takeaways":["The ARIA Authoring Practices Guide (APG) documents the roles, states and keyboard behaviour users expect from each widget pattern.","A disclosure is a button with aria-expanded that shows and hides content; native details and summary give you one for free.","Tabs use tablist, tab and tabpanel roles, aria-selected, a roving tabindex so only the active tab is a Tab stop, and arrow keys to move between tabs.","Use role=“menu” only for application-style action menus; site navigation dropdowns are disclosures of ordinary links."],"further":[{"title":"W3C APG: Tabs Pattern","url":"https://www.w3.org/WAI/ARIA/apg/patterns/tabs/"},{"title":"W3C APG: Disclosure (Show/Hide) Pattern","url":"https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/"},{"title":"W3C APG: Menu Button Pattern","url":"https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/"},{"title":"MDN: The Details disclosure element","url":"https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/details"}],"quiz":[{"q":"

In a correctly built tab widget, what happens when a keyboard user presses Tab while focus is on the selected tab?

","options":[{"text":"Focus moves to the next tab in the tablist","why":"Moving between tabs is the arrow keys’ job. If Tab visited every tab, users would need many presses to get past the widget."},{"text":"Focus moves to the next tab and selects it","why":"Tab never changes the selection in the APG pattern; arrow keys do."},{"text":"Nothing, because Tab is captured by the tablist","why":"Capturing Tab would create a keyboard trap. The widget must let Tab leave normally."},{"text":"Focus leaves the tablist and moves into the active tab panel (or the next focusable element in it)","why":"Correct. With a roving tabindex only the selected tab is in the Tab sequence, so the next Tab goes to the panel content."}],"answer":3},{"q":"

What is wrong with this FAQ toggle?

\n
HTML
<button type=\"button\" aria-controls=\"refund-answer\">How do refunds work?</button>\n<div id=\"refund-answer\" hidden>…</div>
\n","options":[{"text":"It should be a link because it reveals content","why":"Revealing content in place is an action, not navigation, so a button is correct."},{"text":"It needs aria-expanded, updated on every toggle, so users know whether the answer is open","why":"Correct. aria-expanded is what makes screen readers say “collapsed” or “expanded”. aria-controls on its own is barely announced."},{"text":"It needs role=“menu” because it opens something","why":"menu is for lists of application actions. A show and hide toggle is the disclosure pattern."}],"answer":1},{"q":"

Ticketly’s header has an “Events” dropdown containing six links to event pages. Which pattern fits best?

","options":[{"text":"A disclosure button with aria-expanded that shows a list of ordinary links","why":"Correct. Navigation dropdowns are disclosures. Users Tab through the links as normal, and screen readers announce them as links."},{"text":"A menu button with role=“menu” and role=“menuitem” on each link","why":"The menu role makes screen readers switch to application-style interaction and expect arrow-key navigation, which surprises users on website navigation."},{"text":"A tablist where each event is a tab","why":"Tabs switch between panels of content on the same page. These are links to other pages."}],"answer":0},{"q":"

Why does the APG tabs pattern give inactive tabs tabindex="-1"?

","options":[{"text":"To hide inactive tabs from screen readers","why":"tabindex doesn’t affect the accessibility tree. Inactive tabs are still announced, for example as “Saturday, tab, 2 of 3”."},{"text":"So the whole tablist is a single Tab stop, while arrow-key handlers can still focus each tab from script","why":"Correct. This is the roving tabindex technique: the active tab has tabindex=“0”, the rest “-1”, and the arrow keys move focus and the 0 between them."},{"text":"Because buttons inside a tablist can’t be focused otherwise","why":"Buttons are focusable by default. The -1 is there to take them out of the Tab sequence, not to make them focusable."}],"answer":1}],"exercise":{"kind":"web","mode":"dom","starter":{"html":"

Line-up

\n
\n \n \n \n
\n
\n

Nour Quartet, 8 pm. The Saltmarsh Band, 10 pm.

\n
\n\n","css":".tabs { display: flex; gap: 4px; border-block-end: 2px solid #5b3cc4; }\n.tab { font: inherit; padding: 8px 16px; border: 1px solid #c9c4dc; border-block-end: 0; border-radius: 8px 8px 0 0; background: #f4f2fb; color: #1b1830; }\n.tab.active, .tab[aria-selected=\"true\"] { background: #5b3cc4; color: #fff; }\n.panel { padding: 12px 4px; }\n:focus-visible { outline: 3px solid #1b1830; outline-offset: 2px; }\n","js":"const tabs = [...document.querySelectorAll('.tab')];\n\ntabs.forEach((tab) => {\n tab.addEventListener('click', () => {\n for (const t of tabs) {\n const on = t === tab;\n t.classList.toggle('active', on);\n document.getElementById(t.dataset.panel).hidden = !on;\n }\n });\n});\n"},"solution":{"html":"

Line-up

\n
\n \n \n \n
\n
\n

Nour Quartet, 8 pm. The Saltmarsh Band, 10 pm.

\n
\n\n","css":".tabs { display: flex; gap: 4px; border-block-end: 2px solid #5b3cc4; }\n.tab { font: inherit; padding: 8px 16px; border: 1px solid #c9c4dc; border-block-end: 0; border-radius: 8px 8px 0 0; background: #f4f2fb; color: #1b1830; }\n.tab.active, .tab[aria-selected=\"true\"] { background: #5b3cc4; color: #fff; }\n.panel { padding: 12px 4px; }\n:focus-visible { outline: 3px solid #1b1830; outline-offset: 2px; }\n","js":"const tabs = [...document.querySelectorAll('[role=\"tab\"]')];\n\nfunction select(tab) {\n for (const t of tabs) {\n const on = t === tab;\n t.classList.toggle('active', on);\n t.setAttribute('aria-selected', String(on));\n t.tabIndex = on ? 0 : -1;\n document.getElementById(t.getAttribute('aria-controls')).hidden = !on;\n }\n tab.focus();\n}\n\ntabs.forEach((tab) => tab.addEventListener('click', () => select(tab)));\n\ndocument.querySelector('[role=\"tablist\"]').addEventListener('keydown', (event) => {\n const i = tabs.indexOf(event.target);\n const moves = { ArrowRight: i + 1, ArrowLeft: i - 1, Home: 0, End: tabs.length - 1 };\n if (i === -1 || !(event.key in moves)) return;\n event.preventDefault();\n select(tabs[(moves[event.key] + tabs.length) % tabs.length]);\n});\n"},"checks":[{"id":"roles","test":"const list = $$('[role=\"tablist\"]'); if (list.length !== 1) return false; const tabs = $$('[role=\"tab\"]'); return tabs.length === 3 && tabs.every((t) => list[0].contains(t)) && $$('[role=\"tabpanel\"]').length === 3;"},{"id":"linked","test":"const tabs = $$('[role=\"tab\"]'); const byName = (n) => tabs.find((t) => t.textContent.trim() === n); const panelOf = (t) => document.getElementById(t.getAttribute('aria-controls')); const shown = (p) => !!p && !p.hidden && getComputedStyle(p).display !== 'none'; const selectedIs = (n) => tabs.every((t) => t.getAttribute('aria-selected') === String(t === byName(n))) && tabs.every((t) => shown(panelOf(t)) === (t === byName(n))); return tabs.length === 3 && tabs.every((t) => { const p = panelOf(t); return p && p.getAttribute('role') === 'tabpanel' && (p.getAttribute('aria-labelledby') || '').split(/\\s+/).includes(t.id); });"},{"id":"initial-state","test":"const tabs = $$('[role=\"tab\"]'); const byName = (n) => tabs.find((t) => t.textContent.trim() === n); const panelOf = (t) => document.getElementById(t.getAttribute('aria-controls')); const shown = (p) => !!p && !p.hidden && getComputedStyle(p).display !== 'none'; const selectedIs = (n) => tabs.every((t) => t.getAttribute('aria-selected') === String(t === byName(n))) && tabs.every((t) => shown(panelOf(t)) === (t === byName(n))); return tabs.length === 3 && selectedIs('Friday');"},{"id":"roving","test":"const tabs = $$('[role=\"tab\"]'); const byName = (n) => tabs.find((t) => t.textContent.trim() === n); const panelOf = (t) => document.getElementById(t.getAttribute('aria-controls')); const shown = (p) => !!p && !p.hidden && getComputedStyle(p).display !== 'none'; const selectedIs = (n) => tabs.every((t) => t.getAttribute('aria-selected') === String(t === byName(n))) && tabs.every((t) => shown(panelOf(t)) === (t === byName(n))); const sel = tabs.find((t) => t.getAttribute('aria-selected') === 'true'); return tabs.length === 3 && !!sel && tabs.every((t) => t.tabIndex === (t === sel ? 0 : -1));"},{"id":"click-selects","test":"const tabs = $$('[role=\"tab\"]'); const byName = (n) => tabs.find((t) => t.textContent.trim() === n); const panelOf = (t) => document.getElementById(t.getAttribute('aria-controls')); const shown = (p) => !!p && !p.hidden && getComputedStyle(p).display !== 'none'; const selectedIs = (n) => tabs.every((t) => t.getAttribute('aria-selected') === String(t === byName(n))) && tabs.every((t) => shown(panelOf(t)) === (t === byName(n))); if (tabs.length !== 3) return false; await click(byName('Saturday')); return selectedIs('Saturday') && byName('Saturday').tabIndex === 0 && byName('Friday').tabIndex === -1;"},{"id":"arrow-keys","test":"const tabs = $$('[role=\"tab\"]'); const byName = (n) => tabs.find((t) => t.textContent.trim() === n); const panelOf = (t) => document.getElementById(t.getAttribute('aria-controls')); const shown = (p) => !!p && !p.hidden && getComputedStyle(p).display !== 'none'; const selectedIs = (n) => tabs.every((t) => t.getAttribute('aria-selected') === String(t === byName(n))) && tabs.every((t) => shown(panelOf(t)) === (t === byName(n))); if (tabs.length !== 3) return false; await press(byName('Saturday'), 'ArrowRight'); if (!selectedIs('Sunday') || document.activeElement !== byName('Sunday')) return false; await press(byName('Sunday'), 'ArrowRight'); if (!selectedIs('Friday') || document.activeElement !== byName('Friday')) return false; await press(byName('Friday'), 'ArrowLeft'); return selectedIs('Sunday') && document.activeElement === byName('Sunday');"}],"title":"Build accessible day tabs","prompt":"

Ticketly’s line-up tabs work only with a mouse and say nothing to screen readers. Turn them into the APG tabs pattern:

\n\n","hints":["Keep the tab text exactly Friday, Saturday and Sunday; the checks find tabs by their text.","Write one select(tab) function that updates aria-selected, tabIndex and the panels’ hidden attribute, then calls tab.focus().","In a keydown listener on the tablist, find the index of event.target in the tabs array, add or subtract 1, and wrap with (index + tabs.length) % tabs.length."],"explanation":"

The roles turn three loose buttons into one widget that screen readers announce as “Festival days, tab list, Friday, tab, selected, 1 of 3”. aria-controls and aria-labelledby link each tab and panel both ways. Because only the selected tab has tabindex="0", the tablist is a single Tab stop; the arrow-key handler moves the selection, the focus and the 0 together, and wraps at the ends as the APG describes. Having one select() function keep every state in sync is what makes the widget trustworthy: the visuals (.active), the semantics (aria-selected) and the focus can never disagree.

\n","checkLabels":{"roles":"One tablist holds three tabs, and there are three tabpanels","linked":"Each tab controls its panel, and each panel is labelled by its tab","initial-state":"Friday starts selected and only its panel is visible","roving":"Only the selected tab has tabindex 0; the others have -1","click-selects":"Clicking Saturday selects it, shows its panel and moves the tabindex","arrow-keys":"Arrow keys select and focus the next or previous tab, wrapping at the ends"}},"words":737,"readMinutes":4}