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

Headings communicate the structure of a page, and assistive technologies can use them for in-page navigation. Choose a level that matches the surrounding outline instead of choosing a heading for its visual size.

Avoid skipping heading levels when opening new sections. For example, do not move from an <h2> directly to an <h4> unless the intervening section has ended. The W3C WAI headings tutorial notes that skipped ranks can be confusing for people navigating by heading.

@see W3C WAI tutorial on headings

General guidance

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

Icons must not be the only way to convey meaning. If the icon is part of a link, button, or other control, make sure the control has an accessible text label from visible text, aria-label, or another appropriate labeling technique.

If an icon is decorative and the same meaning is already provided in text, hide the icon from assistive technologies so it does not create duplicate or noisy output. MDN’s aria-hidden guidance notes that hidden content is removed from the accessibility tree.

@see MDN aria-hidden reference

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.

Every image needs an alt value, but the right value depends on the image’s purpose in the current page. Use concise alt text when the image communicates information or acts as a link, and use an empty string when the image is purely decorative.

When an image is wrapped in a link, the alt text becomes part of the link’s accessible name, so describe the link destination or action instead of the pixels. For complex images, provide the short identification in alt and put the longer explanation in nearby page text or a linked description.

@see W3C WAI alt decision tree @see WCAG Understanding 1.1.1: Non-text Content

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. Use them only for visual spacing, not to imply grouping, section breaks, reading order, or hierarchy.

If the page needs structure, use semantic HTML such as headings, lists, landmarks, or sectioning elements. WCAG’s non-text-content guidance treats purely decorative content differently from content that communicates information; spacers should stay decorative.

@see WCAG Understanding 1.1.1: Non-text Content