HTML spec: section 4.11.1, for <details> (HTMLDetailsElement), should probably briefly but explicitly state that the element uses shadow DOM, and should probably link to section 15.5.5 to direct readers to further information

[DavidJCobb]

What is the issue with the HTML Standard?

BLUF: I think it'd be a good idea to amend the HTML standard section 4.11.1 so that it links to section 15.5.5 while summarizing the most important facts from 15.5.5 in brief.

The HTML spec defines the details element as using the shadow DOM, but only in 15.5.5: The details and summary elements. There is no explicit mention of the shadow DOM in 4.11.1: The details element, nor is there a link from 4.11.1 to 15.5.5. Someone who goes directly to the spec to look for information on the details element is unlikely to find the mentions of the shadow DOM, because:

• The logical place to look for information on the details element, in a spec that has a dedicated section for every element, is the dedicated section for the details element.
• It is reasonable to assume that the dedicated section for the details element will contain or otherwise direct a reader to all pertinent information about the details element. It is therefore also reasonable to immediately stop looking for information upon finding that section.
• The dedicated section for the details element is higher on the table of contents. Ctrl + F will find that section first, and if you want to get to 15.5.5's entry in the table of contents, you have to scroll (on my desktop) 32,711 pixels down the page, almost to the bottom.
• Third-party reference materials such as MDN make the same mistake that an individual would make. Most people aren't going to directly access the HTML spec, because it's such an absolutely massive document that just the table of contents is thirty-two 1080p monitors tall. Devs will more often use third-party reference materials, and follow those materials' links to the spec if there's a problem.¹

Moreover, someone who doesn't stumble upon 15.5.5 won't expect details to use the shadow DOM because there... doesn't seem to be any real reason for it to? Like, thinking about this like someone who isn't a browser engineer, "box what hides the things you put in it" shouldn't require a shadow DOM for the same reason "button that looks like an OS-native widget by default in most browsers" shouldn't require a shadow DOM. It feels like it should be sufficient for the spec to just say, "The disclosure widget hides stuff until the user clicks a thing. The button widget looks and acts like a button. Do whatever you have to do outside the realm of HTML, CSS, and the DOM to make that happen, vendors." It's baffling and unintuitive that a native element built into the browser is made of the same stuff that randoms like me scribble into Notepad++. All of this is to say that the Venn diagram of "people who haven't read or heard about section 15.5.5" and "people who would never in their lives guess that details was implemented using the shadow DOM" is a circle.

Why this matters

The use of slots and the shadow DOM for the details element causes a number of quirks for web content, including by breaking CSS's inherit keyword. It's important to know when you're dealing with a shadow DOM, and since the shadow DOM is usually opt-in, details is pretty egregious.

CSSWG #8184 is an example from a couple years ago, and the thing that led me to file this issue after I found it while searching for something else. I've put together a demonstration of the reported issue here if anyone needs a visual reference. The issue report is also instructive, in my opinion, for how it actually played out. OP saw the shadow DOM quirks on details and, failing to understand what was going on, they reported it to Mozilla as a browser bug; a Firefox dev then directed OP to 15.5.5 to justify a RESOLVED INVALID response. OP then submits an issue to CSSWG pointing out that this behavior is unintuitive even knowing the shadow DOM is involved; and even despite linking to their Bugzilla report as context, and suggesting changes to the spec that would entail treating details like a special case, the responses they get from folks involved in the standardization process were, to my eyes, at least, worded as though the confusion came entirely from the shadow DOM itself having the limits that it did, and not from the fact of details even using a shadow DOM to begin with -- as if it's obvious to everyone that details uses the shadow DOM and obvious why it should.

Recommended solution

The dedicated section for the details element should call out the use of the shadow DOM, and then invite readers to jump to 15.5.5 to learn more about the details shadow DOM setup in specific.

Footnotes

1. On the one hand, WHATWG isn't responsible for what MDN does or doesn't link to. On the other hand, the "H" in "HTML" literally refers to a document system wherein one can follow links between pages -- and possibly arrive right in the middle of a large collection of information, out of context, without ever having seen that collection's table of contents or other primary navigation. If any document should be designed to withstand that, it should be the HTML standard. (And to the standard's credit, it largely is. The ability to click on a term's definition and see inbound links from the rest of the spec -- the extent to which navigation is baked right into the content -- is impressive.²) ↩

2. Of course, this also works against the spec. The specs are so massive, and formatted and themed so similarly, that when clicking on links to defined terms it's very easy to fail to notice when you've traveled to a completely different spec. There, if you click on a definition to see inbound links -- perhaps a definition that you just followed an inbound link to specifically so you could view the other inbound links -- you'll only see links from within the same spec, and not cross-spec links. In this way, the inbound link feature can actually offer something like a false sense of security: you think you can navigate more reliably than is actually possible. Sometimes there really is no better substitute for just saying, "Hey, this thing does the thing. Click here to learn more," inline in the text. ↩

[annevk]

I could see generally making the rendering requirements for elements more apparent, but I'm not a big fan of one-off solutions for cases some might consider surprising.

E.g., a concrete thing I would support is adding a "Rendering" topic to the green information box similar to how we already have "DOM interface" and "Accessibility considerations" that simply links to the relevant Rendering subsection.