Community生產力與協作github.com

語意化 HTML

審查、改寫並解釋 HTML5 語意(標籤、地標、標題、表單、ARIA)。當使用者貼上 HTML 或要求標記審查、正確標籤、可及性或修正「div 泛濫」時使用。

語意化 HTML 是什麼?

此技能專注於審查 HTML 標記,提供修正版本,並解釋每個選擇背後的理由。它強調純粹的 HTML5,與框架無關:即使原始碼是 JSX 或其他範本,也只分析最終的標記並以 HTML 回應。核心原則是透過瀏覽器的可及性樹(accessibility tree)來說明語意的重要性:螢幕閱讀器、搜尋引擎和閱讀模式依賴的是 DOM 結構而非 CSS 樣式。技能提供一個詳細的審查清單,涵蓋文件結構、地標、標題層級、互動元素、表單、清單、表格、媒體、文字語意和 ARIA 的使用原則。輸出格式包含診斷(依影響程度分類)、修正後的程式碼(僅對更改部分加上簡短註解)以及針對每個重要決策的解釋,確保使用者不僅知道如何修改,更理解背後的運作機制。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/lucasaugustsof/skills/tree/HEAD/semantic-html

Installed? Explore more 生產力與協作 skills: steipete/gemini, steipete/gh-issues, steipete/skill-creator · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

語意化 HTML 是做什麼的?

協助審查 HTML,回傳修正版本並解釋每個選擇背後的理由。重點始終是純 HTML5,與框架無關:若程式碼以 JSX 或其他範本形式出現,僅分析最終標記並以 HTML 回答。

以使用者書寫的語言回覆。

為何語意重要(用於解釋)

瀏覽器將 HTML 轉換為 DOM,並從中建立可及性樹。每個標籤都有一個隱含角色(<button> → 按鈕,<nav> → 導覽,<h2> → 標題層級 2)。螢幕閱讀器、搜尋引擎、閱讀模式及擴充功能讀取的是這棵樹,而非 CSS。一個樣式化成按鈕的 <div> 看起來像按鈕,但對這棵樹來說它只是一個通用區塊:它不會獲得焦點、不會回應 Enter/空白鍵,也不會被宣告為按鈕。

解釋時應將論點建立在這個基礎上——瀏覽器理解的是什麼,對使用頁面的人來說有什麼改變——而不是背誦規則。偏好具體範例(「螢幕閱讀器會宣告⋯」、「Tab 鍵會跳過這個元素⋯」)而非抽象概念。

實用的心智測試:如果 CSS 消失了,結構仍然合理嗎?

工作流程

  1. 先理解內容,再考慮標籤。 每個區塊是什麼?導覽、主要內容、獨立項目、互動控制項?如果意圖不明確(例如看起來像按鈕的連結),假設最可能的讀法並說明你假設了哪一種。
  2. 使用下方清單進行審查。
  3. 以定義的格式回答。

審查清單

文件

  • <!DOCTYPE html>、<html lang="...">、<meta charset="utf-8">、<meta name="viewport">、一個描述性的 <title>(僅當片段為完整文件時)。

地標

  • <header>、<nav>、<main>(每個頁面僅一個可見)、<aside>、<footer>。
  • <section> 將主題性內容分組,通常應有標題;若無標題則可能是 <div>。
  • <article> 是本身有意義的內容(文章、產品卡、留言)。
  • 頁面上有多個 <nav> → 使用 aria-label 區分它們。

標題

  • 層級不跳階(h2 → h4 是問題)。
  • 標題描述其區段;不要用標題來放大文字,也不要用樣式文字取代標題。

互動

  • 頁面上的動作 → <button>(表單內需加上明確的 type)。導覽到其他 URL → <a href>。
  • <div onclick>、<span onclick> 及沒有 href 的 <a> 是紅旗警示。
  • 在重新建立原生元素前先考慮它們:<details>/<summary>、<dialog>。

表單

  • 每個欄位都有關聯的 <label>(使用 for/id 或包裹 input)。placeholder 不能取代 label。
  • Radio/Checkbox 群組放在 <fieldset> + <legend> 中。
  • 使用適當的 type(email、tel、number、date⋯)及 autocomplete。

清單與表格

  • 一組項目 → <ul>/<ol>;術語-定義配對 → <dl>。
  • <table> 僅用於表格資料,需包含 <caption>、<thead> 及 <th scope>。絕不用於版面配置。

媒體

  • <img> 加上描述其用途的 alt;裝飾性 → alt=""。
  • 有說明的圖片 → <figure> + <figcaption>。

文字

  • 有意義的強調:<strong>/<em>;<b>/<i> 僅用於無重要性的樣式偏移。
  • 合適處使用 <time datetime>、<blockquote>/<q>、<cite>、<abbr>、<code>/<pre>、<address>。
  • <br> 僅用於內容本身的換行(地址、詩句),非用於間距。

ARIA

  • 第一條規則:若有原生元素存在,使用它而非 ARIA。
  • 標記冗餘 ARIA(<button role="button">、<nav role="navigation">)以及與標籤矛盾的 ARIA。

不要過度修正。 當一個區塊僅用於版面或樣式時,<div> 和 <span> 是正確的。將每個 <div> 換成 <section> 反而會使可及性樹變差。

回應格式(混合語氣:直接修正 + 簡短原因)

診斷

按影響程度分組的問題清單:

  • 破壞可及性/可用性 — 某些東西阻止使用者使用頁面(無焦點的按鈕、無標籤的欄位、無替代文字的圖片)。
  • 語意不精確 — 運作正常但傳達錯誤結構(跳階標題、沒有標題的 section)。
  • 細節 — 細微改進。

每項:哪裡有問題 → 該用什麼。一行。

修正後的程式碼

完整的改寫 HTML,僅在變更的部分加上簡短註解。

原因

2 到 5 個簡短說明,每個對應一個重要決策,連結到瀏覽器/可及性樹的行為。如果某個概念是核心(如隱含角色、地標),用具體範例解釋一次。

如果程式碼已經很好,請清楚說明,並只指出真正值得調整的部分。

範例

輸入:

<div class="header">
  <div class="logo">Store</div>
  <div class="menu"><a>Home</a><a>Products</a></div>
</div>
<div class="title">Deals</div>
<div onclick="buy()">Buy</div>

輸出(節錄):

診斷

  • 破壞可用性:<div onclick> → <button type="button">;無 href 的 <a> → 有 href 的連結。
  • 語意不精確:.header → <header>;.menu → 含 <ul> 的 <nav>;.title → <h1>;缺少 <main>。

修正後的程式碼

<header>
  <p class="logo">Store</p>
  <nav aria-label="Main">
    <ul>
      <li><a href="/">Home</a></li>
      <li><a href="/products">Products</a></li>
    </ul>
  </nav>
</header>
<main>
  <h1>Deals</h1>
  <button type="button" onclick="buy()">Buy</button>
</main>

原因

  • <div> 不在 Tab 順序中,也不會回應 Enter;<button> 自帶焦點與鍵盤支援,並會被宣告為「按鈕」。
  • 無 href 的 <a> 對瀏覽器而言不是連結:它不會獲得焦點,也不會出現在螢幕閱讀器的連結清單中。
  • <nav> 和 <main> 成為地標:螢幕閱讀器使用者可以直接跳轉到它們。

參考來源

對於某個規則有疑問時,在 MDN 或 HTML 生活標準中確認(若有文件工具可用則使用它),並引用連結。

相關技能