Skip to main content

HTML

Coding standards for all types of HTML documents.

Use consistent formatting​

  • Indent with 2 spaces (per level). Don’t use tabs.
  • Use all lowercase for elements and attributes.
  • Don’t add spaces around the attribute equal signs.
  • Break lines at 80 characters.
    • Meta description tag may be as long as needed.
    • Link href values may be as long as needed.

For a complete overview of style rules, please check out the Google HTML/CSS style guide.

Structure​

Add doctype​

Add an HTML 5 doctype as the first statement in your HTML file:

<!DOCTYPE html>

Include charset​

Include the charset, mostly UTF-8, in your <head> section.

<meta charset="UTF-8" />

Include viewport​

<meta name="viewport" content="width=device-width" />
Don't disable zooming

Don’t disable zooming for the user with this meta tag, this is considered an anti-pattern and bad UX.

Add language​

You should always include the language attribute on the html tag:

<html lang="en"></html>

Minimize nesting​

Keep your code as flat as possible. Prevent using too many layers of elements by using semantic elements and smart css. The example illustrates this well.

No excessive DOM​

Don’t add too many DOM elements on a page as that will hurt your page performance. So be mindful of the elements that you add to your pages and/or components, don’t just go and add div elements everywhere if it can be done in another way by using modern CSS for example.

More info over at Chrome Developers.

Use semantic elements​

Use HTML elements for the purposes that they were designed for.

Use a reset script in your project

Most of the times, your project will benefit from a CSS reset that removes default styling added to native elements by your user agent (browser). See the SCSS reset section for more information.

Always prefer semantic elements​

Always use the most appropriate semantic element for your case. Only if there is not a specific HTML element for your specific case, use the generic <div> or <span> tags.

A list of all available HTML elements can be found at MDN docs.

Use <button> or <a> elements for clickable items​

Use semantic elements for clickable items (button, anchor tags). This follows semantic rules, but moreover it enables built-in browser behavior that makes elements tabbable, clickable using the keyboard (enter/space) and tells screen readers that elements are indeed clickable items.

Only use <a> tags for links, don’t use them for actions like opening a navigation menu, then a <button> is the appropriate element to use.

Something about <ul> and <ol>.

Use typographic tags for text​

Use the <h1> through <h6> tags for titles, and <p> tags for body text. Don’t use these tags just for formatting.

Use table for tabular data​

Use a table tag for tabular data as that is the semantic way of declaring it.

Use microformats​

To make data available for other tools (like search engines for example), you can use Microformats to be able to enrich your content and make your website or webapp more accessible from other tools.

Attributes​

Always provide text alternatives​

Always provide a text alternative for images using the alt attribute. Use an empty alt tag for images that are purely for decoration.

More information about accessibility can be found in the Accessibility section.

Avoid using id attributes​

Avoid using the id attribute. Do not set styling in CSS using an #id selector. Only use this for declaring anchor sections, and make sure they are unique.

Avoid inline styling​

Inline styling (using the style attribute) is hard to override. Don't use it.

Use ARIA attributes​

Use ARIA attributes to add support for assistive technology to your HTML if you are using non-semantic elements that do not support them natively. Read more over at MDN - Accessibility.

Use data-testid attribute for testing DOM nodes​

The data-testid is an attribute used to identify a DOM node for testing purposes. It should be used as a handler to the test code. We need to make sure its value is unique.

Don't use other (tool specific) attributes

Using data-testid attributes is an industry standard. Don’t use tool specific data attributes, for example data-cy for Cypress. These tools also work with generic data attributes.

Example​

This (hypothetical extreme) code example shows how an HTML snippet can be refactored to follow the standards described above.

🚫 Not semantic, long and many nesting levels:

<div class="header" id="toolbar">
  <div class="header__section--left">
    <div class="header__logo">
      <img src="my-logo.png" />
    </div>
    <div class="header__title">Awesome page</div>
  </div>
  <div class="header__section--right">
    <div class="navigation">
      <div class="navigation-item">Nav Item 1</div>
      <div class="navigation-item--active">Nav Item 2</div>
      <!-- More nav items -->
    </div>
  </div>
</div>

<div class="content">
  <div class="content__title">Awesome article</div>
  <div class="content__body">
    <!-- Body goes here -->
  </div>
</div>

<div class="footer">
  <div class="footer__copyright">
    <p>&copy; Awesome company</p>
  </div>
</div>

✅ Semantic, short and flat:

<header>
  <img src="my-logo.png" alt="My Company Logo" />
  <h2>Awesome page</h2>
  <nav>
    <button>Nav item 1</button>
    <button>Nav item 2</button>
  </nav>
</header>

<main>
  <h1>Awesome article</h1>
  <p><!-- Body goes here --></p>
</main>

<footer>
  <p>&copy; Awesome company</p>
</footer>