语义化布局

解决什么问题

页面用 div + class 堆出来的「div soup」在浏览器里看不出问题，但机器读不懂结构：屏幕阅读器只能靠地标角色判断区域用途，爬虫难以区分主内容与侧边栏，结构化数据（尤其是 featured snippets）也需要列表、表格标题这类语义线索。这个技能在交付前对 HTML 做一轮语义与无障碍审计，把「该有的标签有没有、该只有一个的有没有出现两份」变成可复现的 PASS / WARN 结论。

核心能力与检查步骤

• 必备语义元素：逐项检查页面是否包含约定的核心容器，缺失即判 FAIL；存在时输出实例数，例如 ✅ PASS <main> found (N instances)。
• 推荐语义元素：不强制，但缺失会给出 ⚠️ WARN，如「Consider using … for content structure」。
• Skip navigation：查找跳转链接（a、#skip-nav、skip-to-content），缺失时提示为无障碍补充跳转入口。
• Div-soup 检测：统计 div 与语义元素（header、main、footer、nav、article、section、aside、figure）的数量比；有 div 但语义元素为零判 FAIL，div 超过语义元素 5 倍判 WARN。
• ARIA 地标角色：检查 banner、navigation、main、contentinfo、search 五类角色，命中即 PASS 并列出。
• 布局建议：main 为 0 或多于 1 个时告警；统计不在任何语义容器内的 h1–h3 并建议包裹；超过 3 张未用 figure 包裹的图片、正文出现日期但缺少 time 元素、列表型内容未用 ul/ol、表格缺少 caption 均触发 WARN。

边界与注意点

• Next.js 等 React 应用的根节点通常是 div 或 section，不算 div-soup，应审计其内部的语义元素。
• SSR 与客户端渲染结果可能不同，优先审计首屏 SSR 输出。
• 隐藏容器内的内容在静态 HTML 中不可见，需注明该局限；Web Components / Shadow DOM 内部的语义元素同理。
• 邮件类页面（如退订页）天然缺少 header/main/footer，不应告警。
• lang 属性检查由 international-seo 技能负责，本技能不重复覆盖。