SEO・アクセシビリティ・演出を同時に満たす品質ゲート

SEO、アクセシビリティ、演出を別工程にすると、最後に衝突します。見出しをアニメーション用のdivへ変えた後でsemantic HTMLへ戻す、Canvasへ入れた情報をスクリーンリーダー向けに書き直す、といった手戻りが起きます。

三つを同時に満たす近道は、スコアを一つにすることではありません。同じ主要フローを、複数の観点で通過させる品質ゲートを作ることです。

品質ゲートのhard failureとwarning

hard failure：直すまで公開判定にしない

• routeのHTMLが生成され、h1が主題を示している。
• canonical、title、description、OGP、Twitter Card、JSON-LDが本文と一致している。
• 内部リンク、sitemap、RSS、robots、画像パスが生成物から解決できる。
• JS無効時も本文、見出し、主要リンク、FAQ、図のHTML代替が読める。
• キーボードで操作でき、focusが見え、320pxで二方向スクロールがない。
• dist/とupload/のファイル内容が一致している。
• 秘密情報、未確認の実績、架空の数値が差分へ入っていない。

warning：記録してから判断する

• 外部URLのTLS、cache、compression、security headersがこの環境から確認できない。
• npm auditがCA証明書エラーなどで取得できない。
• Search Console、Lighthouse、SNS crawlerの実環境確認をまだしていない。
• axeの自動検出外にある文脈、読み上げ順、操作の分かりやすさを人手で未確認。

warningは0件と書き換えず、取得不能・未確認として残します。npm auditで証明書検証を無効にしたり、strict-ssl=falseへ逃がしたりしないことも品質ゲートの一部です。

semantic HTMLを共通の基盤にする

検索エンジンと支援技術は目的が違いますが、文書の主題、見出し、ナビゲーション、本文がHTMLとして明確であることは両方に効きます。

• ページごとに一つの主題を持つh1。
• セクションの関係を表すh2とh3。
• サイト移動はnav、本文はmain、補足はaside。
• 操作はbutton、移動はa。
• 比較はtable、用語と値はdescription list。

見た目のために要素を選ばず、CSSで見た目を変えます。divへrole=buttonを足すより、最初からbuttonを使う方がキーボードと状態を保ちやすくなります。

headingとfocusを視覚設計へ含める

大きな見出しはブランド表現であると同時に、文書の入口です。日本語タイトルがモバイルで一文字ずつ分断されない幅、本文が一行70文字前後を超えないmeasure、200%拡大時のreflowを確認します。

focus ringは後付けの枠ではありません。NightテーマとPaperテーマの両方で背景から見える色をトークン化し、sticky headerの裏へフォーカス対象が隠れないscroll-padding-topも設定します。

ダイアログでは次を確認します。

1. 開いたとき検索欄へフォーカスする。
2. Tabがダイアログ内を移動する。
3. Escで閉じる。
4. 閉じた後、開いたボタンへ戻す。

Command Paletteは便利でも、通常ナビゲーションの代わりにはしません。JavaScriptがなければ使えない入口だけを作らないためです。

structured dataは画面の内容と一致させる

Article structured dataには、画面に存在するtitle、description、公開日、更新日を使います。架空の組織、著者資格、評価、レビューを足しません。

品質ゲートでは、JSON-LDの構文だけでなく次を見ます。

• headlineがH1と同じ主題か。
• datePublishedとdateModifiedが記事metaと一致するか。
• canonicalが本番URL一種類か。
• draftがsitemap、RSS、記事一覧から除外されるか。
• BreadcrumbListの順序と実際の導線が一致するか。

構造化データはランキングを約束する装飾ではなく、ページの内容を別形式で矛盾なく表すものです。

AI検索で意味を失わない確認

AI検索向けの別ページや専用ファイルを先に増やすのではなく、通常のHTMLだけで「問い → 結論 → 条件 → 根拠 → 次の行動」が追えるかを確認します。Google Search CentralのAI features and your websiteと生成AI機能の最適化ガイドに合わせ、特別な記法や引用順位を約束せず、検索に必要な通常の品質を保ちます。

• H1と冒頭の段落で、誰のどの判断を助けるページかを言い切る。
• 用語、対象範囲、条件、例外を同じ本文の近くに置き、断片だけでも意味が変わらないようにする。
• Projectデータ、確認日、Git履歴、外部資料などの根拠を、主張の直後からたどれるようにする。
• 数値や判断が変わるときは、公開日と更新日、集計日、サンプル規模を分けて記録する。
• 読了後の行動を、関連Note・Pattern・Project・Simulatorの既存ルートへ一つだけ渡す。

Claim-to-evidence recordを作る

AI検索や人手レビューで文脈が切れても、主張の意味と限界が残る最小記録を、ページ単位で作ります。BUILD ORBITでは次の5欄を使います。

たとえばAstro静的サイトの判断Noteは、HTMLへ残す情報とIslandへ切り出す状態を分け、Local AI Compassのケーススタディで実例へ戻します。これはAI回答への掲載や引用を約束する記法ではなく、元ページだけを読んでも過剰な一般化をしにくくする編集基準です。

JavaScript無効時を設計レビューに使う

no-JS確認は、古い環境だけのためではありません。情報と機能の境界が正しいかを見る強いテストです。

JavaScriptを無効にしたとき、次が読めれば基盤は残っています。

• サイトの目的と主要導線。
• Projectの概要一覧。
• 記事本文と関連記事。
• Simulatorが扱う条件と基本方針。
• プライバシーと外部リンク。

診断の再計算やCommand Paletteのような機能は止まって構いません。ただし、その事実と代替経路をnoscriptで伝えます。

performance budgetを機能要件として書く

「できれば速く」では削減判断ができません。初期JavaScript gzip 180KB以内、LCP 2.5秒未満を目標、CLS 0.1未満など、測定条件と一緒に予算を置きます。

予算を超えたときは、次の順で直します。

1. bundleや画像から原因を測る。
2. 不要な依存や重複コードを削る。
3. 画面下のIslandを遅延読込する。
4. SVGやCSSなど軽い代替表現へ変える。
5. 効果の密度を段階的に下げる。

機能を無条件に削ってLighthouseだけ上げるのではなく、同じ目的を軽い表現で達成できるか検討します。

自動・ブラウザ・人手の担当を分ける

AIコーディングの出力は、同じ種類の「確認済み」へまとめません。再現可能なsource/build検証、実行環境でのbrowser検証、意味を読むhuman reviewに分けます。

自動化しやすいものは、毎回同じ基準で止めます。

ブラウザでは、直接URL、戻る・進む、共有状態、キーボード、主要viewport、reduced motion、no-JSを実際の生成物で確認します。axeはこの層で機械検出できる違反を減らします。

人手で残すものもあります。

• 見出しを順に読んで主題が伝わるか。
• キーボードだけで主要フローを完了できるか。
• 320px、390px、landscapeで情報が欠けないか。
• 200%拡大で固定要素が重ならないか。
• NightとPaperのコントラストが実際に読みやすいか。
• Motion Offで操作結果が分かるか。

BUILD ORBITで実行できる確認群は、次の順に分けています。長い一括コマンドで最後の失敗だけを読むのではなく、どの層で止まったかを残します。

npm run format:check
npm run lint
npm run typecheck
npm run check:content
npm run test
npm run build
npm run check:og
npm run check:seo
npm run check:dist
npm run test:routes
npm run check:links
npm run prepare:upload
npm run check:delivery
npm run test:e2e
npm run test:a11y

Playwrightとaxeは自動検出できる問題を減らすための道具で、axeが通ったことだけでアクセシビリティ全体を証明しません。320px、390px、200% zoom、reduced motion、キーボード、no-JSは人が意味と連続性を確認します。実装を再利用するPatternは静的な本体に操作だけを重ねる設計、検証工程全体はMethodへ接続します。構成ごとのgate候補はBuild Simulatorで整理できます。

axeで問題がないことは、使いやすさの証明ではありません。自動検出が得意な問題を先に減らし、人は意味と連続性を確認します。

リリース前ゲート

次の順で一つでも失敗したら公開作業を止めます。

1. content schemaと関連slugが正しい。
2. format、lint、strict typecheck、unitが成功。
3. build後の全主要routeが存在。
4. 内部リンク、canonical、OG、sitemap、RSSが一致。
5. キーボード、reduced motion、no-JSを手動確認。
6. 代表ページをaxeと主要breakpointで確認。
7. distとuploadが一致。
8. diffとcommit対象に秘密情報がない。

このNoteは検証責任の分担をownerとします。実際に公開するかをbuildからrollbackまで順に決めるときはAIサイトの公開前チェックリストへ進みます。

SEO、アクセシビリティ、演出は、奪い合う予算ではありません。semantic HTMLを本体にし、動きを意味へ限定し、生成物まで検証すれば、同じ設計判断が三つの品質を同時に支えます。

よくある質問