HTML style guide

Semantic elements

Semantic elements are HTML tags that give semantic (rather than presentational) meaning to the data they contain. For example:

• <article>
• <nav>
• <strong>

Prefer using semantic tags, but only if the intention is truly accurate with the semantic meaning of the tag itself. View the MDN documentation for a description on what each tag semantically means.

<!-- bad - could use semantic tags instead of div's. -->
<div class="...">
  <p>
    <!-- bad - this isn't what "strong" is meant for. -->
    Simply visit your <strong>Settings</strong> to say hello to the world.
  </p>
  <div class="...">...</div>
</div>

<!-- good - prefer semantic classes used accurately -->
<section class="...">
  <p>
    Simply visit your <span class="gl-font-weight-bold">Settings</span> to say hello to the world.
  </p>
  <footer class="...">...</footer>
</section>

Buttons

Button type

Button tags requires a type attribute according to the W3C HTML specification.

// bad
<button></button>

// good
<button type="button"></button>

Button role

If an HTML element has an onClick handler but is not a button, it should have role="button". This is more accessible.

// bad
<div onClick="doSomething"></div>

// good
<div role="button" onClick="doSomething"></div>

Links

Blank target

Use rel="noopener noreferrer" whenever your links open in a new window, i.e. target="_blank". This prevents a security vulnerability documented by JitBit.

// bad
<a href="url" target="_blank"></a>

// good
<a href="url" target="_blank" rel="noopener noreferrer"></a>

Fake links

Do not use fake links. Use a button tag if a link only invokes JavaScript click event handlers, which is more semantic.

// bad
<a class="js-do-something" href="#"></a>

// good
<button class="js-do-something" type="button"></button>