thecatthatflies/content-site-design

コンテンツサイトのデザイン

コンテンツサイトは、読者がページを見つけ、それが求めるページであることを確認し、目的の答えや理解を得て、次の行動に移るために存在します。ほとんどの読者は検索から詳細ページに直接アクセスし、読む前にスキャンし、必要なものが得られればすぐに離脱します。モデルが間違える最も一般的な方法は、シェル（ヒーロー、カード、サイドバー、ダークモード切り替え）を設計して、コンテンツ自体の構造（曖昧なタイトル、何も言っていない見出し（「概要」「はじめに」）、3段落下にようやく現れる答え、チュートリアル・リファレンス・意見が混在したページ、「こちら」のようなリンクテキスト、日付の欠如、役に立たないサイト内検索）を軽視することです。

interface-guidelinesの優先順位付けされた原則を適用します（誰でも使える > 真実を伝える > 意味を伝える > 答えが最初 > ミスは生存可能 > そのまま動く > 可能なことが見える > 慣習 > 洗練）。そのスキルがインストールされている場合は、最初にそのSKILL.mdを読んでください。ボディタイプのサイズ、行長、コントラスト、リフローについてはそちら（references/human-interface.md セクション6および7）に記載されています。このスキルは、コンテンツ構造、ナビゲーション、検索、およびエージェントリーダーをカバーします。

概要

• サイトの種類: ドキュメント、ヘルプセンター、ナレッジベース、編集/ブログ、またはこれらを組み合わせたもの。複合サイトでは、セクションごとに主要なジョブを指定します。
• 読者とそのアクセス方法: 検索から詳細ページへ、プロダクト内から（「？」リンク）、ブラウジング、購読。誰が初心者で誰がエキスパートか？
• トップタスク: 読者が持つ10〜20の質問を、彼らの言葉で表現します。検索ログ、サポートチケット、フォーラムの投稿から取得し、組織図からは取得しません。
• コンテンツタイプ: ドキュメントの場合、チュートリアル、ハウツー、リファレンス、解説のどれか。編集系の場合、ニュース、分析、意見、ガイドのどれか。
• 鮮度: コンテンツの更新頻度、各ページの所有者、プロダクトバージョン変更時の対応。
• エージェントリーダー: ドキュメントを読むコーディングエージェント、ページを引用する検索・回答エンジン、ナビゲートするブラウザエージェント。彼らは何を正しく行わなければならないか？
• 執筆者: スタッフのみか、ユーザー（コメント、コミュニティ回答）も許可するか？外部の執筆者によるコンテンツを明示する。

ルール

タグ: [E] 実証的、[S] 標準または制度的、[P] 実践者、[J] 判断。ソースはリファレンスファイルにあります。

ページ

• 答えを最初に。 最初の2つの段落で主要なポイントを伝え、詳細は重要度の高い順に続けます（逆ピラミッド）[S: GOV.UK; P: NN/g]。読者はページのごく一部の単語しか読みません。Nielsenの推定では約20〜28％です[P: Nielsen 2008, Weinreich et al. 2008のデータに基づく]。
• 1ページ1ジョブ。 チュートリアルは教え、ハウツーガイドは指示し、リファレンスは説明し、解説は議論します。1つのページでこれらを混在させてはいけません[P: Procida, Diátaxis]。
• タイトルは一意で、具体的で、重要な情報を前に置き、 読者の言葉で、65文字以内に収め、検索結果で切れないようにします[S: GOV.UK]。タスクページは動詞で始めます（「APIキーをローテートする」）。タスクに関するガイダンスは動名詞形を使用します（「APIキーのローテート」）[S: GOV.UK]。
• タイトルの下に1文の要約を 160文字以内で、タイトルに欠けている言葉を補います。同じテキストをメタディスクリプションとしても使用します[S: GOV.UK]。
• 見出しはそのセクションの内容を表し、 重要な情報を前に置き、「概要」や「詳細情報」ではなく、疑問文でもありません。見出しを削除してもコンテンツが意味をなすようにします[S: GOV.UK]。見出しレベルは構造に従います。h1は1つ、レベルをスキップしない[S: WCAG 1.3.1, 2.4.6]。
• 短い文と段落、平易な言葉。 約25語を超える文は分割し、段落は5文以内に抑え、専門用語は最初の使用時に説明します[S: GOV.UK]。読者を「あなた」と呼び、能動態を使用し、条件を指示の前に置きます（「プロジェクトを削除するには、設定を開きます」）[S: Google デベロッパー スタイル ガイド]。
• 手順には番号付きリスト、集合には箇条書き、比較には表を 使用します[S: Google デベロッパー スタイル ガイド; GOV.UK]。
• スキャンしやすくフォーマットする: 意味のある見出しと情報を前に置いた段落は、読者がページの右側や下部をスキップするF字型スキャンに対抗します[P: Pernice, NN/g 2017]。
• 意味のある日付: 「最終更新: 2026年11月4日」と、実質的な変更に対する短い変更メモ、記事には公開日を記載します。古いページで正確なものは「レビュー済み」と表示します[S: GOV.UK 変更メモ; J]。
• 脚注: GOV.UKはサービスコンテンツでの使用を禁止しています。学術的で長文の編集記事では必要な場合があります。読者がソースを検証する必要があるかどうかで判断します[S: GOV.UK; J]。

リンク

• リンクテキストはリンク先を明示し、 重要な情報を前に置き、ページ上のリンク先ごとに一意にします。「ここをクリック」「続きを読む」「こちら」は決して使用しません[S: GOV.UK, WCAG 2.4.4]。
• リンクがサイト外に出る場合、ファイルを開く場合、言語が変わる場合 を明記します：「料金表 (PDF, 240 KB)」[S: GOV.UK]。
• リンクは役立つ場所に配置し、 「参考文献」として下部にまとめない。タスクページの最後に具体的な次のステップを置くのは構いません[S: GOV.UK]。
• すべての見出しは安定したアンカーを持ち (#rotate-a-key)、コピーリンク用の可視コントロールを備えます。見出しの名前を変更しても、古いアンカーは機能し続けます[J]。
• URLは読みやすく、永続的です。 ページが移動した場合は古いURLをリダイレクトし、ドキュメントのリンクが404にならないようにします[J]。

ナビゲーション

• 読者は詳細ページに直接アクセスします。 すべてのページは、現在地（パンくずリストまたはハイライトされたセクション）と、次に何があるか、近くに何があるかを表示します[S: WCAG 2.4.8; P: NN/g パンくずリスト]。
• ナビゲーションラベルは読者の言葉を使用し、その内容を予測させます（情報のにおい）[E: Pirolli and Card 1999]。
• ページに到達する少なくとも2つの方法: ナビゲーションと検索、またはサイトマップ[S: WCAG 2.4.5]。
• 長いページにはページ内目次 を、h2とh3から生成し、現在のセクションをハイライトします[J]。
• アーカイブや検索結果には、無限スクロールではなくページネーションまたは「さらに読み込む」 を使用し、読者がフッターに到達し、場所に戻り、位置を共有できるようにします[P: NN/g 無限スクロール]。
• ドキュメント: 読者のタスクとDiátaxisタイプで整理された1つのサイドバー、バージョンが異なる場合は可視のバージョンスイッチャー、古いバージョンのページには現在のページへのリンクを含むバナーを表示します[P: Procida; J]。

検索

• 検索は主要な経路であり、付加機能ではありません。検索ボックスはすべてのページで可視であり、デスクトップではアイコンの背後に隠してはいけません[P: NN/g; J]。
• 結果には、ページタイトル、そのセクションまたはタイプ、一致した単語を含むスニペット、日付を表示します。実際のクエリからのタイプミスや同義語を許容します[J]。
• 結果なしのページは、スペル修正、より広い用語、トップページを提案し、クエリをログに記録します[J]。
• ゼロ結果とトップクエリを毎月レビューします。それぞれが見つからないページ、見つからない同義語、または悪いタイトルを示しています[P: 一般的なドキュメントの慣行; J]。

読書の快適さ

• ボディタイプ、字間、行間、コントラスト、リフローは基本に従います。携帯電話では、読者は短くシンプルなテキストをデスクトップ同様に理解しますが、難しいテキストでは速度が落ちるため、難しいコンテンツはモバイルで追加の構造が必要です[P: Moran, NN/g 2016]。
• テキストを覆うインタースティシャルや固定要素は禁止。広告やニュースレターのプロンプトが回答の最初の画面を妨げてはいけません[S: WCAG 2.4.11 フォーカス用; J]。
• 情報を伝える画像には、その情報を述べる代替テキストがあります。装飾的な画像には空の代替テキストがあります[S: WCAG 1.1.1]。図には近くにテキストによる説明があります[J]。
• コードサンプルはテキストであり、画像では決してありません。コピーコントロールと言語ラベルが付いています。言語バリアントのタブは、すべてのバリアントをDOM内に保持します[J]。
• 印刷モードとリーダーモードでは、ナビゲーションチャームなしでコンテンツを生成します[J]。

エージェント向け

• コンテンツはHTML内にあり、 サーバーサイドでレンダリングされ、クライアントJavaScriptによってロード後に組み立てられることはありません。これにより、スクリプトを実行しないクローラーやエージェントがコンテンツを取得できます[J]。
• セマンティック構造がインターフェースです: 見出し、リスト、テーブル、言語クラスを持つcodeとpre、figureとfigcaption[S: WCAG 1.3.1]。
• 安定した、引用可能なURLとアンカー、 ページごとの正規URL、およびページ内の日付[J]。
• 各ドキュメントページのクリーンなMarkdownコピー を同じURLに.mdを追加して作成し、rel="alternate" type="text/markdown"でリンクすることは、コーディングエージェントにチャームなしでコンテンツを提供する安価な方法です。サイトまたはドキュメントルートのllms.txtはコミュニティの提案です。一般的なサイトでは需要は低いと測定されていますが、コーディングエージェントが読むドキュメントには適しています[P: Howard, llms.txt; foundation agent-surfaces section 6]。
• エージェント向けの隠し指示 をページテキスト、コメント、非表示要素に含めてはいけません。これらはプロンプトインジェクションと区別がつきません[J; foundation oversight section 5]。
• ユーザー生成コンテンツ（コメント、コミュニティ回答、フォーラム投稿）は、マークアップと視覚的にその旨を明示し、作成者と日付を添えることで、エージェントと人間がその重みを評価できるようにします[J]。

ビルド順序

1. トップタスクとコンテンツインベントリ: 既存または計画中の各ページについて、そのタイプ、所有者、最終レビュー日、提供するタスクを記録します。タスクを提供しないページは削除または統合します。
2. 情報アーキテクチャ: 読者のタスクとコンテンツタイプからセクションを作成。読者の言葉でラベル付けします。ツリーテストでラベルをテストします（人がテキストのみのツリーで5つのタスクを見つけられるか）[P: NN/g ツリーテスト]。
3. コンテンツタイプごとのページテンプレート: タイトル、要約、日付、本文構造、次のステップ。ドキュメントの場合: チュートリアル、ハウツー、リファレンス、解説のテンプレート（references/docs.md）。
4. 最初にトップタスクページを書くまたは書き直す（references/writing.mdを使用）。20のスタブページよりも、1つの完全で質の高いページの方が優れています。
5. セマンティックHTMLシェル: ランドマーク、スキップリンク、パンくずリスト、aria-currentを持つnavとしてのサイドバー、ページ内目次、フッター。サーバーサイドレンダリング。
6. 検索: ログまたはトップタスクリストからの実際のクエリを使用。同義語をチューニングします。
7. エージェントレイヤー: 正規URL、アンカー、Markdownコピー、サイトマップ、オプションのllms.txt。
8. 長時間の読書向けのスタイル: ブランドが外観を所有します（brand-identity）。
9. 検証（下記）。

検証

1. レンダリング監査 をホームページ、長い記事またはリファレンスページ、検索結果ページ、404ページで実行します:

   node <interface-guidelines>/scripts/audit.mjs <dist-or-url> --out audit-output
   

2. トップタスクテスト: 各トップタスクについて、検索エンジンのクエリまたはホームページから開始し、回答に到達します。ステップ数をカウントし、情報のにおいが途切れた箇所を記録します。キーボードで電話幅で人間として1回、アクセシビリティスナップショットのみでエージェントとして1回実行します。

3. コンテンツリンター をすべてのページで実行します（references/writing.md セクション8にスクリプトの概要があります）: h1が1つであること。見出しレベルのスキップがないこと。タイトルが一意で65文字以内であること。要約が存在し160文字以内であること。一般的な見出しやリンクテキストがないこと（「概要」「ここをクリック」「続きを読む」）。25語を超える文にフラグが立てられていること。alt属性がない画像。最終更新日が存在すること。

4. リンク: 壊れた内部リンクと欠落したアンカーをクロールします。古いURLがリダイレクトされていることを確認します。

5. No-JSチェック: curlでページを取得し、メインコンテンツと見出しがHTML内にあることを確認します。

6. 検索: 上位20のクエリと5つのスペルミスクエリを実行します。適切なページが上位3位以内にあることを確認します。

7. エージェント読み取り: エージェントにドキュメントページのURLまたはその.mdコピーのみを与え、タスクを実行するように依頼します。現在のバージョンに従い、正しいセクションアンカーを引用していることを確認します。

落とし穴

• 記事のティーザーのカードグリッドをドキュメントのホームページとして使い、タスクエントリポイントや検索がない。
• 「はじめに」「概要」「詳細」という名前の見出し、または疑問文で書かれた見出し。
• 無関係な質問を集めたFAQページ。代わりに、質問が発生するページで回答する。
• トピックの重要性についての長い前文の下にある回答。
• 途中でリファレンスに変わるチュートリアル、または意見で水増しされたリファレンス。
• 日付のない記事、およびすべてのページの「最終更新日」がビルド日に設定されている。
• クライアントJavaScriptによってのみレンダリングされるコンテンツ、非表示パネルがDOMにないタブ、コードのスクリーンショット。
• アーカイブと検索結果での無限スクロール。
• ページに隠されたAIクローラー向けの指示テキスト。
• タイトル、見出し、検索が壊れたままドキュメントサイトを再スタイリングする。

リファレンス

ファイル	これを使用するタイミング
references/writing.md	ページの作成または編集時: タイトル、要約、見出し、文、リンク、日付、数字、編集上の詳細、リンターの概要
references/docs.md	ドキュメントとヘルプセンター: テンプレート付きのDiátaxisタイプ、API参照ページ、コードサンプル、バージョン、チェンジログ、コーディングエージェント向けドキュメント
references/navigation-search.md	サイト構造、ラベル、サイドバー、パンくずリスト、目次、アーカイブ、検索結果、404