Bug: Different heading levels used for styling purposes instead of semantically on the home page

[milofultz]

Bug Description:

Heading levels are used in ways to affect their styling and not being used semantically. This leads to poor experiences for users of assistive technologies. See MDN's notes on navigation using headings.

---

Reproduction Steps:

1. Go to the home page and turn on your screen reader (Voiceover, in this instance).
2. Go to the list of headings (using the rotor in Voiceover)
3. Note that they are not linear (e.g. 2, 5, 2, 5; instead of 2, 3, 2, 3)

What should be expected is a linear tree of heading levels. Each child should be a direct descendant of the parent (e.g. an <h2> element can only have succeeding <h3>s as direct children).

Screenshots (If applicable):

Screenshots are from this extension.

Possible Solution (optional):

Use CSS to style elements using something like a class name or the tag name itself (for example, .subheader or applied directly to h2) and modify this based on zoom level, width of browser, etc.

This would likely mean we need to decouple our styling from the MUI Typography component. Unsure how this is done, but I see the sx prop.

Thinking it would probably make sense to either make components that are styled correctly that we can then apply a heading level to, or something of that nature, to make a more modular and more easily maintained structure (if these styles are only used in small parts of the app, I don't want to go full design system and build out unnecessary infra).

[timbot1789]

Nice catch. You're right that we can override any MUI styles with the sx property. If that's not sufficient to fix the accessibility issues, we may want to take a look at base-ui, which advertises itself as an accessible library.

It looks like, at least for the home screen, the issue is with our own styles. We're hard-coding the h2 and h5 values. We can switch those over to more semantic ones pretty easily, and move font sizes to visual CSS styles.

[xscottxbrownx]

@milofultz - I completely understand the semantic linear idea, but what I have confusion on is where do you have to start?

Do you always have to start with <h1>?

Answers to this and I can get started on this issue.

---

@timbot1789 as well,

MUI makes it much easier to do what we want to do here.

If you want the text to look stylistically like an h1, but need it to be an h2 semantically:

<Typography variant="h1" component="h2">
  h1. Heading
</Typography>

[milofultz]

@milofultz - I completely understand the semantic linear idea, but what I have confusion on is where do you have to start?

Do you always have to start with <h1>?

Answers to this and I can get started on this issue.

You usually only want a single h1 on the page. From MDN:

While using multiple <h1> elements on one page is allowed by the HTML standard (as long as they are not nested), this is not considered a best practice. A page should generally have a single <h1> element that describes the content of the page (similar to the document's <title> element).

As far as what needs to be done, it's mainly just ensuring that the headers follow that linear structure. See the nesting example on MDN as an example of how things should be stacked.

Another example, think of it as a "belongs to" relationship.

• We have an h2 of "Food"
• another heading of "Fruit" would "belong to" the h2 of "Food", and because it is a direct descendant, it would have to be an h3.
• "Apples" would also "belong to" the "Fruit" h3 and because it is a direct descendant, it would be an h4.
• "Vegetables" would be an h3 because it is the same level as/a sibling of "Fruit" and also a direct descendant of "Food".
• etc. etc.

Think of them as structural items that help organize the content and you should be gucci 👍

[xscottxbrownx]

@milofultz - I completely understand the semantic linear idea, but what I have confusion on is where do you have to start?
Do you always have to start with <h1>?
Answers to this and I can get started on this issue.

You usually only want a single h1 on the page. From MDN:

While using multiple <h1> elements on one page is allowed by the HTML standard (as long as they are not nested), this is not considered a best practice. A page should generally have a single <h1> element that describes the content of the page (similar to the document's <title> element).

As far as what needs to be done, it's mainly just ensuring that the headers follow that linear structure. See the nesting example on MDN as an example of how things should be stacked.

Another example, think of it as a "belongs to" relationship.

• We have an h2 of "Food"
• another heading of "Fruit" would "belong to" the h2 of "Food", and because it is a direct descendant, it would have to be an h3.
• "Apples" would also "belong to" the "Fruit" h3 and because it is a direct descendant, it would be an h4.
• "Vegetables" would be an h3 because it is the same level as/a sibling of "Fruit" and also a direct descendant of "Food".
• etc. etc.

Think of them as structural items that help organize the content and you should be gucci 👍

understand all this completely. What I am asking is if an h1 HAS to be on every page, or can you start from any header level (like h2 or h3 for example) and work down linearly?

[xscottxbrownx]

understand all this completely. What I am asking is if an h1 HAS to be on every page, or can you start from any header level (like h2 or h3 for example) and work down linearly?

Found it in usage notes, yes start from h1

[milofultz]

Ah @xscottxbrownx , not trying to mansplain at you, my apologies. Let me know if you have any more questions

[xscottxbrownx]

@milofultz have one more question for you...

Do you have any suggestions for pages that don't logically have an h1? Like for instance our Contacts page, or this Home page? The docs say to always start from an h1.

[milofultz]

@xscottxbrownx There should always be an h1 for assistive technologies to have the proper hierarchy and know the content, but this h1 can be made invisible so it's only for assistive technologies. It should identify and describe the main content of the page. For "Home" and possibly for "Contacts", I'd reckon it's probably the same as the title of the page? For the case of "Contacts", an h1 of "Contacts" would probably suffice, or more if context is needed.

See this page for an example:

Should an <h1> tag be used in this manner, it should be written in HTML before the main content of the page. Screen reader users can utilize the level one heading as a means to skip to the page header (similar to how a skip to content link navigates to the main content of the page). The <h1> tag should not be hidden from the accessibility tree, as it provides guidance and assistance to those who use screen readers and other assistive technology to understand the contents of the page.

So no need to aria-hidden or role="presentation" or anything. But you can make it visually hidden through various means of CSS, like the following I got from WebAIM's recommendation:

.sr-only {
  position:absolute;
  left:-10000px; 
  top:auto;
  width:1px;
  height:1px;
  overflow:hidden;
}

The .sr-only CSS class ("sr-only" meaning "screen reader only", though the class name does not really matter) should then be referenced from within the tag of the element being hidden ... Sighted users will not see the hidden content at all—it will be hidden well to the left of the visible browser window. Because it is still part of the page content, screen readers will read it.

[xscottxbrownx]

@milofultz could you Friend request on Discord, to make this convo a little easier? I've got just a couple ideas to run by you - thinking about this for all the pages.

[milofultz]

Hey @xscottxbrownx , I thought I friended you on Discord, but now I'm not so sure 🙃 . What is your username? You can shoot me a message too at @milofultz

[xscottxbrownx]

Hey @xscottxbrownx , I thought I friended you on Discord, but now I'm not so sure 🙃 . What is your username? You can shoot me a message too at @milofultz

Found you and sent message - username: veganedge

[milofultz]

Going through this again and noticing that some headings were downgraded to just strong tags, but they are definitely headings in that they "reflect the organization of the content" (Secure Storage, etc.).