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.

This is a journal entry. It was worth mentioning at the time but I probably won't make changes to it, other than to fix mistakes. It was last updated .