HTML

HTML should be prepared using a template language. Pug is recommended for static files.

Some variance from the below guidance is expected if using a framework to generate HTML from reactive or shadow-DOM data (for attribute order and boolean attributes for example). However given that overall on a project the goal is consistency this should be documented and monitored along those lines.

Syntax

  • Use two spaces for indentation
  • Use single quotation marks for attributes
  • Don't repeat IDs in a document

Encoding

  • Use UTF-8 encoding and custom characters instead of HTML entities.

Attributes

  • Omit type attributes in CSS and JavaScript
  • Omit values in boolean attributes
  • Comply to the following attribute order ...
    • class
    • id, name
    • data-*
    • src, for, type, href, value
    • title, alt
    • role, aria-*

Nesting

HTML Tags should be properly nested per the document specification. Incorrectly nested tags are usually not a problem if a templating language is used to generate HTML but can emerge if fragmented HTML is delivered from multiple partials.

Ideally run pages through the W3C markup validation service as part of build. This will reveal issues immediately.

Accessibility

Projects must meet AA checkpoints from WCAG 2.1 standards, and where possible, we should aim for support of AAA checkpoints.

Full guidelines on implementation of accessible markup is outside the scope of this document. The WAVE tool from WebAIM is a good way to audit your sites. Careful consideration should be given to the introduction of some audit tooling in the build process. WAVE is good for manual tests but Axe and a11y in Storybook can also assist in testing and automation. Axe also provide a linter plug-in for VS Code.