Disclosure

CSS rotates the disclosure triangle to match the button's state.

.aria-disclosure-summary > button[aria-expanded="true"] {
  transform: rotate(0.25turn);
}

Reported as: Element has incorrect role

An ARIA disclosure's control must carry the button role.

When the control is a generic element with click handling and no role, or carries a different role, assistive technology reports it as plain content or as the wrong kind of control. Users can't tell that it does anything, let alone that it reveals content.

Build the control from a <button> element, which supplies the role on its own, or set role="button" on the element when it has to stay generic.

Severity: Critical

Reported as: Incorrect root element

A disclosure button's role should sit on the same element that receives focus and handles activation.

When the role sits on a descendant while a wrapper takes focus or handles the click, screen readers announce a button that isn't the element users operate, and keyboard users may reach a control that doesn't toggle the panel.

Put the role, the accessible name, aria-expanded, and the activation handling on that one element, and keep any wrapper free of roles and handlers. If the test selected a wrapper by mistake, select the button itself and run the test again.

Reported as: Accessible name

A disclosure button must have an accessible name that says which section it reveals.

When the button holds only an icon, a chevron, or an image with empty alt text, the wording that names the section usually sits in the panel below it, and users get a control they can operate and can't identify. In a stack of sections, every button then exposes the same name, so choosing between them means opening each one to find out what it was.

Name the button from the text inside it. When the design leaves no visible text to use, fall back to meaningful alt text on a child image, an aria-label, or an aria-labelledby pointing at text elsewhere on the page.

Severity: Critical

Reported as: Summary has no accessible name

A <summary> element must contain text that says which section it reveals.

When the <summary> is empty, or holds only an icon or an image with empty alt text, users get a control they can operate and can't identify. In a stack of sections, every summary then exposes the same name or none, so choosing between them means opening each one.

Put the text that names the section inside the <summary>. When the design leaves no visible text to use, give a child image meaningful alt text.

Severity: Critical

Reported as: Native disclosure is missing summary element

A disclosure built from a native <details> element must have a <summary> element with an accessible name as its first child.

When the first child of the <details> element is the content itself, the browser still renders a control and falls back to a default string, usually "Details". Users get a set of identically named controls and no way to tell which one holds what they came for. Nothing on screen signals the problem, because whatever heading the design intended is still visible, just not connected to the control.

Put a <summary> first inside the <details> element and give it the text that names the section.

Severity: Serious

Reported as: Disclosure panel has no accessible name

A disclosure panel that carries a role should take its accessible name from the control that reveals it.

When a panel has a region or group role and no name, assistive technology reports it as a region with nothing attached, or as an unnamed group it may skip. Users who move into the content, or reach it by jumping between regions, can't tell which control produced it.

Give the button an id and point the panel's aria-labelledby at it, so the name can't drift from the button's wording. Give the panel a role only when its content earns one, and leave the attribute off a panel with no role, where it names nothing.

Severity: Minor

Reported as: Conflicting aria-expanded value

A disclosure button's aria-expanded value must match whether its panel is showing: false while the content is hidden and true while it's available.

When the value is derived from something other than the content's real state, it reports the opposite of what's on screen: users skip content that's open in front of them, or go looking for content that was never revealed.

Set the attribute from the same state that decides whether the panel renders.

Severity: Critical

Reported as: Aria-expanded value did not change

A disclosure button's aria-expanded value must change whenever its panel opens or closes.

When the panel changes and the value doesn't, the attribute goes on reporting the state the panel was in before, so screen reader users are told the content is hidden while it's showing, or the reverse.

Change the attribute in the same step that shows or hides the panel, whatever caused it to open or close.

Severity: Serious

Reported as: Missing aria-expanded attribute

A disclosure button must carry aria-expanded, in the collapsed state as well as the expanded one.

When the attribute is absent, nothing in the markup says the button reveals anything, so screen reader users have no reason to expect content to appear and can't tell afterward whether activating it worked.

Set it to false from the start rather than adding it once the panel has been opened.

Severity: Serious

Reported as: Conflicting disabled values

A disclosure button must declare its disabled state one way only.

When a native <button> carries the disabled attribute alongside aria-disabled="false", or the two otherwise disagree, assistive technology can report a different state from the one the browser enforces. Users can't tell whether the button will reveal anything.

Use the disabled attribute on a native <button> and aria-disabled on a button built from a generic element, never both.

Severity: Serious

Reported as: Element does not support the disabled attribute

A disclosure button built from a generic element must convey its disabled state with aria-disabled rather than disabled.

When the disabled attribute is set on a <div> or a <span>, browsers ignore it, so the button is still reported as available and still opens its panel, however grayed out it looks. Users are told they can act on something the design means to be unavailable.

Set aria-disabled="true" instead, and keep it in step with the code that blocks activation. When a native <button> would do, switch to one and use disabled.

Severity: Serious

Reported as: Element type does not support disabled state

An element in a disclosure must carry disabled or aria-disabled only when its role supports a disabled state.

When the state sits on an element whose role has none, such as a wrapper, a list item or a heading, assistive technology may drop it or report it on something users can't operate, while the control that really is unavailable is still reported as available.

Remove the attribute from that element, and set the disabled state on the control itself, using an element or role that supports it, such as a native <button>.

Severity: Serious

Reported as: Forbidden interactive children; Nested interactive elements

A disclosure's control must not contain or be nested inside another interactive element, such as a link or a button.

A control that behaves as a button has no accessible children. An interactive element nested inside it is presentational, so screen reader users can't perceive or operate it as a control.

Move the interactive element out of the control, into the panel or next to the control.

Severity: Serious

Reported as: Aria-controls has multiple targets

A disclosure control's aria-controls attribute should name one element.

When it lists several ids, the control claims to drive several separate elements at once, and the attribute stops answering the one question it exists to answer. Assistive technology that offers to move users to the controlled content has to pick a target or offer none.

Point aria-controls at the single element holding the panel's content. When several elements appear together, wrap them in one container and name that container instead.

Severity: Minor

Reported as: Invalid aria-controls reference

A disclosure control's aria-controls attribute must name an element that exists on the page.

When the id matches nothing in the document, the reference fails quietly. Assistive technology finds no target, so it can't tell users what the control affects, and the markup still looks correct to anyone reading it.

Generate the panel's id and the aria-controls value from one source. When the panel exists only while it's open, add the attribute when the panel appears and remove it when the panel is destroyed.

Severity: Minor

Reported as: Missing aria-controls attribute

A disclosure button should identify its panel with aria-controls.

When the attribute is missing, nothing in the markup states which content the button affects, and assistive technology that uses the relationship has nothing to offer users. When the panel doesn't directly follow the button, the only cue left is a visual one: seeing which region changed.

Add aria-controls to the button and set its value to the panel's unique id. When the panel isn't adjacent, move it next to the button rather than relying on the attribute to lead users there.

Severity: Minor

Reported as: Avoid aria-owns

A disclosure button should not use aria-owns.

When the button owns its panel, the panel becomes one of the button's children, and a button's children are presentational. Assistive technology users perceive the panel's content only as part of the button's name and can't operate anything interactive inside it.

Remove aria-owns and keep the panel outside the button. Reference the panel with aria-controls, which already states the relationship.

Reported as: Keyboard accessible

A disclosure's control must be reachable with the Tab key.

When the control is built from markup that isn't focusable, such as a <div> or a <span> given click handling and a role, keyboard users can't reach it, so the content it reveals is out of their reach too.

Use a <summary> or a <button> element, both focusable on their own. When the button has to stay generic, add tabindex="0" so it joins the tab order in document order.

Severity: Critical

Reported as: Disabled element focusable

A disclosure button that presents as disabled should not be a stop in the tab order.

When Tab still lands on a disabled button, because a native <button> was styled as disabled without the disabled attribute or a generic one kept tabindex="0", keyboard users arrive at a control that reveals nothing.

Use the disabled attribute on a native <button>, which removes it from the tab order. On a generic button, set tabindex="-1" while it's disabled and restore tabindex="0" when it's available again. If you keep it focusable so users can hear why it's unavailable, make sure assistive technology reports the disabled state and activation is blocked.

Severity: Minor

Reported as: Focusable offset

The element that carries a disclosure button's role must be the element that receives focus, not one of its descendants.

When the role sits on a wrapper and focus lands on a child inside it, screen reader users tabbing through the page hear nothing about what they've landed on, and can't tell it's a control that reveals content.

Make the element with the role focusable, with a <button> element or tabindex="0", and remove focusability from the descendant that was taking focus.

Severity: Minor

Reported as: Button not activated by keyboard

A disclosure button must show and hide its panel when keyboard users activate it.

When a button built from a generic element handles only the click event, keyboard users can focus it but can't reveal the content it controls.

Use a native <button> element, which is keyboard operable on its own. Otherwise, add keyboard event listeners that either toggle the panel or create a click event that does.

Severity: Critical

Reported as: Disabled button keyboard activation

A disclosure button that reports itself as disabled should reject keyboard activation.

When a button carries aria-disabled="true" but the Enter or Space key still toggles its panel, screen reader users may be confused or lose trust in the interface.

Use a native <button>, which blocks interaction when disabled is set. Otherwise, check the disabled state in the keyboard handlers and return before toggling anything.

Severity: Serious

Reported as: Button requires space key activation

A disclosure button must activate with the Space key as well as the Enter key, as a <button> element does.

When only Enter works, users who press Space, as they would on any other button, may conclude the control is unresponsive.

Add a Space keyup handler that toggles the panel, or use a native <button> element.

Severity: Minor

Reported as: Element's state did not change

A disclosure button must update aria-expanded every time it's operated.

Nothing looks broken to sighted users, who watch the panel open and close, while screen reader users are told it's still in the state it started in. After a few presses with no change in what they hear, they decide the control is broken.

Derive the attribute from the same state that decides whether the panel shows, and handle pointer and keyboard activation through one path rather than two.

Evinced reports this issue as Critical or as Serious, depending on the context where it shows up.

Severity: Critical

Reported as: Toggle state not resetting

Activating a disclosure button twice must return aria-expanded to the value it started with.

When the code assigns a fixed value on activation instead of inverting the current one, the attribute stops tracking the panel after the first press. The panel goes on opening and closing, and screen reader users are told a closed panel is open.

Invert the state on each activation rather than assigning a fixed value.

Evinced reports this issue as Critical or as Serious, depending on the context where it shows up.

Severity: Critical

Reported as: Invalid toggle attribute

When a native disclosure carries aria-expanded on either the <details> or the <summary> element (not recommended), the value must stay consistent with the open attribute.

The browser derives the state from open while assistive technology reports the ARIA value to users, so the two disagree from the first toggle. The native construction has no script doing the toggling, so nothing updates the attribute, and screen reader users go on being told that a panel they've just opened is closed.

Remove aria-expanded and let the native state stand. When it can't be removed yet, update it from the toggle event on the <details> element so it at least tracks open.

Severity: Serious

Reported as: Disabled element active

A disclosure button that presents as disabled must not toggle its panel when it's activated.

aria-disabled="true" changes only what's reported, not what the browser allows, so the click and key handlers keep firing unless the code checks the state itself. Users are told the button isn't available and then find that it works, and they can't tell whether the change took effect or whether they've broken something they were warned off.

Check the disabled state at the top of the handler and return before changing anything, covering the pointer and the keyboard paths. On a native button, use the disabled attribute, which stops activation in the browser.

Severity: Moderate

Reported as: Disclosure is not closed with Escape key

A disclosure panel that opens over other content must close when users press Escape, and focus must return to the control that opened it.

When there's no handler for Escape, the panel covers what users were reading and the only way out is to find the control again and activate it. The partial version is as common: the panel closes, focus is left on an element that no longer exists and drops to the document body, and screen reader users hear nothing to say where they are.

Listen for Escape on the control and the panel, so the key works from either, and close the panel and call focus() on the control in the same step. Closing means clearing open on a <details> element, or hiding the panel and setting aria-expanded to false on a button.

Severity: Serious

Reported as: Deprecated keypress listener

A disclosure's key handling should use keydown or keyup, not keypress.

When a handler listens for keypress, keys the browser doesn't send through that event go unanswered, and keyboard users find the disclosure ignoring keys it's meant to respond to.

Replace each keypress listener with a keydown listener, and read the key from event.key.

Severity: Minor

Most disclosure issues relate to 1.3.1 Info and Relationships and 4.1.2 Name, Role, Value. Under 1.3.1, the button's aria-expanded state is present and reflects whether the panel is open, aria-controls references the panel, and a disabled control ignores activation.

Under 4.1.2, the control has an accessible name and holds no interactive elements, the button has the button role, a native disclosure starts with a <summary>, the disabled state is declared one way only, and activating the control updates its state.

Under 2.1.1 Keyboard, the control can be reached with the Tab key, takes focus itself, and activates with Enter and Space, and a panel that opens over other content closes with the Escape key.

Four criteria map to no WCAG success criterion and are best practices: aria-controls references a single target, a disabled button leaves the tab order and ignores the keyboard, and a panel that carries a role takes its name from its control.

Severity reflects how much an issue gets in users' way. Critical issues leave users unable to tell what the control does or whether the content is shown, or unable to use it: a control with no name, no button role, or no way to reach or activate it by keyboard, or an aria-expanded value that's wrong or doesn't change when the control is operated.

Serious issues mislead or strand users, such as a button with no aria-expanded or one whose value stays put when the panel opens or closes, a stale aria-expanded on the native elements, a <details> element with no <summary>, a disabled state the browser and assistive technology disagree on, an interactive element nested in the control, a disabled button that still responds to the keyboard, or an Escape key that doesn't close the disclosure and return focus.

The Moderate issue is a disabled control that still opens. Minor issues cost users a little extra effort but leave the content reachable, such as a missing or broken aria-controls, a disabled button that's still a tab stop, focus that lands inside the control rather than on it, a panel role with no name, or a button that ignores the Space key.

Two checks carry no severity: the general check for aria-owns and the sanity check on where the button role sits.