Markup

The way we write HTML matters, because clean and well structured markup is more manageable.

Coding standards

  • Always use double quotes for attribute values
  • Use whitespace to define logical blocks of code
  • Tab size is equal to 2 spaces
  • Always use sentence casing for all text within HTML and use CSS to apply lowercasing, or uppercasing to meet design requirements. Please be aware of accessibility concerns
  • Re-usable code should be seperated into components where possible/appropriate

Reducing Markup

Avoid superfluous parent elements. Execessive DOM size can harm performance

Avoid:

<span class="avatar">
  <img src="..." />
</span>
1
2
3

> Prefer:

<img class="avatar" src="..." />
1

Semantics

Markup should be semantic and presentational markup should be avoided, however it is understood this is sometimes unavoidable. Using elements such a <header>, <footer>, <nav> and <article> give the browser and developers a clearer understanding of the content within. Avoid <div> and <span> where possible.

Avoid:

<div class="header">
  <div class="navigation">...</div>
</div>

<div class="article">...</div>

<div class="footer">...</div>
1
2
3
4
5
6
7

> Prefer:

<header class="header">
  <nav class="navigation">...</nav>
</header>

<article class="article">...</article>

<footer class="footer">...</footer>
1
2
3
4
5
6
7

Order of elements.

The order of elements plays a huge role in accessibility and SEO. Having elements ordered incorrectly can negatively effect page rankings and will give a bad user experience on screen readers.

Avoid:

<h3>Heading 3<h3>
<p>...</p>
<h2>Heading 2</h2>
<p>...</p>
<h1>Heading 1</h1>
<p>...</p>
1
2
3
4
5
6

> Prefer:

<h1>Heading 1</h1>
<p>...</p>
<h2>Heading 2</h2>
<p>...</p>
<h3>Heading 3<h3>
<p>...</p>
1
2
3
4
5
6

If you need elements to be styled as their counterparts consider defining classes for headings. This will ensure screen readers and SEO rankings are not negatively effected.

<h1 class="h3">Heading 1</h1>
<p>...</p>
<h2 class="h2">Heading 2</h2>
<p>...</p>
<h3 class="h1">Heading 3<h3>
<p>...</p>
1
2
3
4
5
6

Validation

Code should be tested against the W3C, to ensure the markup is well-formed, however, it is understood that 100% valid code is not always possible.

Class names

Always style using classes, not IDs.
Class names should be:

  • Lowercase and hyphenated
  • Unabbreviated: It may make sense to you, but it might not to someone else
  • Meaningful: Use structural or purposeful names over presentational

Boolean Attributes

Do not add a value to boolean attributes. (This does not include aria attributes)

The presence of a boolean attribute on an element represents the true value, and the absence of the attribute represents the false value.
If the attribute is present, its value must either be the empty string or a value that is an ASCII case-insensitive match for the attribute's canonical name, with no leading or trailing whitespace.
The values "true" and "false" are not allowed on boolean attributes. To represent a false value, the attribute has to be omitted altogether.

Bad:

<input type="text" disabled="false" />
1

> Good:

<input type="text" disabled />

<!-- or -->
<input type="text" disabled="disabled" />
1
2
3
4

States and Properties

Define Aria properties and labels where possible. This includes state changes. A full list of aria properties can be found here. Or read more detailed examples in Accessibility.