Common Mistakes to Avoid in HTML | Hacker News Reader

Common Mistakes to Avoid in HTML

iamshadmirza.com

67 pointsiamshadmirza78 comments

Semantic HTML is fascinating, but I think it's pretty challenging/frustrating to work with in reality.

The average web user doesn't really benefit from something being an aside rather than a div. There absolutely are benefits from having good markup, but those benefits are more for screen readers (which are hard for me to acquire and almost impossible for me to use in the same way that people who need them use them) or for SEO (which tends to be a black box) or for other theoretical cases.

If you read the spec, which I find myself doing for semantic stuff more than any other part of my frontend work, you end up with a bunch of cases that seem obvious but rarely track with real-world problems.

So much of my work in this area feels like best guesses, without ever really knowing for sure if I did it right.

Anyways, that's why articles like this are good. If you have real-world experience for what works and what doesn't, keep posting about it because I want to read it.

> which are hard for me to acquire

Uh, there's one built in to the OS. Which OS? All of them.

Sure, but

1. JAWS and NVDA have a massive chunk of market share, and I don't run Windows

2. Screen readers work differently, so I can't guarantee that something that's fine in Orca does what I want elsewhere

3. Even if I have access to everything, I can't use a screen reader at the speeds that real users prefer, and I don't use them regularly enough to know what's annoying and what's not.

I'm happy to learn, just noting the challenges.

You're way overthinking the situation. It takes 15 minutes to turn on the integrated screen reader and go through the initial training. Do that and you'll cover 90% of the issues. You can grow an intuition for what works well for screen readers very quickly. And being an infrequent user is an advantage for your testing. If you can make it easy for yourself to use, than someone with more experience will find it even easier.

Quit making excuses and do the bare minimum work already.

I can state with extreme confidence that it takes some people more than 15 minutes. Maybe I'm not as smart as you, or perhaps we learn differently.

If it's so much easier for you, you should share your knowledge! It was a blog post that got me running the basics with Orca; I found it to be much more approachable and practical than the docs.

The first person who seems to benefit from legible semantics in my projects is... me. It helps keep me oriented on where I am in the document and remember what the content is supposed to be. Sometimes this even transfers to months-from-now me or even other people.

I'll grant that markup semantics have limits, and the semantics of selectors can be a greater value here than markup.

I remember reading somewhere about the history of the HTML standard that there was a camp of people at the start who wanted the html viewer to just show a syntax error if something in the code was out of spec. Luckily what we got was a very forgiving standard that will always try to show something, no matter how it is formatted.

It's kind of a gray area, but headings are scoped to sectioning elements so there can be multiple h1 in a page. After all, article content should be considered as stand-alone sections of content. I'm not aware of how this affect accessibility.

But at the same time, I get that this guide seems aimed at people not very experienced with HTML so it may be fitting to deal with details like that later.

Exactly. Also this:

> Avoid skipping heading levels: always start from <h1>, next use <h2>, and so on.

Isn't quite correct. For longer documents it is sometimes appropriate to skip a level if it is warranted. For example, an online book may have an <h1> for a chapter heading, then some text introducing the chapter, then a minor point that doesn't deserve as much prominence as a proceeding section. So under a chapter called "Introducing Python" (an <h1>) there may be a heading immediately following the <p> text after the <h1> called "Python Runtimes" that isn't really an important part of the document, but deserves to be covered before any <h2> is called. It's ok to label it <h3> so that it shows up in the table of contents appropriately as a minor section.

It also makes more semantic sense and is better for screen readers too. If "Python Runtimes" were a <h2> a reader / lister could reasonably assume that this is a semi-major part of "Introducing Python" when it is not. It's just a quick interlude that says "There are many types of python, you should probably use CPython, since that is what this book is going to assume" or something like that.

But like you say, this is geared towards junior devs, so it's ok to generalize a bit.

> You should only use one <h1> per page.

This just isn't true in 2020. I know that MDN still recommends that, but it's seemingly invalid and outdated.

Here's what MDN says about a single H1:

> Having a single top-level title is also arguably better for screenreader users, and SEO

Here's why it isn't always bad for SEO and why it isn't always bad for screenreaders: https://www.youtube.com/watch?v=WsgrSxCmMbM

Here's a much longer article about it all: https://webdesign.tutsplus.com/articles/the-truth-about-mult...

MDN vs. a random resource on the net...

Honestly, the article that you link to has a few h1s and only one of them is for the article itself, while the rest seem like ads and not equally important content. I can continue pointing contradictions in what the author says, but the article is rather long.

> MDN vs. a random resource on the net...

No, it's an presumed expert deep diving on a subject vs MDN reference material. MDN is extremely inadequate for explaining anything that isn't mere reference, like how things are practically used in the wild or their practical impact.

A good example of this would be https://css-tricks.com/ vs MDN. MDN doesn't even try to be the resource that css-tricks is.

Anyways, why not respond to the author's actual content? What tutsplus.com's CMS is doing to their content is irrelevant.

Honestly, I have limited time and writing extended counterpoints to every argument is rather tiresome.

Regarding the article given, what made impression to me was that it states that if a document have a few important articles, all of them deserve to be h1. Well, put h1 as the topic that binds together those articles like "The blog of an expert" and each article can move to h2. Simple, semantic, and does not need to break convention.

I'm not against a few h1s in a document, but each of them must be important in a different way like name of the website, name of article, important warning in the footer/sidebar/wherever. It is like mail, if each email is marked "important", none of them is or at least you can't make your mind without reading everything and deciding for yourself which makes the "important" label meaningless.

Edit: adding a counterexample.

I've visited news websites which have sidebar with most recent or most read or the like articles. Each item in the list is marked h1 and skipping them wastes time and money.

Same with a few sidebars that are h1 titled though I don't care about their existence and their presence just shadows the h1 of the article that I'm interested in.

> If something is supposed to be clickable, it should always be a <button>

Poorly chosen language. Should be: Anchor tags should not be rendered inaccessible by setting the `href` value to an empty fragment link and then coding an event handler in Javascript for when it is clicked

They probably mean button not div.

> Read more about anchor tag on w3school guide

The most impactful thing I ever did while learning HTML/CSS/Javascript was to block w3schools in search results so they didn't even show up.

I don't know if they've improved since then, but then I do know MDN has improved since then by leaps and bounds.

Mdn was also much better than w3schools 10 years ago (when that site was much better at seo)

I think w3school improved a lot and I use it more often than MDN, as it's more "user friendly" per se, but to get full explanation etc I will visit MDN.

So w3school for quick check, MDN for deeper reading.

W3school is popular as it gets one thing done right: very user friendly esp for beginners, no one beats that yet.

Agreed. MDN is very dependable as a reliable reference.

But W3Schools is more likely to have the exact example or easy to use little tool I need in the moment.

I agree. While i love love love MDN, i can not deny that W3School caters to either beginners, or - in my case - someone looking for the quick answer; and they do a decent job in that regard. If i need to dive deep into a topic, yes, MDN is the better destination. But, sometimes it takes a little extra effort to get the quick answer from MDN. This is not the same for every single page on MDN of course. There were a few that i encountered that DID provide that quick, helpful answer...but just not as much as w3School.

Before folks start to hate, i actually (happily) donate yearly to Mozilla, partly because i 100% believe in all that they do, but also because if there are gaps in Mozilla's offerings, i want to pay to help resolve them. I pay nothing to w3school - except indirectly when they serve up ads of course...but absolutely want MDN to be around for the long term, hence my constant donations to Mozilla.

I've heard that w3schools has gotten better. MDN is certainly currently the gold standard in my opinion. But since Mozilla laid off the team maintaining it, not so sure how long that will be the case...

https://mspoweruser.com/mozilla-lays-off-dev-tool-threat-man...

Google still lists them on top for almost any query about html or css. It’s the go-to example demonstrating that there is something wrong with Google’s algorithms for ranking results.

Personally I think this is pretty outdated. I've used w3schools quite a bit over the last 12 months and it's consistently offered a concise reference alongside some examples.

Could be. I admit I haven’t taken a look in over a year. But....they were still at the top then, when they had a bad reputation among the skillful.

W3Schools has come a long way. I used to block them, now I rely on them.

These common mistakes are easy if you are doing static content.

For dynamic content like blog, it became much harder to retain synthetic correctness when most user doesn't really understand any if this.

Mistake #0: Not using the W3C Validator: https://validator.w3.org/

What if the browser didn't assume any defaults when rendering HTML? That is, without CSS an <h1> element looks identical to a <p>, a <div> doesn't do anything different to a <span>, etc. It would probably mean developers would make less mistakes using semantic HTML elements for style, but of course it would never happen because it would break every website in existence.

Is there a cheatsheet for screen readers? I didn't know they can't phrase <br>.

Not sure, there are some tools to help, but I'm not front end dev and haven't used them. However, you can install a screen reader and try the browsing shortcuts on your website.

Voice over is installed by default on Macs, NVDA is free and open source for Windows, and Orca is on Linux.

Basically when it comes to screen readers, they will parse content as it appears in the DOM as blocks of items to be read aloud.

This is why it's so important to use semantic HTML and truly understand how you are structuring your content.

A good rule of thumb is to not try to force a voice reader to have a certain cadence (like making multiple paragraphs into a single paragraph element so it gets read as one) or nesting anchor tags into paragraph elements because that's the way the copy appears.

When it comes to making accessible experiences it helps to use the tools that disabled people use to navigate, even better is if you had disabled engineers or people when doing user research.

What becomes a challenge is that all the assistive tech are similar to all the different browsers, they all have their own standards and how something gets read aloud in VoiceOver may not be the same as NVDA.

I'm actually creating a cheatsheet for a11y in general (at first I was tailoring it to react, but taking a general web approach now). I'm not done with it, but if you want to look on github I have the same username as I do here.

Also a good resource about a11y in general is Deque Systems. They're a consultancy that specializes in a11y, they've also created a popular tools in the OS community like axe. They put out many great talks not just about the engineering side of a11y but also the legal issues, how design is impacted, what sort of automation can be done to help find issues.

https://www.deque.com/

The anchor misuse and the wrong headings are the two most serious in my experience. Both of them cause me time and nerves and some poor soul lots of carma every single day.

How does a misused anchor tag cause you "time and nerves?"

You reach a door, you twist the handle, a window at the other end of the room opens.

Not sure how to explain it better.

As mentioned in the article it can make all kind of tool and normal browser interactions misbehave.

I'm frequently annoyed by it, too. But it had gotten much better.

One example is one of the first bugs I ever fixed as a working developer. A click event was broken on Firefox only because of a nested anchor and button element. As interactive elements, they shouldn't be nested according to the HTML spec, but it's common for developers to reuse button styles on a link by wrapping it with the button element. The behavior is undefined, which resulted in it working okay on Chrome but not Firefox.

What problems do skipping headings cause?

When I open a page, I press "1" to go to the main part of the content and to avoid nav bars, side bars and everything inconsequential between the top of the page and the part I'm interested in. If there is no h1, the shortcut is in vane and I start checking with 2, 3, 4 and some other possibilities to find the important stuff or try to find if the article/text/whatever starts with no heading at all and where it is doing it from. Generally, it can take from half a second to 10-20 seconds to orient myself in the structure of the content.

There is a mailing list and one of the most annoying things there is that the mail treads page has only h2. I forget it every time and I need to do 1, 2 before I reach the first mail in the tread. If they make it h1 and if every mail in the tread has an h2, it will radically improve navigation and spare me navigating requoted previous mails and mail footers.

This seems an edge case to me. For the vast majority of people, having the prime heading in <h2> and subheadings in <h4> would be totally unnoticeable.

I come from a time before <button> and use anchors out of habit. I apologize and will try to do better in the future.

thank you

From a crawler/automation perspective, bar some extra ingenuity it's good to use the likes of <article> to differentiate the 'main' content of a page versus the navigation/template.

Also nowadays worth considering structured data to help clarify the meaning of a page and the entities within it.

I like that it makes a exception for using <br/> to mark up poems, as that’s probably 95% of my usage for it; e.g. https://standardebooks.org/ebooks/john-keats/poetry

Hard disagree on the first point.

Anchors are perfectly fine for jumping to a specific point on a page. Nearly all documentation websites do it, wikipedia does it, etc...

It's literally in the texts from back in 1995: https://www.w3.org/MarkUp/1995-archive/Elements/A.html

"This allows for the form HREF="#identifier" to refer to another anchor in the same document."

As Linus Torvalds says with Linux: don't break userspace. If userspace has made something work, don't break that.

> Hard disagree on the first point.

> Anchors are perfectly fine for jumping to a specific point on a page. Nearly all documentation websites do it, wikipedia does it, etc...

I don't think that point says to not use anchors for in-page navigation.

They're not objecting to `href="#my_anchor"`, they're objecting to `href="#" onclick="doStuff()"`, which is increasingly common on the web today.

incidentally if you must do this, it's better to use href="javascript:;" rather than href="#" because it won't cause jumps in position for noscript users/when scripts break

href="javascript:;" is also bad. It doesn't work if you try to open it in a new tab. Just use a real url!

There isn't a situation where you must do this. Don't do this.

Quick heuristic: if you have a clickable link and I can't open it in a new tab, you should be using a button instead.

href="javascript:..." is just as bad. I want to hover over a link and see where it goes before I click. That makes navigation fair to the user, as opposed to "guess what's behind door number 3"

The first point is that anchor elements should not be used as buttons by adding event listeners that don’t do something akin to following a link. It isn’t really related to the usage you are describing.

I think the author was talking about a literal "href='#'" which ought to have no use aside from a poor man's "back to the top", rather than an anchor pointing to another id on the page, which can be useful.

Those are a same-page links and they are perfectly okay when pointing to an identificator on the same page. However, people put no identificator after the "#" and attach a listener instead where the behavior turns undefined and everything is possible.

Am I the only person here who just learned about <aside>?

1. Angular

I can’t always use “button” for buttons because safari on iOS enforces its own style for those. Consequently, I end up with DIVs as buttons.

button provides free accessibility, using div is terrible.

You can use <div role=button tabindex=0>.

Tabindex=0 means you can tab to it but you still can’t press Enter or the space bar to activate it like a real button. So now you have to bind a keypress listener.

Use a real <button>! You can style it.

Safari on iOS does not consistently apply HTML standards.

No browser consistently applies HTML standards and nothing but HTML standards. In this case, your complaint is probably about the browser prefixed property and value, -webkit-appearance: button.

This is a good article about Overriding Default Button Styles that also touches on why one should use a genuine <button>:

https://css-tricks.com/overriding-default-button-styles/

Thanks for that link.

I’ve read so many of these, and it all comes down to a trade off which they decide goes a particular way but I don’t feel convinced by their reasoning. It still seems like, in cases where the appearance has to be pixel perfect you can either: add a few lines of accessibility code to a .button (which is consistently described every where I look), or add many many more lines of css reset code, which is quite opaque. The article you linked says that to reset the style... you end up applying -webkit-appearance:button. Whereas I thought the style reset would include removing that? Other sources online say that’s warranted.

There is a choice to be made, and the sort of “semantic-fundamentalism” preaching I see in these articles seems to be used as a way to avoid truly weighing up the options. They treat guidelines as laws and try to justify it from there. For me: it depends.

It doesn't say to make the -webkit-appearance value 'button', that's the default. Change it to 'none'. Look at the first embedded Codepen, note it also has a -moz-appearance: none, it's not just Safari.

I don't understand why someone would want to add multiple attributes plus a JavaScript keypress listener to the wrong element when you can instead add basically reusable "reset" CSS to the right element (<button>).

You're making choices for the people using a site. If you use a <button> and don't get the CSS right, it doesn't always look the way you'd like for some people; if you don't use a <button> and an attribute or the JavaScript is wrong, it doesn't work at all for some people.

You don't have total control over the appearance of everything in the browser anyway. Some people want or need to make changes (higher contrast, more readable font, etc.) to use the web and not using appropriate elements just makes it harder for them to do that.

https://codepen.io/andybelldesign/pen/Vxpjvo

It sounds like you almost saw that there are trade offs involved in the two different approaches. But then just went for pejorative terms a bit more.

There are some scenarios where total control of the style is an important part of the thing being built.

I’m closing the browser now. I do appreciate the many constructive parts of what you’ve said. The preaching about what’s “wrong” I can skip. Like there’s some grand moral imperative not to connect a click handler to a div. Spare me!

The click handler won't work with keyboard and who knows what else, which means broken accessibility, This is actually a moral issue (you shouldn't decide which people to exclude), as well as legal in some territories. And the button can be styles pixel perfect easily, as explained above.

I think “terrible” is a bit much. With a little work a div can be both accessible and styled appropriately (without having to know platform specific ways to reset it)

The scenario above is for a game. The look of the button should be pixel perfect to suit the game.

Why does your "need" for pixel perfect styling trump your users' need for accessible interfaces?

I was building a game and wanted to control the appearance of the buttons.

And you'd rather people not be able to play the game or have a harder time rather than let the styles be a little different?

Sorry, what? Where is this hostility coming from? I’m not against accessibility.

The trade off here is between trying overcome default styles of buttons on every single platform (hard! But necessary for a game) versus treating a div as a button on every single platform (not as hard)

Please don’t simplify it to mean that by highlighting that this trade off exists I am uninterested in accessibility. You don’t know my journey.

> Please don’t simplify it to mean that by highlighting that this trade off exists I am uninterested in accessibility. You don’t know my journey.

True, I don't know your journey. But I do know that some percent of the time you use divs as buttons and your only justification for doing so is styling.

Why is pixel perfect styling of buttons "necessary for a game" anyway?

In a game, you are creating a world and bringing the player into that world. The pixels are part of how that is done. They matter a lot.

If you don’t think it’s reasonable for game designers to want complete control of the pixels inside a game they’re building then just walk away from this conversation. It’s a multi billion dollar industry that you’ve taken no notice of before now. I’m not about to convince you of its validity by typing characters into this textbox.

I disagree that 'if something is supposed to be clickable, it should always be a button.'

Anchor elements are easy shortcuts for interactive element in text. If you aren't using it already, try `tabindex=0` which enables mouse clicking, keyboard focusing, and special styling through CSS; all without messing your URL anchors.

Power users are likely to be annoyed when middle clicking your link opens a new worthless tab instead of doing what they wanted to do.

Less knowledgeable users already have a hard enough time distinguishing what is clickable and what causes navigation, swapping functionality around on them is not kind. Styling can overcome this one to be fair.

And of course as the article states, using the wrong thing makes it harder for screen readers and other such technologies to help users use your page.

If that's not enough to convince you, I offer you a challenge. Use a screen reader for a week to get a feel for how to use it. Then use nothing but a screen reader for a week, no looking at your screen at all for even a moment.

If you get through that without being frustrated by decisions exactly like these, I'll take you much more seriously.

Unfortunately, nobody using a screen reader uses tabulation to navigate a page because it is slow and painful process. So, you might hide the element from the tabbing sequence, but it will show in browsing mode. Just tried it in MDN.

`tabindex=0` actually does something else than (what I understand) you think it does.

Normally an <a> element can only be clicked+focused if it has a href or a tabindex. A tabindex of 0 will make it clickable+focusable, without having a href on it, making it behave like a button.

It doesn't make it unclickable/untabbable, simply an alternative to href without a # (as an empty href will also not be clickable).

Still on the MDN example. The browsing mode reads the nont-tabbable element but when I try to focus it with object navigation, it says unknown. However, if I move to it from the previous object it reads the text but still does not interact.

I'm not sure what would happen if the element is an anchor but I'd bet on "WTF is this supposed to do".

a tabindex=0 shouldn't be non-tabbable, i think you're thinking of tabindex=-1, 0 should make it tabbable even if it wasn't

It is possible. MDN does not have the edit to play feature of wc3 or at least it is not accessible so I can't test the different options easily.

Reply on news.ycombinator.com