Web patterns and content will use semantic HTML5 where possible
Context
HTML5 comes with many built-in features and document semantics that make web content more meaningful and predictable. Interactive HTML5 elements like buttons, form elements, and links also come with native keyboard behavior, which provide more robust interactive behavior.
Decision
When building components or content, we start with using valid and semantic HTML markup. In other words, we are using the correct element for the meaning we are trying to convey, or the interaction the user should complete. Examples include but aren't limited to:
- If we have section titles indicating a new topic, we use headings and choose the appropriate heading level for that title.
- We use links for sending users to new pages or sections of pages. Button elements are used for on-page interactions, or form submits through the submit input type. If there is collapsible content within a section (and isn't the start of a new section), the <details> element should be used.
- We use label elements to name form controls like inputs, selects, and text areas.
We use native HTML5 elements where they are accessibility supported, and don't use ARIA techniques when a native HTML element for that feature already exists. Examples:
- Instead of <div role="button">, we use the <button> element.
- Instead of an ARIA disclosure, we use the native <details> element.
Once semantics are in place, we can apply styling as necessary.
Status
Consequences
Using native HTML5 means we are familiar with what the elements do, their functionality, and what attributes are allowed. Misuse of these elements can create confusing and unequal user experiences.
Some HTML elements are not fully accessibility-supported, like the date input type or definition lists. We use caution and test content built with HTML5 elements that don't have full accessibility support, or find alternative HTML solutions to that markup.
Some custom features or widgets don't have an HTML equivalent, like accordions, tablists, or alert messaging. For widgets that need to be custom built, we use the appropriate ARIA authoring pattern.
Most websites or web apps should have the infrastructure to support HTML5 semantics. In rare cases native HTML5 isn't well supported, ARIA should be used as a fallback where appropriate to provide the necessary semantics and keyboard behavior. If the site is a legacy platform with outdated code, we recommend updating the site to modern HTML standards.