菜单
Use when building or reviewing a web page's HTML structure — to ensure heading hierarchy, landmark regions, and semantic elements convey the correct document outline to screen readers and assistive technology.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/jeffreytse/grimoire-core --skill write-semantic-html-structure命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
Use when comparing very differently-titled roles for compensation banding, leveling, or organizational design — score each role's inherent Know-How (knowledge, skills, experience required), Problem Solving (complexity and freedom of thinking, scored as a percentage of Know-How), and Accountability (freedom to act and magnitude of impact), because job titles and informal seniority perceptions vary inconsistently across departments and don't provide a comparable basis on their own.
Use when many people request your scarce time, mentorship, or expertise and you cannot evaluate their genuine commitment level from a conversation alone — require a specific, costly, objectively verifiable unit of self-directed output (a set number of completed attempts) before engaging, because genuine commitment is what a conversation cannot reliably reveal but a completed, verifiable body of work can.
Use when deciding how to allocate a manager's or leader's limited time across competing activities — before defaulting to whatever is most urgent, estimate each candidate activity's leverage (how many people's output it affects, for how long, and whether it requires your specific position), because a manager's actual output is the output of the organization under their influence, not their own individual task completion.
基于 SOC 职业分类
正在显示 SKILL.md
| name | write-semantic-html-structure |
| description | Use when building or reviewing a web page's HTML structure — to ensure heading hierarchy, landmark regions, and semantic elements convey the correct document outline to screen readers and assistive technology. |
| source | W3C WCAG 2.1 SC 1.3.1 Info and Relationships (Level A), SC 2.4.6 Headings and Labels (Level AA); W3C HTML5 semantic element specification; ARIA Landmarks specification |
| tags | ["accessibility","wcag","a11y","semantic-html","headings","landmarks","screen-reader","developer"] |
| related | ["design-accessibility-standards","apply-aria-roles","apply-skip-navigation"] |
Use heading hierarchy and landmark regions to give the page a logical structure that screen readers can navigate.
Adopted by: WCAG 2.1 SC 1.3.1 (Level A) and SC 2.4.6 (Level AA) are required by
all major accessibility standards (Section 508, EN 301 549, PSBAR 2018). The W3C HTML5
spec's semantic elements (<nav>, <main>, <article>, <aside>) are supported in
all modern browsers since 2014. WebAIM screen reader user surveys consistently show
heading navigation as the #1 navigation technique — 67% of screen reader users use
headings to find content.
Impact: WebAIM Million 2024 found that empty heading levels and missing landmark
regions appear in 43% of analyzed pages. Screen reader users navigate by landmarks
(R key in NVDA) and headings (H key) to skip to desired content — without these,
every page requires linear reading from top to bottom.
Why best: <div> and <span> have no semantic value. A page built entirely with
divs forces screen reader users to listen to everything sequentially. Semantic elements
provide free navigation, document structure, and AT compatibility with no additional
ARIA required.
Sources: W3C WCAG 2.1 SC 1.3.1, 2.4.6 (2018); WebAIM Screen Reader User Survey #10 (2024); W3C HTML5 semantic element specification
<h1> per page — match the page title<!-- Wrong — multiple h1s, skipped levels -->
<h1>Company Name</h1>
<h1>Products</h1> <!-- second h1 — creates ambiguous top-level -->
<h3>Widget A</h3> <!-- skipped h2 — broken outline -->
<!-- Right — one h1, sequential hierarchy -->
<h1>Products</h1>
<h2>Widgets</h2>
<h3>Widget A</h3>
<h3>Widget B</h3>
<h2>Services</h2>
Heading levels convey document outline — never choose a heading level for visual size. Use CSS to style headings; use heading elements only for structure.
<!-- Wrong — all divs, no structure -->
<div class="header">...</div>
<div class="nav">...</div>
<div class="content">...</div>
<div class="sidebar">...</div>
<div class="footer">...</div>
<!-- Right — native semantic elements -->
<header>...</header>
<nav aria-label="Main navigation">...</nav>
<main>
<article>...</article>
<aside>...</aside>
</main>
<footer>...</footer>
Each landmark element maps to an implicit ARIA role: <main> = role="main",
<nav> = role="navigation", <header> = role="banner", <footer> = role="contentinfo".
Native elements are always preferred over role= on divs.
<!-- Wrong — two nav landmarks with identical names -->
<nav>...</nav>
<nav>...</nav>
<!-- Right — aria-label distinguishes them -->
<nav aria-label="Main navigation">...</nav>
<nav aria-label="Breadcrumb">...</nav>
Screen readers list all landmarks — duplicate names create confusion.
Use aria-label or aria-labelledby to distinguish repeated landmark types.
<!-- Wrong — visual list with no semantics -->
<div class="list">
<div>• Item one</div>
<div>• Item two</div>
</div>
<!-- Right — screen reader announces "list, 2 items" -->
<ul>
<li>Item one</li>
<li>Item two</li>
</ul>
<!-- Tables: always include <caption> and <th scope="col/row"> -->
<table>
<caption>Q3 Sales by Region</caption>
<thead>
<tr><th scope="col">Region</th><th scope="col">Revenue</th></tr>
</thead>
<tbody>
<tr><td>North</>$1.2M
Use the browser extension "HeadingsMap" or the axe DevTools outline view to verify:
<h1> at the page level<header> inside <article> scopes to the article, not the page. Use landmark elements deliberately, not as generic containers.role= attributes instead for accessible email.Styling headings visually rather than structurally. Using <h3> because it looks like the right size — not because it's the third level in the hierarchy — breaks the outline. Style with CSS; use heading levels for structure only.
Multiple <main> elements. A page must have exactly one <main>. Multiple <main> elements are invalid and confuse AT.
<section> and <article> without headings. Both elements are expected to have a heading that names them. A <section> without a heading provides no navigation benefit and is treated as a generic container.