thisisAhsanIqbal/nextjs-seo-audit / skills/semantic-layout
semantic-layout
VerifiedValidates 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 3.5 KB |
SKILL.md
View on GitHub---
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](../international-seo/SKILL.md) 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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |