Make dialog title a semantic heading element

[JamesFromIT]

Proposed change

Adds a semantic header tag to the dialog title in dialog-box.ts. This is helpful for accessibility as some accessibility software uses semantic HTML to better understand the page.

An example of an accessible dialog can be found in the Deque Code Library of Accessible Examples. This shows a h1 tag being used for the dialog title.

This is one change in response to #3387.

Type of change

• Dependency upgrade
• Bugfix (non-breaking change which fixes an issue)
• New feature (thank you!)
• Breaking change (fix/feature causing existing functionality to break)
• Code quality improvements to existing code or addition of tests

Additional information

• This PR fixes or closes issue: fixes #
• This PR is related to issue or discussion: Heading tags for accessibility #3387
• Link to documentation pull request:
• Link to developer documentation pull request:
• Link to backend pull request:

Checklist

• I understand the code I am submitting and can explain how it works.
• The code change is tested and works locally.
• There is no commented out code in this PR.
• I have followed the development checklist
• I have followed the perfect PR recommendations
• Any generated code has been carefully reviewed for correctness and compliance with project standards.

If user exposed functionality or configuration variables are added/changed:

• Documentation added/updated for www.home-assistant.io

To help with the load of incoming pull requests:

• I have reviewed two other open pull requests in this repository.

[home-assistant]

Hi @JamesFromIT

It seems you haven't yet signed a CLA. Please do so here.

Once you do that we will be able to review and accept this pull request.

Thanks!

[home-assistant]

Please take a look at the requested changes, and use the Ready for review button when you are done, thanks 👍

Learn more about our pull request process.

Stale

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Updates the generic dialog title markup to use a semantic heading element to improve accessibility and assistive-technology navigation (per issue #3387).

Changes:

• Replace the dialog title wrapper from a span to an h1.
• Add CSS to neutralize default heading styling for the .title class.

[Copilot]

Using an h1 inside dialogs can create multiple level-1 headings across the app, which can make heading navigation noisy for screen reader users. Consider using a lower-level heading (e.g., h2) for dialog titles, or switch to role=\"heading\" with an appropriate aria-level if you need to avoid hardcoding a global heading level.

[JamesFromIT]

Interesting.

I've tested this implementation with the NVDA and JAWS screen readers and when I go to navigate by headers it seems to show only the dialog heading when one is open. Also, as expected, focus is trapped within the dialog until it is closed, so there's no way to manually navigate to the headings outside of the dialog using the arrow keys that I'm aware of. So, in this case, I don't see how this could generate noise.

I also think it's fair to say that the convention is probably well understood if it used in Deque University's Code Library of Accessibility Examples, W3C's ARIA Authoring Practices, and Harvard's Digital Accessibility Services. And, it is also what @steverep recommended in #3387 and he is a screen reader user himself.

That being said, if anyone has any strong opinions either way, I can change it.

As for using role and aria- attributes, use of existing native semantic elements (like h1, h2, etc.) where available is generally considered preferable. Using aria- attributes is useful in some cases, but because they can override accessibility behaviours, they can also cause confusion if implemented incorrectly. You also introduce an inconsistency risk as you then have to maintain this additional aria- code to make sure it still makes sense when the page structure changes.