How can I give a website dialog the right HTML semantics?

Semantics tell browsers and assistive technologies what an interface element is and how it is intended to behave. Start by deciding whether your panel is modal: should people be able to interact with the page behind it while it is open?

For an HTML <dialog>, showModal() opens it as modal and makes the rest of the page inert; show() opens it nonmodally, so users can still interact with the page. The open attribute also makes it nonmodal, though MDN recommends using show() or showModal() to display it. A native dialog provides behavior that a custom widget made from other elements would need to reproduce. [S1]

A <div> is not automatically a dialog just because it looks like one. If you build a custom widget, you are responsible for implementing its semantics and interactions. The modal pattern’s expected behavior includes preventing interaction with the underlying page and keeping keyboard focus in the dialog until it closes. [S2]

Give it a short name that identifies its purpose. A visible heading is often the clearest choice: give the heading an id, then reference that ID from the dialog’s aria-labelledby. Alternatively, use aria-label to provide a name directly. The W3C pattern describes these as naming options for a modal dialog. [S2]

For example, a confirmation panel might be named “Discard changes?” and include a short explanation and clear choices. If the dialog contains complex content that people need to navigate piece by piece, avoid using aria-describedby to make all of that content sound like one long description; the pattern says that attribute is optional and best suited to simple descriptive text. [S2]

<dialog id="discard-dialog" aria-labelledby="discard-title">
  <h2 id="discard-title">Discard changes?</h2>
  <p>Your unsaved edits will be lost.</p>
  <button type="button">Keep editing</button>
  <button type="button">Discard changes</button>
</dialog>

Treat modality as an interaction requirement, not just a visual style. When a modal opens, move focus to an appropriate element inside it. With native showModal(), a nested focusable element receives focus by default; an autofocus attribute can specify a more suitable initial target. Consider what the person needs to do first: for a long explanation, that may differ from a form’s first field. [S1]

Provide a visible button that closes the dialog. While a modal is open, users should not be able to interact with the content behind it, and keyboard focus should remain within the dialog. When it closes, focus normally returns to the element that opened it; if the workflow makes another destination more logical, that can be the better return point. [S2]

Do not add aria-modal="true" as a substitute for actually blocking outside interaction. The W3C pattern says to use it only when the implementation really prevents outside interaction and visually obscures the outside content. A false claim of modality can mislead assistive-technology users. [S2]

Use show() for a nonmodal native dialog. In that case, the page remains interactive, so do not describe or mark the panel as modal. Decide where focus should go when it opens and how people can dismiss it without disrupting the page; check those interactions with a keyboard as well as a pointer. Native dialog guidance covers both modal and nonmodal display, but the cited material does not guarantee identical behavior in every browser or cover every custom widget. [S1]

For a final review, open the dialog using the real control on the page, check that its name is announced meaningfully, and try its close control. For modal behavior, also try to reach the background and check where focus goes after closing. These checks help you find implementation mismatches; they do not by themselves establish that every browser or assistive technology behaves the same.