Skip to main content
Accessibility
Purpose of These DocsThese docs are meant as a starting point for using Anvil2 accessibly. While the contents can contribute to building accessible interfaces from scratch, that is not the main goal.

​
Overview

Directly Related WCAG Guidelines(s): Semantic HTML provides a crucial structural foundation, allowing assistive technologies to accurately interpret and navigate content. Appropriately used elements like <button>, <nav>,** <main>**, and proper heading hierarchy create a clear content map. This map, denoting page landmarks, aids both manual users and assistive tools in understanding and navigating content more easily. Without this semantic markup, users relying on assistive technology may struggle to comprehend the interface structure, missing vital navigation cues and content relationships. A proper semantic structure ensures all users can access the same information and functionality, regardless of how they interact with your site. It’s essential to separate the design’s appearance from the page’s underlying skeleton. This provides a clear structure that screen readers can navigate, enhancing accessibility, SEO, code maintainability, and overall user experience.

​
Heading Hierarchy

Directly Related WCAG Guidelines(s): Heading hierarchy creates a logical content structure that helps all users navigate content efficiently. Screen readers rely on heading structure to provide navigation shortcuts and announce content organization, while visual users need clear content hierarchy to understand information relationships. Proper heading implementation ensures that content structure is programmatically determinable, making it easier for assistive technologies to interpret and navigate. This includes establishing clear content hierarchy, maintaining logical heading order, and creating consistent navigation patterns for related content. Without proper heading hierarchy, users may struggle to understand content organization, become disoriented about information structure, or fail to navigate efficiently through complex content layouts.

​
Best Practices

  • Use only one <h1> per page as the main title
  • Use <h2> for major sections, <h3> for subsections, and so on in sequential order

​
Common Pitfalls

  • Skipping heading levels (e.g., jumping from <h2> to <h4>) creates confusion for assistive technologies and breaks the logical flow of your content structure

​
Sections, Articles, and Asides

Directly Related WCAG Guideline(s): Semantic containers provide crucial structural context that helps users understand content organization and purpose. Screen readers rely on these elements to navigate and announce content structure, while all users benefit from clear content hierarchy and logical organization. Proper use of semantic containers ensures that content relationships and structure are programmatically determinable, making it easier for assistive technologies to interpret and navigate. This includes grouping related content, establishing clear content boundaries, and creating logical information architecture. Without proper semantic container implementation, users may struggle to understand content relationships, become disoriented about information structure, or fail to navigate efficiently through complex content layouts.

​
Best Practices

  • Use <section> to group related content within a page
  • Use <article> for self-contained, independently distributable content (like blog posts or news items)
  • Use <aside> for content that’s tangentially related to the main content (like sidebars or pull quotes)

​
Common Pitfalls

  • Using generic <div> elements instead of semantic tags—class names are not a substitute for proper semantics
  • Misusing semantic tags for layout purposes, which can confuse assistive technologies about the flow of information

​
Text Style Variations

Directly Related WCAG Guidelines(s): Text style variations help users understand the importance, emphasis, and context of content through both visual and programmatic means. Screen readers rely on semantic markup to announce text with appropriate emphasis, while visual users need clear visual cues to understand content hierarchy and meaning. Proper use of semantic text elements ensures that all users can access the same information regardless of how they interact with content. This includes using appropriate emphasis for important information, maintaining visual hierarchy, and ensuring that text variations enhance rather than hinder comprehension. Without proper text variation implementation, users may miss critical information, become confused about content importance, or fail to understand the intended meaning of emphasized text.

​
Best Practices

  • Use <strong> when text is important or urgent—like warnings, required field indicators, or critical information
  • Use <b> when you want to draw attention without conveying importance—like product names, keywords, or UI elements
  • Use <em> when you want to emphasize or stress specific words or phrases to change the meaning
  • Use <i> when text has a different voice or mood—like foreign words, technical terms, book titles, or thoughts

​
Common Pitfalls

  • Using semantic tags for purely decorative purposes instead of conveying meaning
  • Relying on visual styles alone instead of using appropriate semantic tags
Last modified on December 29, 2025