semantic-layout

name	semantic-layout
description	Validates HTML5 semantic elements, ARIA landmarks, skip navigation, and page structure. Use when auditing semantic HTML, accessibility, or content structure for SEO. For the lang attribute, see the international-seo skill.
license	MIT
metadata	{"author":"Muhammad Ahsan Iqbal (https://muhammadahsaniqbal.com)","linkedin":"https://www.linkedin.com/in/ahsan-iqbal-digitalmarketingexpert/","version":"1.0"}

Semantic Layout

Audit the page for proper use of HTML5 semantic elements and accessibility.

Note: The lang attribute check is handled by the international-seo skill. Do not duplicate it here.

1. Required semantic elements

These elements must be present:

Element	Missing =
<header>	❌ FAIL
<main>	❌ FAIL
<footer>	❌ FAIL
<nav>	❌ FAIL

Report count if present: ✅ PASS "<tag> element found (N instance(s))"

2. Recommended semantic elements

These elements should be present:

Element	Missing =
<article>	⚠️ WARN "Consider using for content structure"
<section>	⚠️ WARN
<aside>	⚠️ WARN
<figure>	⚠️ WARN

3. Skip-navigation link

Check for accessibility skip links: <a href="#main-content">, <a href="#content">, or <a href="#main">

• Found → ✅ PASS
• Missing → ⚠️ WARN "Add skip-navigation link for accessibility"

4. Div-soup detection

Count <div> elements vs semantic elements (header, main, footer, nav, article, section, aside, figure):

Condition	Status
Divs > 0 but zero semantic elements	❌ FAIL "Restructure with semantic HTML"
Divs > 5× semantic element count	⚠️ WARN "High div-to-semantic ratio"

5. ARIA landmark roles

Check for these roles: banner, navigation, main, contentinfo, search

• Any found → ✅ PASS — list which roles are present

6. Layout suggestions

Single <main>

• 0 <main> elements → ⚠️ WARN "Wrap primary content in <main>"
• Multiple <main> → ⚠️ WARN "Should have only one"

Headings inside semantic containers

• Count <h2>, <h3>, <h4> that are NOT inside <section>, <article>, <aside>, or <main>
• If any found → ⚠️ WARN "Wrap content blocks in <section> or <article>"

Images without <figure>

• If > 3 images not wrapped in <figure> → ⚠️ WARN "Use <figure>/<figcaption>"

Date markup

• If <time> elements found → ✅ PASS
• If date patterns found in text but no <time> elements → ⚠️ WARN "Wrap dates in <time datetime=\"...\">"

List elements

• No <ul> or <ol> found → ⚠️ WARN "Use lists for list-type content (improves featured snippet eligibility)"

Tables without captions

• Tables missing <caption> → ⚠️ WARN "Add captions for accessibility"

Edge cases

• Next.js and React apps render into a root <div id="__next"> or <div id="root"> — this does not count as "div-soup"; evaluate the semantic elements inside it
• Server-rendered HTML may differ from client-rendered HTML — audit the initial SSR output when possible
• Components rendered inside <template> or <slot> elements are not visible in static HTML — note this limitation
• Email-style pages (e.g. unsubscribe pages) may legitimately lack <article>, <section>, or <aside> — do not flag as WARN
• If a page uses Web Components or Shadow DOM, semantic elements inside the shadow tree may not be visible — note as limitation