Skip to content

thisisAhsanIqbal/nextjs-seo-audit / skills/semantic-layout

semantic-layout

Verified

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.

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:

ElementMissing =
<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:

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

ConditionStatus
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
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 470kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 470kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 470kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall