Skip to content

Commit

Permalink
Add more accessibility-related advice for <details>
Browse files Browse the repository at this point in the history
This adds two pieces of advice discussed in w3c/html-aam#509 and #9899.

Co-authored-by: Scott O'Hara <[email protected]>
  • Loading branch information
dbaron and scottaohara authored Jan 9, 2024
1 parent fb2ef16 commit 73902be
Showing 1 changed file with 13 additions and 3 deletions.
16 changes: 13 additions & 3 deletions source
Original file line number Diff line number Diff line change
Expand Up @@ -60166,6 +60166,11 @@ interface <dfn interface>HTMLDetailsElement</dfn> : <span>HTMLElement</span> {
<p>The <code>details</code> element <span>represents</span> a disclosure widget from which the
user can obtain additional information or controls.</p>

<p class="note">As with all HTML elements, it is not conforming to use the <code>details</code>
element when attempting to represent another type of control. For example, tab widgets and
menu widgets are not disclosure widgets, so abusing the <code>details</code> element to
implement these patterns is incorrect.</p>

<p class="note">The <code>details</code> element is not appropriate for footnotes. Please see <a
href="#footnotes">the section on footnotes</a> for details on how to mark up footnotes.</p>

Expand Down Expand Up @@ -60201,9 +60206,14 @@ interface <dfn interface>HTMLDetailsElement</dfn> : <span>HTMLElement</span> {

<p>Documents that use the <code data-x="attr-details-name">name</code> attribute to group multiple
related <code>details</code> elements should keep those related elements together in a containing
element (such as a <code>section</code> element).</p>

<p class="note">Keeping related elements together can be important for accessibility.</p>
element (such as a <code>section</code> element or <code>article</code> element). When it makes
sense for the group to be introduced with a heading, authors should put that heading in a <span
data-x="concept-heading">heading</span> element at the start of the containing element.</p>

<p class="note">Visually and programmatically grouping related elements together can be important
for accessible user experiences. This can help users understand the relationship between such
elements. When related elements are in disparate sections of a web page rather than being grouped,
the elements' relationships to each other can be less discoverable or understandable.</p>

<p>The <dfn element-attr for="details"><code data-x="attr-details-open">open</code></dfn> content
attribute is a <span>boolean attribute</span>. If present, it indicates that both the summary and
Expand Down

0 comments on commit 73902be

Please sign in to comment.