Skip to main content

HTML and Page Structure

Valid HTML​

Guidance​

  • Write well-formed and valid HTML.
  • Ensure elements are properly nested and closed.
  • Avoid duplicate IDs.
  • Do not place elements in invalid contexts (e.g. interactive elements inside interactive elements).
  • Invalid HTML can break semantics, focus behavior and assistive technology support.

Avoid Unnecessary ARIA​

Guidance​

  • Use native HTML elements and attributes whenever possible. If HTML can express the structure or behavior, prefer HTML over ARIA.
  • Do not introduce ARIA roles or attributes to fix incorrect HTML. Always correct the underlying HTML first.
  • For detailed ARIA usage patterns, see section ARIA Usage.

Structural Semantics​

Principle​

Use semantic HTML to provide built-in accessibility, predictable behavior and minimal need for ARIA. HTML semantics must always match the intended purpose of the element.

Guidance​

  • Use HTML5 structural elements to describe the layout and landmarks:
    • <header> – page or section header
    • <main> – primary page content (use exactly one per page, do not nest)
    • <nav> – site or internal navigation
    • <section> – thematically grouped content within the page
    • <article> – standalone, self-contained content
    • <aside> – supplementary or secondary content
    • <footer> – page or section footer
  • Use page-level <header> and <footer> for global page structure. Headers and footers inside <section> or <article> represent section-level content and are not page landmarks.
  • Use structural elements consistently across templates so that screen readers can rely on landmarks (e.g. always having a clear <main> and <nav> where applicable).
  • If multiple landmarks of the same type are present (e.g. multiple <nav> or <aside>), provide a clear accessible name using aria-label or aria-labelledby.
    • Example: "Primary navigation", "Footer navigation", "Category navigation".
  • A <section> becomes a landmark only if it has an accessible name. Use it for meaningful sections, not as a generic wrapper.
  • Avoid using bare <div> elements for meaningful structure when a semantic element is available – relationships must be represented in HTML, not only visually.
  • Use ARIA landmark roles only when native HTML cannot express the structure:
    • Do not add roles like role="navigation" when using semantic elements such as <nav>.
    • Use role="region" sparingly and only when the region has an accessible name and represents a meaningful area users may want to navigate to.
  • Don’t landmark lists directly: <ul>/<ol> are lists, not landmarks. If a list represents a region, wrap it in an appropriate landmark (e.g., a <nav> for a menu).
  • Ensure elements appear in a meaningful sequence – the DOM order must match the intended reading order. Do not rely on CSS reordering (e.g. order in flex/grid) to change visual order in ways that break this.

Comparison of page layouts created with non-semantic elements versus layouts with semantic HTML elements

WCAG Reference​

Page Title​

Principle​

Provide descriptive page titles that clearly identify the current page and its purpose.

Guidance​

  • Every page must contain a descriptive <title> element inside <head>.
  • The <title> should accurately reflect the current page or view.
  • The page <h1> should describe the same purpose and ideally align with the page title.
  • Page title and heading wording should follow the design specification.

WCAG Reference​

Headings and Hierarchy​

Principle​

Use heading elements to define a clear and logical content structure that can be understood and navigated by assistive technologies.

Guidance​

  • Use semantic heading elements (<h1> – <h6>) to reflect the actual structure of the content.
  • Each page must contain exactly one <h1>, clearly identifying the main topic or purpose of the page.
  • Do not skip heading levels (no <h1> → <h3> without an <h2>).
  • Do not choose heading levels based on font size — adjust visual styles using CSS, not HTML hierarchy.
  • Do not use headings purely for styling; if text is not a section heading, use a normal paragraph or styled text instead.
  • Headings must be descriptive and clearly communicate the content of the section.
  • Headings allow screen reader users to navigate the page structure and jump between sections.
  • If a section lacks a heading but would benefit from one for accessibility, propose and discuss adding a visible heading with the design first. If this is not possible, agree on the wording and use a visually hidden heading.
  • Keep heading hierarchy consistent across templates, pages, and breakpoints.

Incorrect versus correct HTML heading hierarchy.

WCAG Reference​

Lists and Grouped Content​

Principle​

Use list elements to represent groups of related items so their structure and relationships are clear to assistive technologies.

Guidance​

  • Use <ul> or <ol> when content represents a list.
  • Do not simulate lists using <div> or <p> elements; assistive technologies must understand them as actual lists.
  • Use <dl>, <dt>, <dd> for name–value pairs (e.g. glossary, metadata).
  • Use list elements for navigation menus unless a different semantic pattern is intentionally required.

Principle​

Use the correct HTML element for each interaction so its purpose and behavior are clear to users and assistive technologies.

Guidance​

  • Use <button> for actions that change something on the page: opening dialogs, toggling content, submitting forms, triggering scripts, or modifying UI state.
  • Use <a> only for navigation — going to another page, route, anchor, external destination or download.
  • Link text must clearly describe the destination or purpose of the link.
  • For repeated links or actions, provide additional context through aria-label.
    • Example: aria-label="Read more about accessibility guidelines".
  • Accessible names and terminology should be defined consistently in the design. See section Consistent Terminology and Labels.
  • Always use a valid href attribute on <a> elements. Do not use empty or placeholder values (e.g. href="#") for interactive behavior.
  • Do not use non-interactive elements (<div>, <span>) with role="button" or similar ARIA hacks — native elements provide correct keyboard and accessibility behavior automatically.
  • Buttons must be operable with keyboard by default (Enter + Space). Using the native element ensures this without extra code.
  • Never use <a> as a fake button by preventing its default behavior. Fix the semantics instead (replace with <button>).
  • Styling does not define semantics, but visual design must still match user expectations. Styling a button to look like a link (or a link to look like a button) should only be used in clear, intentional cases and never in ways that confuse the user about what the element does.

Allowed in specific, intentional cases:​

  • A call-to-action <a> (e.g., “Buy now”, “Learn more”) styled as a button because it leads to a new page.
  • A secondary action like “Cancel” implemented as a <button> but visually styled as a link.

Not allowed:​

  • A link styled as a button when it only expands a section or triggers a UI change → must be a <button>.
  • A destructive or critical action styled to look like a harmless text link → breaks user expectations.

WCAG Reference​

Guidance​

  • Link text must clearly describe the destination or purpose of the link.
  • Avoid vague labels such as “Click here”, “More” or “Read more” without context.
  • When possible, make the link understandable on its own.
  • For repeated links, add context visually or through the accessible name.
    • Example: Read more about accessibility guidelines.

Form Elements​

Principle​

Use native form elements and proper labeling to ensure inputs are understandable, operable and correctly announced by assistive technologies.

Guidance​

  • Use native form elements whenever possible: <input>, <textarea>, <select>, <fieldset>, <legend>. They provide correct keyboard behavior, focus handling and programmatic accessibility by default.
  • Every form control must have an associated <label>. Do not use placeholder text as a substitute.
  • Link labels and inputs explicitly using for + id (or wrap the input inside the label).
  • Use <fieldset> and <legend> to group related inputs (e.g. radio buttons, checkboxes).
  • Mark required fields programmatically using the native required attribute (and not only visually).
  • When an input requires a specific format or additional context, provide clear instructions alongside the label.
  • When displaying hints or helper text, connect them to the input using aria-describedby so assistive technologies can announce them.
  • Avoid replacing standard controls with custom components unless necessary.
  • If you must implement a custom form UI (e.g., custom select), ensure it fully replicates native behavior:
    • keyboard navigation
    • focus management
    • ARIA roles and states
    • announcing the current value and changes
  • Choose appropriate input type attributes (email, tel, date, etc.) so the control is correctly announced by assistive technologies and triggers the appropriate virtual keyboard on mobile devices.
  • Use appropriate autocomplete attributes to help users fill forms efficiently.

WCAG Reference​

Input Errors and Validation​

Principle​

Users must be able to identify input errors, understand what went wrong, and know how to fix them.

Guidance​

  • Clearly identify fields with errors both visually and programmatically.
  • Use aria-invalid="true" on invalid fields.
  • Place error messages close to the relevant input or clearly associate them with the field.
  • Associate error messages with inputs using aria-describedby or aria-errormessage.
  • Error messages must clearly explain what is wrong and how to fix it.
  • Do not rely on color alone to indicate errors — use additional cues such as text or icons (this should already be defined in the design system or provided by the design).
  • Ensure error messages are announced by assistive technologies when they appear (e.g. via aria-live or proper association).

Images and Non-Text Content​

Principle​

Provide meaningful text alternatives for images and other non-text content so that users of assistive technologies receive the same information or purpose as visual users. Decorative content must be hidden from assistive technologies.

Guidance​

  • All meaningful non-text content must have a text alternative that serves an equivalent purpose.
  • Provide alt text that describes the image’s purpose, not its visual appearance.
    • Example:
      • Good: “Free shipping badge”
      • Bad: “Blue circular icon with truck”
  • Use alt="" for decorative images to be ignored by screen readers. Only images that provide information require meaningful alt text.
  • Never omit the alt attribute on <img> elements. An empty alt="" is valid; missing alt is not.
  • Do not repeat information already present in adjacent visible text. Keep alt text concise and avoid redundancy.
  • For linked images, the alt text must describe the destination or purpose, not the visual content.
    • Example: “Cordless hammer drill – details”
  • Complex non-text content (charts, diagrams, infographics, visual indicators) requires an accessible text alternative. Provide a nearby textual explanation or reference it via aria-describedby.
  • Decorative non-text content (e.g. background patterns or purely visual icons) should be hidden from assistive technologies.
  • Avoid embedding essential text inside images. If unavoidable (e.g. logos, promotional banners), ensure the alt text includes all meaningful wording.

WCAG Reference​