content-semantics

コンテンツとセマンティクス

IsAgentReady.com の「コンテンツとセマンティクス」カテゴリの問題を修正します。エージェントはサーバーの HTML、DOM、アクセシビリティツリーを読み取ります。適切なセマンティック HTML は、これらの各ビューで信頼できるシグナルを提供します。

• 方法論のバージョン：2026-10-22。方法論：https://isagentready.com/en/methodology
• スコアリング（重みとポイント）：https://isagentready.com/api/v2/methodology/2026-10-22/scoring
• チェックポイントの全データ（ステージ、エビデンスタイプ、検証コマンド、再スキャンコマンド）：references/checkpoints.md

使用する場面

• スキャンで「コンテンツとセマンティクス」に失敗が表示される場合（旧 ID 3.x）。
• ページが、サーバーでレンダリングされたテキストのない空の SPA シェルである場合。
• 見出し、ランドマーク、代替テキスト、ラベル、ボタン名が不足している場合。
• フォームやウィジェットの操作がブラウザーエージェントにとって難しい場合。

使用しない場面

• JSON-LD または FAQPage マークアップの場合：structured-data を使用してください。
• robots.txt、sitemap、llms.txt の場合：ai-content-discovery を使用してください。
• WebMCP ツールの注釈の場合：agent-protocols を使用してください。
• HTML 構造を変更せずにビジュアルデザインを変更する場合。

手順

1. スキャンから失敗したチェックポイントを取得します。各結果には旧 ID（3.2）と固定 ID（ia.heading-hierarchy）があります。
2. 固定 ID と同じアンカーを使って、修正ワークフローに移動します。
3. サイトに合わせて例を調整します。example.com をサイトのドメインに置き換えてください。
4. 検証コマンドを実行します。検証コマンドはすべて読み取り専用です。シェルで確認できないチェックもあります。その後、再スキャンコマンドを使用します。
5. isagentready results <domain> --checkpoint <stable-id> を使用するか、isagentready.com で再スキャンします。

$ARGUMENTS が指定されている場合は、修正する URL またはチェックポイントとして使用してください。

チェックポイント

Strength は agentready.org の仕様レベル（MUST、SHOULD、MAY）です。Strength によってスコアが変わることはありません。

Legacy	Stable ID	Name	AR IDs	Strength
3.1	ia.server-rendered-content	サーバーサイドレンダリングされたコンテンツ	AR-READ-01, AR-READ-03	MUST
3.2	ia.heading-hierarchy	見出しの階層	AR-READ-03	MUST
3.3	ia.semantic-html	セマンティック HTML 要素	none	MUST
3.4	ia.landmarks-aria	ランドマークと ARIA	none	SHOULD
3.5	ia.image-alt	画像の代替テキスト	none	MUST
3.6	ia.lang-attribute	言語属性	none	MUST
3.7	ia.link-text	説明的なリンクテキスト	none	MUST
3.9	ia.form-labels	フォームラベルの網羅性	none	SHOULD
3.10	ia.form-autocomplete	フォームフィールドの自動補完	none	SHOULD
3.11	ia.keyboard-navigation	キーボードでの操作性	none	SHOULD
3.12	ia.document-title	ドキュメントタイトル	AR-READ-03	MUST
3.13	ia.button-names	ボタンのアクセシブルな名前	none	SHOULD
3.14	ia.aria-hidden	aria-hidden の誤用	none	SHOULD
3.15	ia.widget-state	動的なウィジェットの状態	none	SHOULD

修正ワークフロー

3.1 サーバーサイドレンダリングされたコンテンツ

JavaScript を使わずに、未加工の HTML の <body> に 200 文字を超える可視テキストが含まれている場合、合格となります。<noscript> のフォールバックでも部分的な評価を得られます。

1. 未加工の HTML 内で、<div id="root"></div> のような空のシェルを探します。
2. フレームワークで SSR または静的生成を有効にします。Next.js、Nuxt、Astro、Remix、SvelteKit、Angular については、references/ssr-strategies.md を参照してください。

   // Next.js App Router: a server component renders on the server by default
   export default async function Page() {
     const product = await getProduct();
     return <main><h1>{product.name}</h1><p>{product.summary}</p></main>;
   }
   

検証：curl -sf https://example.com/ | sed -e 's/<[^>]*>//g' | tr -s ' \n' | wc -c（200 を超えることを確認）

3.2 見出しの階層

ページに<h1>がちょうど1つあり、レベルが飛ばされず、空の見出しがない場合に合格します。

1. ページタイトルには<h1>を1つだけ使います。それ以外の<h1>要素は<h2>に変更します。
2. 見出しが<h1>から<h3>に飛ぶ場合は、欠けているレベルを追加します。

   <h1>Planner Pro</h1>
     <h2>Features</h2>
       <h3>Timeline view</h3>
     <h2>Pricing</h2>
   

3. ロゴ画像を<h1>に入れないでください。

確認方法：読み取り専用のシェルチェックでは合否を判定できません。再スキャンコマンドを使用してください。

3.3 セマンティック HTML 要素

ページに<header>、<nav>、<main>、<article>または<section>、および<footer>がある場合に合格します。

1. レイアウト用の<div>ラッパーをセマンティック要素に置き換えます。

   <body>
     <header><nav aria-label="Primary"><a href="/">Home</a></nav></header>
     <main><article><h1>Page title</h1><section><h2>Part</h2></section></article></main>
     <footer><p>Example Inc</p></footer>
   </body>
   

確認方法：curl -sf https://example.com/ | grep -oE '<(header|nav|main|article|section|footer)[ >]' | sort -u

3.4 ランドマークと ARIA

3つ以上のランドマーク領域と、aria-label、aria-current、aria-liveなどのARIA属性が1つ以上ページにある場合に合格します。

1. まず3.3のセマンティック要素を使用します。これらは暗黙的なランドマークになります。
2. 繰り返し使われるランドマークにラベルを付け、現在のページを示します。

   <nav aria-label="Primary"><a href="/" aria-current="page">Home</a></nav>
   <nav aria-label="Footer"><a href="/privacy">Privacy</a></nav>
   

3. <main role="main">のような冗長なロールは追加しないでください。

確認方法：curl -sf https://example.com/ | grep -oE '(role|aria-[a-z]+)="' | sort -u

3.5 画像の代替テキスト

各<img>にalt属性がある場合に合格します。画像のないページは合格です。装飾画像にはalt=""が適切です。

1. コンテンツ画像にはそれぞれ短い説明を記述します。装飾画像にはalt=""を使用します。

   <img src="team.jpg" alt="The Example Inc team at the 2026 offsite">
   <img src="divider.svg" alt="">
   

確認方法：curl -sf https://example.com/ | grep -oE '<img [^>]*>' | grep -vc 'alt='（0が期待値）

3.6 言語属性

<html>に、en、nl、en-USなどの有効なBCP 47コードを指定したlang属性がある場合に合格します。

1. ルート要素に言語を設定します：<html lang="en">。
2. 異なる言語の要素にはlangを使用します：<blockquote lang="fr">。

確認方法：curl -sf https://example.com/ | grep -oE '<html[^>]* lang="[A-Za-z-]+"'

3.7 内容がわかるリンクテキスト

サンプルされたリンクに、「ここをクリック」、「続きを読む」、「詳細はこちら」、「ここ」、「もっと見る」、「詳細」、「情報」などの一般的なテキストが使われていない場合に合格します。

1. 一般的なテキストを、リンク先がわかるテキストに置き換えます。

   <a href="/pricing">See the pricing plans</a>
   <a href="/blog/sprints" aria-label="Read the sprint planning guide">Read more</a>
   

確認方法：curl -sf https://example.com/ | grep -ciE '>(click here|read more|learn more|here|more)</a>'（0が期待値）

3.9 フォームラベルの適用範囲

表示される各フォームフィールドに、<label for>、フィールドを囲む<label>、aria-label、aria-labelledby、titleまたはplaceholderのいずれかのラベルがある場合に合格します。フィールドのないページでは、このチェックはスキップされます。

1. 各フィールドにラベルを関連付けます。

   <label for="email">Email address</label>
   <input id="email" name="email" type="email">
   

2. 可能な場合は、表示される<label>を使用します。placeholderだけではラベルとして不十分です。

確認方法：読み取り専用のシェルチェックでは合否を判定できません。再スキャンコマンドを使用してください。

3.10 フォームフィールドのオートコンプリート

テキスト、メール、電話番号、URL、パスワード、検索フィールドの80％以上にautocomplete属性がある場合に合格します。40％以上で部分点が得られます。

1. 各フィールドに適切なトークンを追加します。

   <input name="name" autocomplete="name">
   <input name="email" type="email" autocomplete="email">
   <input name="phone" type="tel" autocomplete="tel">
   <input name="password" type="password" autocomplete="current-password">
   

確認方法：curl -sf https://example.com/ | grep -oE '<input[^>]*type="(text|email|tel|url|password)"[^>]*>' | grep -vc 'autocomplete='（0が期待値）

3.11 キーボード操作

正のtabindexがなく、ロールとフォーカスのないクリック可能な<div>がなく、ロールのない<div>または<span>にイベントハンドラーがない場合に合格します。

1. 正のtabindex値を削除します。tabindex="0"または自然な順序を使用します。
2. クリック対象にはネイティブのコントロールを使用します。

    <div onclick="openMenu()">Menu</div>
      <button type="button" onclick="openMenu()">Menu</button>
   

確認方法：curl -sf https://example.com/ | grep -cE 'tabindex="[1-9]'（0が期待値）

3.12 ドキュメントのタイトル

<title> があり、汎用的なタイトル（「Home」「Untitled」など）ではなく、10～70 文字の場合に合格します。

1. ページのトピックとブランドを含む、一意のタイトルを各ページに設定します：

   <title>Pricing plans for teams | Planner Pro</title>
   

確認：curl -sf https://example.com/ | grep -oE '<title>[^<]*</title>'

3.13 ボタンのアクセシブルな名前

各 <button>、input ボタン、[role="button"] に、テキスト、aria-label、aria-labelledby、title または value による名前がある場合に合格します。

1. アイコンボタンにテキストまたは aria-label を追加します：

   <button type="button" aria-label="Close dialog"><svg aria-hidden="true">...</svg></button>
   <input type="submit" value="Send message">
   

確認：読み取り専用のシェルチェックでは合否を判定できません。再スキャンコマンドを使用してください。

3.14 aria-hidden の誤用

aria-hidden="true" が <body> に設定されておらず、リンク、ボタン、入力欄を含むコンテナーにも設定されていない場合に合格します。<body> の aria-hidden は不合格です。

1. <body> およびフォーカス可能な要素を含むコンテナーから aria-hidden を削除します。
2. 非アクティブなコンテンツを非表示にするには、hidden または inert を使用します。これらの属性はフォーカスも無効にします：

   <div id="old-panel" inert>...</div>
   

確認：curl -sf https://example.com/ | grep -c '<body[^>]*aria-hidden="true"'（期待値は 0）

3.15 動的ウィジェットの状態

サーバーの HTML にウィジェットまたはライブリージョンがある場合に適用されます。各ウィジェットが状態を公開し、更新が通知される場合に合格します。

1. 開閉要素、タブ、切り替えボタン、および現在の項目の状態を公開します：

   <button aria-expanded="false" aria-controls="faq-1">Can I cancel?</button>
   <div id="faq-1" hidden>Yes, at any time.</div>
   
   <div role="tablist">
     <button role="tab" aria-selected="true" aria-controls="tab-1">Monthly</button>
   </div>
   <p role="status" aria-live="polite">3 results</p>
   

2. 表示を変更するスクリプトと同じスクリプトで aria-expanded と aria-selected を更新します。

確認：curl -sf https://example.com/ | grep -oE 'aria-(expanded|selected|checked|pressed|current|live)=' | sort | uniq -c

主な注意点

1. 各コンポーネントが独自の <h1> を追加するため、ページに複数の <h1> が存在します。
2. alt のない <img src="..."> は不合格です。装飾用の場合は alt="" が正しい設定です。
3. <div id="root"></div> のシェルには、エージェントが読み取れるテキストがありません。
4. モーダルを含む背景要素に aria-hidden="true" を設定すると、モーダルが非表示になります。
5. JavaScript の切り替え処理で表示は変わっても、aria-expanded が更新されません。

正しい例と誤った例については、references/gotchas.md を参照してください。

参考資料

• references/checkpoints.md：各チェックポイントの生成済みチェックポイントデータ
• references/semantic-html-guide.md：セマンティック要素、ARIA マッピング、見出しとリンクテキストのパターン
• references/ssr-strategies.md：各フレームワークの SSR
• references/gotchas.md：正しい例と誤った例を含む、よくあるエラー