Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add additional accessibility-related authoring advice regarding <details> #9989

Merged
merged 2 commits into from
Jan 9, 2024
Merged

Add additional accessibility-related authoring advice regarding <details> #9989

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
37e3cc4
Add additional accessibility-related authoring advice regarding <deta…
dbaron Dec 12, 2023
57eace3
Address review comments and incorporate (with edits) suggestions from…
dbaron Dec 15, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 13 additions & 3 deletions source
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60161,6 +60161,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
dbaron marked this conversation as resolved.
Show resolved Hide resolved
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 @@ -60193,9 +60198,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
dbaron marked this conversation as resolved.
Show resolved Hide resolved
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
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

let's improve this note while we're at it.

Suggested change
<p class="note">Keeping related elements together can be important for accessibility.</p>
<p class="note">Visually and programmatically grouping related elements together can be important for accessible user experiences. Doing so will help ensure users are more likely to understand the relationship between such elements. When related elements are not grouped, e.g., the associated elements are located in disparate sections of a web page, it can decrease the discoverability and/or the understandability of the elements' relationship to one another.</p>

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Somehow github's "commit suggestion" UI wouldn't commit the suggestion... but I've incorporated it into the edit that I'll push shortly. I've edited the wording a bit but I don't think I've changed the substance.

One note is that I'm not a fan of "programatically" here (though I've left it for now) because that feels like it's referring to code in a programming language rather than tree structure of markup, but I'm not sure what alternative might be better. Maybe "structurally" or "logically"?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yeh. the HTML spec is far too big for the comitting of suggestions.

you could use 'structurally' rather than 'programmatically' i suppose.

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