Semantic HTML Skill
Transform markup from presentation-focused to meaning-focused, enabling accessibility, SEO, and AI/voice interface compatibility.
🎯 Purpose
Provide atomic, single-responsibility operations for:
- Document outline and structure semantics
- Content sectioning (
<article>,<section>,<nav>) - Landmark roles and ARIA mapping
- Microdata and structured data hints
- SEO and accessibility improvements
📥 Input Schema
interface SemanticHtmlInput {
operation: 'analyze' | 'convert' | 'validate' | 'suggest';
content_type: ContentType;
markup?: string; // Existing HTML to analyze/convert
context?: {
page_type: 'homepage' | 'article' | 'product' | 'contact' | 'search';
has_sidebar: boolean;
has_comments: boolean;
};
options?: {
semantic_level: 'strict' | 'moderate' | 'minimal';
include_landmarks: boolean;
preserve_classes: boolean;
};
}
type ContentType =
| 'article' // Blog post, news article
| 'navigation' // Nav menus, breadcrumbs
| 'sidebar' // Aside content
| 'header' // Page/section headers
| 'footer' // Page/section footers
| 'section' // Generic thematic sections
| 'figure' // Images, diagrams, code blocks
| 'list' // Lists of items
| 'table'; // Tabular data
📤 Output Schema
interface SemanticHtmlOutput {
success: boolean;
markup: string;
semantic_score: number; // 0-100
improvements: Improvement[];
landmark_map: LandmarkMap;
outline: DocumentOutline;
}
interface Improvement {
original: string;
suggested: string;
reason: string;
impact: 'critical' | 'high' | 'medium' | 'low';
}
🛠️ Core Operations
1. Semantic Element Selection
┌─────────────────────────────────────────────────────────────┐
│ Semantic Element Decision Tree │
├─────────────────────────────────────────────────────────────┤
│ │
│ Is it the main content? │
│ └── Yes → <main> │
│ └── No ↓ │
│ │
│ Is it independently distributable? │
│ └── Yes → <article> │
│ └── No ↓ │
│ │
│ Is it a thematic grouping with a heading? │
│ └── Yes → <section> │
│ └── No ↓ │
│ │
│ Is it navigation links? │
│ └── Yes → <nav> │
│ └── No ↓ │
│ │
│ Is it tangentially related content? │
│ └── Yes → <aside> │
│ └── No ↓ │
│ │
│ Is it introductory or navigational content? │
│ └── Yes → <header> │
│ └── No ↓ │
│ │
│ Is it footer/meta information? │
│ └── Yes → <footer> │
│ └── No → <div> │
│ │
└─────────────────────────────────────────────────────────────┘
2. Landmark Mapping
| HTML5 Element | ARIA Landmark Role | Implicit Role |
|---------------|-------------------|---------------|
| <header> (page) | banner | Yes |
| <nav> | navigation | Yes |
| <main> | main | Yes |
| <aside> | complementary | Yes |
| <footer> (page) | contentinfo | Yes |
| <section> | region | If has accessible name |
| <article> | article | Yes |
| <form> | form | If has accessible name |
3. Page Structure Patterns
Blog/Article Page
<body>
<header>
<nav aria-label="Main">...</nav>
</header>
<main>
<article>
<header>
<h1>Article Title</h1>
<p>By <a rel="author" href="/author">Author</a></p>
<time datetime="2025-01-15">January 15, 2025</time>
</header>
<section aria-labelledby="intro">
<h2 id="intro">Introduction</h2>
<p>Content...</p>
</section>
<section aria-labelledby="main-content">
<h2 id="main-content">Main Content</h2>
<p>Content...</p>
</section>
<footer>
<p>Tags: <a href="/tag/html" rel="tag">HTML</a></p>
</footer>
</article>
<aside aria-label="Related articles">
<h2>Related Articles</h2>
<ul>...</ul>
</aside>
</main>
<footer>
<nav aria-label="Footer">...</nav>
<p>© 2025</p>
</footer>
</body>
E-commerce Product Page
<body>
<header>
<nav aria-label="Main">...</nav>
<nav aria-label="Breadcrumb">
<ol>
<li><a href="/">Home</a></li>
<li><a href="/products">Products</a></li>
<li><a href="/products/widgets" aria-current="page">Widget</a></li>
</ol>
</nav>
</header>
<main>
<article itemscope itemtype="https://schema.org/Product">
<h1 itemprop="name">Product Name</h1>
<figure>
<img itemprop="image" src="product.jpg" alt="Product description">
</figure>
<section aria-labelledby="description">
<h2 id="description">Description</h2>
<p itemprop="description">Product details...</p>
</section>
<section aria-labelledby="pricing">
<h2 id="pricing">Pricing</h2>
<p itemprop="offers" itemscope itemtype="https://schema.org/Offer">
<span itemprop="price" content="29.99">$29.99</span>
</p>
</section>
</article>
<aside aria-label="Related products">
<h2>You May Also Like</h2>
<ul>...</ul>
</aside>
</main>
<footer>...</footer>
</body>
⚠️ Error Handling
Error Codes
| Code | Description | Recovery |
|------|-------------|----------|
| SH001 | Missing document outline | Add proper heading hierarchy |
| SH002 | No main landmark | Wrap primary content in <main> |
| SH003 | Multiple main elements | Keep only one <main> |
| SH004 | Section without heading | Add heading or use <div> |
| SH005 | Article without heading | Add <h1>-<h6> |
| SH006 | Nav without label | Add aria-label |
| SH007 | Div soup detected | Suggest semantic alternatives |
Recovery Procedures
Analyze Input → Identify Anti-Patterns → Suggest Fixes → Validate → Report
↓
[If conversion requested]
↓
Apply automatic fixes → Re-validate → Return improved markup
🔍 Troubleshooting
Problem: Screen reader announces wrong structure
Debug Checklist:
□ Is <main> present and unique?
□ Are headings in logical order (h1→h2→h3)?
□ Do sections have accessible names?
□ Are nav elements labeled uniquely?
□ Is banner/contentinfo outside main?
Problem: SEO not picking up content structure
Debug Checklist:
□ Is <article> used for main content?
□ Is author/date marked with rel/datetime?
□ Are headings used (not just styled divs)?
□ Is structured data (schema.org) present?
□ Are images in <figure> with <figcaption>?
Problem: "Div soup" - too many divs
Conversion Guide:
<div class="header"> → <header>
<div class="nav"> → <nav>
<div class="main"> → <main>
<div class="article"> → <article>
<div class="sidebar"> → <aside>
<div class="footer"> → <footer>
<div class="section"> → <section>
<div class="figure"> → <figure>
📊 Semantic Score Calculation
| Factor | Weight | Measurement | |--------|--------|-------------| | Landmark coverage | 25% | banner, main, contentinfo present | | Heading hierarchy | 25% | Correct h1→h6 nesting | | Semantic ratio | 20% | semantic / (semantic + div + span) | | Accessible names | 15% | Labeled sections and navs | | Article structure | 15% | Proper article markup |
Score Interpretation:
- 90-100: Excellent semantic structure
- 70-89: Good, minor improvements possible
- 50-69: Moderate, significant improvements needed
- <50: Poor, major restructuring required
📋 Usage Examples
# Analyze existing markup
skill: semantic-html
operation: analyze
markup: "<div class='main'><div class='post'>...</div></div>"
# Convert to semantic HTML
skill: semantic-html
operation: convert
content_type: article
markup: "<div class='blog-post'>...</div>"
options:
semantic_level: strict
include_landmarks: true
# Suggest improvements
skill: semantic-html
operation: suggest
content_type: navigation
context:
page_type: homepage
has_sidebar: true