This perennial question came up again today.
Should modal dialogs begin with an h1
or h2
heading?
My opinion is that a case can be argued for both patterns. It's a judgement call depending on context, but it doesn't really matter. Consistency is more important and it's difficult to change your mind later.
The ARIA Authoring Practices Task Force discussed it back in 2018 and concluded as much. This is reflected in the example markup shown in the ARIA Authoring Practices Guide.
I have worked on applications and design systems that take both approaches. I personally lean towards using an h2
, because a dialog is spawned as the child of another page rather than being a sibling of it. It's essentially a sub-section, albeit presented with a degree of separation. It's not a separate document with its own outline.
Having a quick look around at design systems and component libraries today, MUI, Microsoft Fluent 2, IBM Carbon, Adobe Spectrum, Shoelace, and the US federal government are all using h2
elements in their dialog components. On the other hand, Atlassian, Salesforce Lightning, and GitHub's Primer use h1
.
Blueprint uses h6
, which is quite the flex.
In the case of MUI, I noticed there is an open issue requesting that the h2
be changed to h1
, with some discussion of the rationale.