
Common Mistakes to Avoid in HTML - iamshadmirza
https://iamshadmirza.com/5-common-mistakes-to-avoid-in-html
======
Brendinooo
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.

~~~
moron4hire
> which are hard for me to acquire

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

~~~
Brendinooo
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.

~~~
moron4hire
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.

~~~
Brendinooo
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.

------
fedleiv
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.

~~~
3pt14159
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.

------
rev12
> 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](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...](https://webdesign.tutsplus.com/articles/the-truth-about-
multiple-h1-tags-in-the-html5-era--webdesign-16824)

~~~
gostsamo
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.

~~~
hombre_fatal
> 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/](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.

~~~
gostsamo
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.

------
blindm
> 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_

~~~
rado
They probably mean button not div.

------
reificator
> _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.

~~~
ausjke
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.

~~~
mxuribe
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.

------
innocenat
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.

------
teddyh
Mistake #0: Not using the W3C Validator:
[https://validator.w3.org/](https://validator.w3.org/)

------
joegibbs
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.

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

~~~
azemetre
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/](https://www.deque.com/)

------
gostsamo
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.

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

~~~
gostsamo
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.

------
ricardo81
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.

------
robin_reala
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](https://standardebooks.org/ebooks/john-keats/poetry)

------
KoenDG
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](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.

~~~
reificator
> _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.

~~~
asddubs
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

~~~
reificator
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.

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

------
rado
1\. Angular

------
LeonB
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.

~~~
rado
button provides free accessibility, using div is terrible.

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

~~~
extra88
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.

~~~
LeonB
Safari on iOS does not consistently apply HTML standards.

~~~
extra88
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/](https://css-
tricks.com/overriding-default-button-styles/)

~~~
LeonB
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.

~~~
extra88
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](https://codepen.io/andybelldesign/pen/Vxpjvo)

~~~
LeonB
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!

~~~
rado
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.

------
grenoire
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.

~~~
gostsamo
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.

~~~
grenoire
`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).

~~~
gostsamo
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".

~~~
asddubs
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

~~~
gostsamo
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.

