Atoms

General guidance

Headings provide your document with an hierarchical outline.

• Avoid skipping heading levels: always start from <h1>, next use <h2> and so on
• You should only use one <h1> per page. Using more than one will not result in an error, but using only one is seen as a best practice. It makes logical sense — <h1> is the most important heading, and tells you what the purpose of the overall page is. You wouldn’t have a book with more than one title, or a movie with more than one name! Having a single top-level title is also arguably better for screenreader users, and SEO

@see MDN article on h1-h6

A common navigation technique for users of screen reading software is jumping from heading to heading to quickly determine the content of the page. Because of this, it is important to not skip one or more heading levels. Doing so may create confusion, as the person navigating this way may be left wondering where the missing heading is.

General guidance

Icons visually represent a small concept. They’re used to provide both visual guidance and visual interest to an element.

Since icons are primarily visual, it’s important that icons not be the only way of conveying meaning. Textual labels are important to avoid inaccessible and unusable “mystery meat navigation”.

General guidance

Images represent ideas visually. They should be used to make an impact where communicating an idea is more effective with visual aids.

Technical

Images should be inserted using the liquid template include whenever possible, since the liquid template uses conditional checks to insert next-generation optimized images if available.

It is required for all images to have an alt attribute. If an image has no communicative value (ie. it is purely decorative), its alt attribute should be an empty string. Otherwise, the alt attribute’s text should be a description of the image’s role in the corpus of the page.

General guidance

Spacers are used to put some breathing room vertically between elements.

Technical

Spacers are only available in 1, 2, 4, 8, 16, and 32 sizes. Other size values will result in an empty spacer.

Spacers are empty <div> elements with no semantic value. Spacers should not be used for any semantic purpose.