Skip to content

HTML Style Guide#

Background#

This document is intended to outline the style rules for HTML here at Miva. This style guide applies to anywhere that HTML is written with the purpose and intent of being rendered in a browser to an end user. This includes: static HTML files, HTML in Miva templates, HTML written in JavaScript templates, etc. This guide applies to the source files. You are free to use tools to obfuscate, minify, and chunk as necessary as long as the input code meets our coding standards.

Key Points#

  • Code according to our HTML Lint linting standards.
  • Code according to the General and Formatting Rules below.
  • Write valid HTML and validate it with validator.w3.org.
  • Use semantic HTML elements.
  • Use accessible elements, attributes, and best-practices.
  • Apply on-page SEO best-practices.
  • Don’t use spaces, tabs, &nbsp;, <br> for spacing & padding, use CSS instead.
  • Avoid excessive DOM elements.

General#

Document Type#

All HTML files should use the HTML 5 doctype.

Incorrect

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
    <head>
    ...

Correct

<!DOCTYPE html>
<html>
    <head>
    ...

Semantics#

Use HTML elements for their intended purpose. Avoid using a tag for something that it was not meant to be used for.

Incorrect

<span class="c-button-primary" onclick="handleEvent();" role="button" tabindex="0" aria-pressed="false">>Click Me</span>

Correct

<button class="c-button-primary" id="js-event-button">Click Me</button>

URI Protocols#

Always use HTTPS when calling for embedded resources whenever possible. This includes images, media files, style sheets, scripts, and anything else you need to pull in.

Incorrect

<script src="http://example.com/main.bundle.min.js"></script>

<link href="http://example.com/dist/css/main.min.css" rel="stylesheet">

<img src="http://example.com/image.png">

Correct

<script src="https://example.com/main.bundle.min.js"></script>

<link href="https://example.com/dist/css/main.min.css" rel="stylesheet">

<img src="https://example.com/image.png">

Capitalization#

Use only lower case characters for general code and syntax.

Incorrect

<TABLE ALIGN="LEFT">
    <TR>
        <TD>An Item</TD>
        <TD>Another Item</TD>
    </TR>
</TABLE>

Correct

<table align="left">
    <tr>
        <td>An Item</td>
        <td>Another Item</td>
    </tr>
</table>

Trailing Whitespace#

  • Remove any trailing whitespace.
  • Use VS Code’s “Trim Trailing Whitespace” command for quick formatting cleanup before committing changes.

Incorrect

<ul>••
    <li>An Item</li>•
    <li>Another Item</li>____
•••
</ul>•

Correct

<ul>
    <li>An Item</li>
    <li>Another Item</li>
</ul>

Comments#

Implement comments where necessary. Use comments to explain why code was written rather then what it does.

Action Items#

Mark action items with a TODO:

Incorrect

<!-- We should add Bilbies and Macropods to our list of Marsupials -->
<ul>
    <li>Wombat</li>
    <li>Opossum</li>
</ul>

Correct

<!-- TODO: Add Bilbies and Macropods to our list of Marsupials -->
<ul>
    <li>Wombat</li>
    <li>Opossum</li>
</ul>
OR: just remove the comment and add a Jira Task to backlog… 
<ul>
    <li>Wombat</li>
    <li>Opossum</li>
</ul>

Formatting Rules#

Indentation#

  • Always indent by 1 tab at a time.
  • Please do not use spaces or mix tabs and spaces for indentation.
  • Use VS Code’s “Convert Indentation to Tabs” command for quick formatting cleanup before committing changes.

Incorrect

<ul>
••••<li>An Item</li>
________<li>Another Item</li>
</ul>

Correct

<ul>
____<li>An Item</li>
____<li>Another Item</li>
</ul>

General Formatting#

Every block level, list, or table element should be on its own line.

Child elements should be indented with respect to their parent element.

Incorrect

<ul><li>Item One</li><li>Item Two</li></ul>

<table><tr><td>Item One</td><td>Item Two</td></tr></table>

<div><span>Miva</span> is a great company!</div>

Correct

<ul>
    <li>Item One</li>
    <li>Item Two</li>
</ul>

<table>
    <tr>
        <td>Item One</td>
        <td>Item Two</td>
    </tr>
</table>

<div>
    <span>Miva</span> is a great company!
</div>

HTML Line Wrapping#

Longer HTML lines can be broken into multiple lines to improve readability where necessary.

Lines should be broken at their attributes and indented with a single tab character.

Incorrect

<a class="js-navigation-menu__link x-navigation-menu__title"
href="https://jburton.mivamerchantdev.com/mm5/merchant.mvc?Screen=CTGY&Category_Code=Gear"
aria-label="main-menu, Shop, Promotions"
    tabindex="-1"
role="menuitem">
Promotions
</a>

Correct

<a class="js-navigation-menu__link x-navigation-menu__title"
    href="https://jburton.mivamerchantdev.com/mm5/merchant.mvc?Screen=CTGY&Category_Code=Gear"
    aria-label="main-menu, Shop, Promotions"
    tabindex="-1"
    role="menuitem"
>
    Promotions
</a>

Quotation Marks#

Attribute values should always be surrounded with the double quote character as opposed to single-quotes or no-quotes.

Incorrect

<div class='o-layout'>
<input type=number min=1 max=2>

Correct

<div class="o-layout">
<input type="number" min="1" max="2">

Avoid Redundant Accessibility Markup#

Use semantic HTML instead of redundantly marking up elements with aria- attributes or [title] and [alt] attributes that match the surrounding content.

Avoid Redundant Attributes#

For example, avoid adding inputmode="email" on an input[type="email"], just use input[type="email"]

Incorrect

<input type="email" inputmode="email" autocomplete="email">

Correct

<input type="email">