Why <details> is Not an Accordion

tl;dr - <summary> is a button and buttons eat semantics

December 13, 2019

I learned something this week and I thought I would share it. Earlier this year I read Adrian Roselli’s post “Details/Summary are not [insert control here]”. In this post Adrian says <details> is not a tab set, it’s not a subnavigation menu, not a dialog, not an accordion, not a … wait, what? Not an accordion‽⁈

Giving some context; I believe at the time Adrian was responding to a popular tweet by Caleb Porzio (140k views) showing <details> as a <dialog> replacement. Incidentally, this pattern is being used by Github in the form of a <details-dialog> custom element. Mu-an Chiou has a great slide deck from a talk at BrooklynJS explaining some of their thinking about it. But let’s get back to accordions…

So here I am, some months later, tasked with building an accordion. I was curious about the assertion that an <details> “is not an accordion”. Adrian cites the missing heading , button , and region roles missing. Well if that’s the issue, that’s all stuff that we should be able to add back in with ARIA and we could even wrap it all up in a nice Web Component… I thought.

See the Pen <details-accordion>: An Accordion made of Details Elements? by Dave Rupert (@davatron5000) on CodePen.

Cunningham’s Law states “The best way to get the right answer on the Internet is not to ask a question, it’s to post the wrong answer”, so I shared this out on Twitter to get feedback. Adrian and Scott O’Hara offered valuable feedback (as usual) and I’m sad to report that <details> is STILL not an accordion.

I got very close to the dream, but there was one nut I could not quite crack…

Summary is a button and buttons eat semantics

The core of the issue, which Scott pointed out, because <summary> has role="button", it eats the semantic content of elements inside it.

Here’s a contrived example with headings:

h1 + button // ✅ H1 will show up when navigating by headings
button + h1 // ❌ H1 will not show up when navigating by headings

As you can see, a heading can have a button but a button cannot have a heading. This makes my head spin a bit. It may not seem like a big deal because we can make it work visually with CSS, but if you use a screen reader or a braille reader and browse-by-headings, that giant accordion got a major downgrade.

Clobbering semantics happens elsewhere too. Last week I was looking at how role="presentation" will eat the semantics of its required children in certain situations (e.g. ul and table). Both of these are a great example of why ARIA is a heavy handed move and should be a last resort when authoring.

So where do we go from here?

I will be honest in saying that this is a bit of a major bummer for me. Let’s quickly process the Five Stages of Accessibility Grief together so we can move on:

  1. Denial - But like <details> just feels right, maaan
  2. Anger - This sucks. HTML sucks. ARIA sucks.
  3. Bargaining - Do blind people really need headings anyway?
  4. Depression - HTML is doomed and so is my career
  5. Acceptance - I accept that this is a sub-optimal situation beyond my control

In all seriousness, I think the biggest frustration here is expectations are broken. <details>/<summary> is the most accordion-like thing I’ve ever seen and yet it can’t be used as an accordion. My expectation as an Author does not match the Platform’s capabilities. Is this something that can be patched? Is this HTML’s fault? Is this ARIA’s fault? I don’t know. I only know that this creates more work for me.

I can still add a slew of ARIA roles, states, and properties to a series of <h#> + <div> combinations but it feels like we lost an opportunity here. We’re asking a lot of authors to home-roll and manage ARIA which we’ve already established is a difficult task to get right. Same goes with <dialog> being insufficient. Is everyone supposed to write their own keyboard trap? Christ almighty, may God help us. I made websites for like 20 years before I learned about that web development gem.

At the risk of being a broken record; HTML really needs <accordion> , <tabs>, <dialog>, <dropdown>, and <tooltip> elements. Not more “low-level primitives” but good ol’ fashioned, difficult-to-get-consensus-on elements. A new set of accessible controls for a modern era… except that these things have been in-use on nearly every major website and application for the last two decades and exist in every major design system.

In a world where 97.8% of sites are inaccessible and sites that do use ARIA are 26.7% more inaccessible, we are failing the most vulnerable of users on the Web. I wish browsers would prioritize accessibility improvements over things like main thread scheduling optimization to unblock tracking pixels and the Sisyphean task of competing with native.

If we really want to win, let’s make it easy for everyone to access the Web.