A11y Treats - Heading Design

CSD. Welcome to Syntax. On this Monday, hasty treat. We're gonna be talking about headings in HTML. That's right.

H one through h six. They might be the 1st element you learned, but they are more interesting than many people give them credit. And, perhaps they're one of those things that a lot of people get wrong. So we're gonna be talking all about common issues that you might face. We're gonna be talking about do's and don'ts.

We're gonna be talking about why you need good heading structure, what the benefit is, and then perhaps it. Some tools to help you along there and some further reading. My name is Scott Tolinski. I'm a developer from Denver.

With me as always is Wes Bos. What's up, Wes? Not too much. Just got done recording a really good one with,

Chris Lattner, so I'm buzzing on that one. That was awesome. Yeah. I'm I'm straight up. It's Bee Movie over here. I'm buzzing buzzing like crazy.

And I'm I'm feeling it. That was a a great episode. You know, if you wanna be buzzing like the Bee Movie, You might want, error handling and exception tracking in your application. So you'll want to check out century.i0forward/syntax.

And, you can sign up for Sentry, and you can get all that good stuff in your application because this podcast is presented by Sentry. Alright. Let's get into it. So We're gonna be talking all about heading design in websites and how you do it. But first and most important, and we'll get into this in greater detail After we learn some of the facts is why. Why do we even care about this stuff? And the big reason is for for 2 things.

1, accessibility. Headings are extremely important for Screen readers, specifically, in accessibility.

Keyboard navigation, not as important. But screen readers, they really rely on the information in headings to allow users to easily navigate the site in a way that makes sense. And without proper heading design and proper heading hierarchy, your users won't be able to navigate your website with a screen reader, and that is a tremendous problem for many people who rely on that technology, whether it is, people who are visually impaired, it. People who who just rely on, maybe people can't, they have dyslexia. They can't read as well, and they need that maybe that auditory version of the website. It. There's a lot of reasons here that this heading structure is important for accessibility tools and also SEO. Right? Robots, they're scanning your website.

They need to know the hierarchy just as much as any other screen reading technology does. Right? They need to know The hierarchy and the order and the structure of your website.

And headings really do act as landmarks it for that outline that is your website. Right? So let's get into thought process and design here. And I think the thing here that you're going to take away from this episode more than anything else is that heading design is all about providing a proper outline for your website, and that's really the way to think about headings.

You should be thinking about them as it builds an outline for which the content will live in your site.

So When your teacher in high school told you to start writing a paper, you oftentimes would say, alright.

I I'm being told to start with an outline. And And the first thing you do is you open up Microsoft Word, and you give that file a name.

That file name is your h one. Okay? The it. File name is your h one. What the thing is or the page title is your h one. Maybe it's the cover sheet and it has a title. That's the h one. Then you start building out an outline. So you do perhaps a heading, introduction, and then you tab over, who and what is going on. Right? And then perhaps you tab back and then you tab forward and then you tab forward and you build essentially a tabbed in outline. And that outline is essentially your h one through h six system. Each time you move over 1 space, you are adding to your heading number.

And so, therefore, You can imagine that you're never going from h 2 to h 6, but people do that in web programming all the time Because they're just not thinking about it. They're thinking about maybe perhaps visual, right, this visual hierarchy of things. And these headings don't really relate to that at all. Because in reality, when you're designing that outline of your headings, it should always match how you would if you were doing a legitimate outline.

So don't skip heading numbers. Number 1, that's a big do not do. You wouldn't do that in outline, if If your outlining goes from yeah. Like, Notions does a dark circle to a, outline circle to a block, you wouldn't go from the dark circle to the block. You can't do that.

And just like with web, you shouldn't be able to do that either. Doesn't make any sense.

So that's the big big picture here. It should always match outline of the content.

Now here are common mistakes people make. One of the big common mistakes people make is that they think about it visually. Alright. It. I have this h two. It's nice and big. It's perfect for the spot in the design. I'm just gonna do an h two here. And that's specifically not what you should be doing. It. You should be using the correct indentation level of your h's to match the structure of the page at that given point.

So picking an h tag just because it's CSS that's baked into the browser or perhaps the framework you're using matches the design is not the right idea.

And, likewise, don't just pick something because it's a bold version of the size you're currently using or any of that.

Oftentimes, 2 people will omit a heading because they feel like the design shows that there's a heading there. But if you omit the heading entirely, Screen readers and in robots in general, they don't even see that section as being anything. They don't understand. It doesn't build a landmark there for the screeners to be able to look off of. If you think about, like, a docs for even just JavaScript library, often the documentation

In my own shameless plug WestBoss.comJavaScript.

My JavaScript guide.

The table of contents is literally generated from all the headings. And if I were just willy nilly throw in headings into random pieces, then I wouldn't be able to generate that nice table of content. So I think it makes a lot of sense for like document based websites and in text based website, but it starts to get a little bit hairy when you get into like component and When it moves a little bit from an a website to an app. Right? Mhmm.

Yeah. And that's something that has to be built into your component design.

And, you know, there's some things that make that easier. For instance, in our new syntax site, we have, like, sections with headers and stuff, and some of these components have a built in header into that component. And sometimes that component is used in one place or another place.

So sometimes what I've done is I've added a prop, which is which level of heading is this going to be. And then using a dynamic thing in Svelte called Svelte element, You're able to then swap what the element is based on its actual use case. So I can say, hey. When I use this component, the heading needs to be an h three based on the hierarchy here of your your document. But at the end of the day, again, it needs to be that outline.

So what are some other things that are interesting here? Headings, they're gonna be read by a screen reader. So sometimes people write paragraph text that's too long or maybe not even descriptive enough of the content itself. And when it gets to that, it will show it essentially again like an outline, and the screen earner is gonna start reading that paragraph. Right? Like, One of the examples that the Ally project used was that, don't use an h two just for for quotes because it has a nice big font size. Right? And because it says that, it's like, oh, yeah. Right? A screen reader is now going to see that quote as a outline section is gonna read that whole quote as being some sort of header for your application. So be cognizant of the length of your your text inside of your headers. They should be short, and they should describe the context of which precedes it. Right? Or that it it precedes.

Man, language is hard sometimes. Alright. Next, here's a here's one that could be controversial.

You know, sometimes, again, we wanna separate the a structure from the visual aspect of things.

How do you feel, Wes, about classes like an h one class that gives the styles of an H one that you could use on other elements. How do you feel about that? I like that a lot because

what you visually want it to look like Is not the semantic version of that element, right? So it's hilarious because I'm sure I have a tweet that's like 10 years old, I remember being like, oh, well, like h two with the class of h one.

But that literally makes a lot of so much sense to me now Because if you want it to be as big as an H1 and you don't have to call them H1, you could call it like. Oh, yeah, you can call them anything. But it makes So much sense that you would have 1 through 6 of of heading values and you just give it a class and that will determine what it actually is printed out on on the screen. Yes. This is something that, in my opinion, is an easy yes. I will do this all day long.

Some other people will say, hey. Don't do this. You can develop another class. But, honestly, it's a class. The class has no semantic meaning here. It's just a way of assigning visual. And, also, you know, the other conversation around that would be, hey. If your visual hierarchy isn't matching the structural hierarchy, then that's not good design. Personally, hey. You know, you your your the thing that's most important is the The outline design of your headings. So as long as that's right, the visual design is that's the designer's job. Whatever it needs to look like to fulfill the styles. If it needs to look Like an h one even though it's an h three. I'm okay with that all day long. Here's another one. This is one that I get wrong, or I I would say I got this wrong up until last week it. When Killian from Polypane messaged me about this as being a bug on the syntax website, is the logo on your application an h one? I've always made it in h one. I always figured That's what we've been told. My entire life, I've been told to do that. Right. I've been told my entire life. Oh, you can you can put a a title tag in the SVG. You can, hide the text.

But according to everything that I've been reading, Some people are okay. I should say some people are more hard lined no on this than others. Some people say iffy. But from what I've been seeing, The the consensus is no. The the logo should not be the heading because if you wrap the logo in an h one As it being the website's name, right, syntax.fm, that's the website's name, then every single page on your website, the title of that The page is syntax.fm.

I mean, the application, the screen reader, and the user already knows they're on syntax.fm.

Right? So The more appropriate h one would be, like, for us, a tasty Treat web development podcast on the home page. Or if you're on the, podcast page, it would be podcasts or something like that. It it is the descriptor of the page you are on, not the website as a whole.

So this could confuse screen Screeders because it's not essentially describing the page content. It's describing

what the website title is. Right? Yeah. That that makes a lot of sense. It's funny because I think I don't know who it was, SEO people or whatever, but they always said h one, it's your website name and h two would be the like a blog post name. But It's really the op not the opposite, but your your logo can just be a a div or you probably throw it in a NAV tag if it's in your NAV.

And then your h one should be, like you said, the name of the blog post or the name of the podcast or whatever's whatever that page is for. Yeah. It. I think I've done this wrong my entire career. So if anybody,

is out there who wants to say otherwise, please let us know on Twitter. But I did quite a bit of research, and I found it to be pretty decisive that you shouldn't do that. So, I'd be interested in been inspecting Element on, like, Tons of sites, and you're right. Like, every every website I go to has no h one tag around the logo. Yeah. It's an interesting one. It's When I really got into into this, I was like, man, I've been really doing this wrong my whole life. Very, very interesting.

Another one, that it. I didn't necessarily realize is that you can give anything an ARIA level. So you can give anything the role of an h one through 6 using the ARIA hyphen level. It. In fact, an example I found on MDN docs was giving a div a role of heading and then an ARIA hyphen level of 3 Saying it is going to be then represented as essentially the h three. Now me, personally, I see this. I think You probably got other ways to solve this problem. Yeah. You can make an coat smell.

It it feels like a coat smell to me. It exists, and It does seem to work well, and it works fine, as far as screen readers go. But I I was trying to reason about in my mind what is the use a case for this that I would say, oh, this has gotta be a div with a roll of heading and an aria label of 3, and I just couldn't put it together.

For for a lot of, like, websites, People just don't have access to the templating of of everything. Like, there's like a lot of times we think we're spoiled having access to a full stack, Where like, but I guess if you can add that attribute, why don't you just go switch the tag out? You know? Yeah. Maybe it's another component somewhere down the line or or whatever. So, yeah, it's important. I I feel like with the ARIA attributes is If you're reaching for an ARIA attribute, you should first check, can I use semantic HTML? And if the answer to that is no because corporate BS or because it literally is a weird thing. Like, we also have Div role equals button. You know, if you've got to make your button a div, then you have to give it a roll, right? You've got to switch it up. But

You should probably try use the semantic element for it first. Totally. Here's another interesting one. Is it okay to ever use multiple h ones?

I've always been told no. Yeah. I've always been told no because of it's funny. Like, there's a lot of this, like, SEO stuff got beaten into us for years years, and I feel like I don't know if this is true or not, but I feel like Google has got to be able to figure out what's happening. If there's 2 H ones, like, with all the AI power we have in the world,

Is it not able to figure out what's on that page? Probably. This I'm gonna say, technically, yes. It is possible to use multiple h ones and still be accessible and still be okay for SEO.

However, it does seem to be a little Still under discussion. People say that the use case for using two h ones is rare, but especially in multi page applications, perhaps You have segments of the page that are only ever being visible at once, and they're truly 2 essential separate pages but in the DOM at the same time. It. Then you can use multiple h ones to define those sections or those separate pages as being totally separate areas, And that is the specific use case.

But other other things that I found have have said do not do that just as a a blanket rule. So it seems like there is some leeway there, but as a general rule, you should probably if you're building normal websites Yeah. You should not Use multiple h ones. Like, to give it a URL. If if you're really doing that, then those things should be 2 separate pages. Yes. I agree with you. Yeah.

Yeah. That said, another common question. Well, can I use multiple h twos? What about h threes? And as far as that goes, yes.

You can use as many of those as you want. However, if you use an h two, it should indicate the starting of a section of a page. And an h three should always be What's next? Right? You should never jump from h two to h four. So the next one becomes an h three. And then if you go back 1 layer, it's h two. I'm not sure if you know this, but the number In the h is how many you should ideally aim to use per page. I don't think that is an actual thing. No. That's not true. Straight up. Yeah.

It. I'll tell you straight up. I was about to say, I hope you're not I hope you're not doing anything that's happening. Right now. And then, like, 3 years from now, they'll be like, I think West said she'll only use 2 h twos per page.

Yeah. Don't do that. Okay.

Next 1, is it okay for headings to be visually hidden? This is an interesting question, it. Because is it is it okay to have, a heading that perhaps is not on the screen? Well, there's a couple of caveats here. Yes. It is okay For headings to be visually hidden, if it does not fit in the design but should be in the hierarchy of the structure of the page, If the outline of the page calls for a heading but the design does not, yes, you can use a heading and make it visually hidden with the caveat of you need to do it in a a special way. Right? Because if you use display none or visibility hidden or the hidden attribute in HTML, that hides it from screen readers, Making it, I mean, not useful at all. Right? Right? There's there's if you have a heading and you want it to be Visually hidden only from users who are looking at the page but not people who are listening to the structure of your page, then using these properties will make it, hidden from everything, making it completely pointless. So there's a technique of which we'll have a code snippet for, but, basically, you're positioning an absolute. It. You're sending it off the page, and you have it a container that is overflow hidden, and you're making that container impossibly small

So it doesn't take up any space. Right. That's crazy. That's the fix. You know, the fix.

There really should be something in CSS. Like The Accessibility Project recommends using a CSS clip path with a 50% insight and a 1 pixel height.

Come on, can't we get a can Can we get a visually hidden yes in CSS?

Yes. Visually hidden, but, yeah, not not hidden from screen readers. Yeah. I know that'd be that'd be cool.

But this is not the type of thing you should do often. Often, your headings should be visually labeled just like they should be labeled in the structure of your page, but there are some use cases where it is important to give your sections some heading hierarchical c s information, but the design does not work well with it, does not call for it. And in that case, you can use this visually hidden CSS trick.

However, another thing here is if that element is focusable for some reason, right, like there's a link in that h one or something, Then you need to make sure that when the user tabs to that heading, that that heading appears on screen or it is not a part of, like, the tab order because that's the thing. If you're tabbing through your website with the keyboard, then all of a sudden that focus ring disappears. People are gonna be like, where where the heck did that focus ring go? Right? This is,

a good rundown on CSS tricks from Chris Coyier. Hidden for everyone, display none, visibility hidden.

Hidden visually but presented for assistive text.

That's a screen reader only class or that's the visually hidden that we just talked about are hidden for assistive text but not visually.

Is the ARIA hidden true? That's the opposite where you don't want the screen reader to read it, but you do want the a text to show up on the screen. Yeah. So ARIA hidden

is e is an attribute that you can use that will then again hide something from screen Typically, but not visually.

I guess I've used that password for whatever reason. If I have, like, duplicate text, Like if I'm doing some cool CSS effect where I like put 2 pieces of 2, like, let's say I had the word like syntax podcast and then I wanted to, like, Put it behind and, like, tilt it a little bit, and I would have another paragraph tag. That's the syntax podcast. I wouldn't want it to visually say syntax,

syntax modules twice. So I would, ARIA, hide the second one. This is just decorative. Interesting. Yeah. Cool. That was another one I was wondering when would you do that? But I'm glad to glad to have that insight from you. Okay. So benefits. Again, for accessibility, this doesn't necessarily matter for keyboard users. Headings do not Do much for keyboard only navigation of websites. Right? But for screen readers, again, this is where headings are really important because they offer an outlined here content.

And the way screen readers work is that they allow the user to jump to the sections or the areas of the website that they they want to Easily.

And if you don't have that heading structure mapped out or that heading structure is poor, the screen reader will not be able to function, And people who are using them will not be able to navigate your website, which is a huge deal.

Okay? They they are they essentially act as shortcuts For navigating your website, you could think of it as, like, if I had an outline and I were to collapse all the information except for the headings, The screen order then allow me to navigate my website by picking the section that I would like to visit and then expanding upon that. And they also essentially there's another a thing in here that we haven't talked about with accessibility called landmarks, and we're gonna be talking an entire episode about ARIA labels. So if you're listening to this episode and you're like, what about landmarks? Landmarks will be covered in-depth when we talk about ARIA labels as well.

It. And lastly, SEO. Right? Crawlers, like we mentioned, off the top will definitely understand your application better if it's well laid out and organized.

Tools. What kind of tools do you need? There's a couple extensions I put in here for headings map, 1 for Firefox, 1 for Chrome.

Headings map essentially will outline your website in what looks Like, essentially, an outline using only the headings and allows you to see it explicitly, makes it nice and easy. My favorite tool for this stuff is honestly one of my tools for a lot of things accessibility based, but just straight up development, which is Polypane.

Polypane is a paid product, but it's really good. It's a It's a browser, and we actually interviewed Killian from Polypane on syntax before if you'd like to learn more about that. But Polypane Is great because one of the views that it gives you is both a landmarks view as well as a heading view of your application, And then it gives you nice, big, red flashing warnings. Hey. You skipped a level here. Hey. This doesn't make any sense. Hey. Yeah.

What are you doing? So So Polypane is really great for that. You can also look up screen readers tech to actually use your application and as a screen reader would if you want to get deep into how Screen readers work, which, I would recommend.

Personally, I I'm good with a lot of the tools that come in something like Polypane, but, you know, nothing nothing can beat experiencing your application like somebody who's disabled actually does. This headings map is awesome. Like, I just fired it up on my own website. And

In the footer of every page, I have, like, syntax, podcast, tweets, Instagram, and of course, and I put those as H Threes, Probably because I thought they look good, dude. And now they're being they're being categorized as part of the blog post, which they are not, You know, like they should be their own h two tags as they're their own things.

That can sometimes get a little bit tricky with the components because you don't necessarily know where a component is going to live, especially if you start nesting components inside of each other. But there is I've seen people with React maintain like a like a counter.

And every time you you nest a level deeper, You can use the counter to increment. That would actually be a really good use case for a sync local storage because it's it's contained within scope, You know, so you could increment it because and then you can programmatically render out the h tag that you need.

Interesting. It's interesting.

I I'm gonna also link to the issue that Killian raised on the GitHub on the, syntax GitHub issue it. Because he gives a bunch of tips and, like, shows a screenshot of what our h one system looked like before before. If you wanna see pros get it wrong, like, Trust me. I I thought I knew what I was doing with headers, and then he said into this. And I was so embarrassed to how bad the heading system was. And granted, I plan on doing a second pass on it, But still, I didn't realize how bad it was.

So I I really appreciate that he submitted this GitHub issue, but it allowed me to dive deeper into it. And, you you can see exactly, like, some of the issues that were there before we made these changes. I've also added a couple of links here for an Ally project, a one one y project .com. Again, it's a really great website or accessibility hyphen developer hyphen guide .com was also a really cool website They had a lot of information, and you may see some conflicting information because some of this stuff, like, should you ever use multiple h ones, isn't set in stone necessarily.

But, Again, I think we're trying to be nuanced enough here that you can get the general vibe. Shout out to Killian for

opening the issue like this as well because I think a lot of times people are afraid to even talk about accessibility because I feel like there's a lot of name and shame in it. And if you get it wrong, people love to not everybody, but I feel like there's a part of the industry that is very Person hates blind people, and we're all trying to do a really good job, and I'm glad that we're going through it and making sure it's all dialed in before we go live. But Like, this is how you tell somebody, hey. You're you're being a jerk to some of your website users. You know? Yeah. Yeah. And and I think that goes along too with, like, Nobody likes to be told that they're doing a a bad job at what they do. Right? And, again, we're all craftspeople. We really enjoy working on this stuff, and we want to make the best stuff possible.

And so, like, I don't know. I think it all goes under assuming assuming positive intent. People are trying to do good stuff, and sometimes, You know, sometimes everybody slips up. So I I was really, really, really stoked to see this issue come in and really Stoked to take it as an opportunity to immerse myself in some learning opportunities here and share it up with everybody.

So if we got anything super wrong in this episode, I really sincerely did my very best to not misrepresent anything here. Accessibility stuff is Honestly, unfortunately, harder than it it should be. Mhmm. But, again, you know, we're building data structures and all sorts of interesting things here. It. Kind of needs to be complex, but then again, we have some weird wacky stuff like this visually hidden class that we have to use. So, you know, It it's a nuanced conversation. So if there's any, additions, addendums, or anything that you think that would further enhance this episode, reach out to us. Hit us up on x, Twitter, TikTok, Flip Flop, any of that stuff we're around. Beautiful. Alright. Peace. Peace.

Head on over to syntax.fm for a a full archive of all of our shows.

And don't forget to subscribe in your podcast player or drop a review if you like this show.