Semantic Markup

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):

Anvil2 Responsibility	Implementor Responsibility
Anvil2 provides components with proper semantic tags and/or roles on them, along with the basic page layout.	Implementors ensure they are using the provided components correctly, while also making sure they are manually establishing correct logical flow and content separation of content.

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):

Anvil2 Responsibility	Implementor Responsibility
Anvil provides components where text elements can be selected and handles page titles properly but not placement of the tags outside H1.	Implementors ensure they are not skipping heading levels when creating their pages. Layout of the page should reflect a table of contents with logical heading order.

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):

Anvil2 Responsibility	Implementor Responsibility
Anvil2 provides you with main page content containers but not the containers needed for this foundation.	Implementors ensure that when creating content that they are using correct logical container elements in the right places.

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):

Anvil2 Responsibility	Implementor Responsibility
Anvil2 provides a text component for consistent typography visuals but not styling utilities for style variations.	Implementors ensure they are using the correct html tags to denote their content within the text component.

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

​Overview

​Heading Hierarchy

​Best Practices

​Common Pitfalls

​Sections, Articles, and Asides

​Best Practices

​Common Pitfalls

​Text Style Variations

​Best Practices

​Common Pitfalls

Overview

Heading Hierarchy

Best Practices

Common Pitfalls

Sections, Articles, and Asides

Best Practices

Common Pitfalls

Text Style Variations

Best Practices

Common Pitfalls