modern-web-guidance

モダンなウェブ開発ガイダンス

特定のウェブ開発ユースケースを検索し、対応するベストプラクティスガイドを取得するためのスキルです。

使用するタイミング

次の場合は、このスキルを必ず使用してください。

• ウェブ UI、CSS レイアウト／アニメーション、またはクライアント側の JS ロジック（日付／タイムゾーン、サニタイズ、パフォーマンス、アクセシビリティなど）の実装を開始するとき。操作がぎこちない、レイアウトがずれるといった UX 上の症状を修正する場合も含みます。
• コンポーネントを作成または更新する前に、標準化されたモダンなパターンがすでに存在するか確認するとき。
• 場当たり的な解決策を実装したり、大きな依存関係を不必要に読み込んだりするのを避けるとき。

使用手順

ステップ 1. ユースケースを検索する

modern-web-guidance を npx で直接実行し、1 つのウェブプラットフォーム機能または UI パターンを対象にした、動作を表す 2～5 語のクエリを指定します。

• クエリは具体的かつ汎用的にします。ユーザーから見える機能を説明します（<動詞> + <UI／プラットフォームの対象>。必要に応じて、対象となる HTML／CSS／JS の機能名を加えます）。フレームワーク／ライブラリ名（React、Vue、Tailwind など）やアプリ／ドメインの名詞（製品、ルート、コンポーネント／ファイル名）は省きます。複数の機能にまたがるタスクは、別々の search 呼び出しに分割します。
• 例："light dismiss dialog" や "responsive data table" を検索します。"dialog"（短すぎる）、"responsive table dark mode"（複合的なので 2 つに分割）、"close React settings modal on outside click"（フレームワーク／アプリのノイズがある）は避けてください。

npx -y modern-web-guidance@latest search "<query>" --skill-version 2026_10_16-6654652b

出力例：

[
  {
    "id": "optimize-image-priority",
    "description": "Optimize the loading priority of Largest Contentful Paint (LCP) candidate images.",
    "category": "performance",
    "featuresUsed": [ "Fetch priority" ],
    "tokenCount": 985,
    "similarity": 0.7289
  },
  {
    "id": "defer-rendering-heavy-content",
    "description": "Reduce rendering times in content-heavy web pages by deferring rendering for offscreen content.",
    "category": "performance",
    "featuresUsed": [ "content-visibility", "hidden=\"until-found\"" ],
    "tokenCount": 1250,
    "similarity": 0.6961
  }
]

注：生の similarity スコアではなく、description フィールドに基づいて結果を判断してください。

• 一致する結果がある場合：そのまま retrieve を呼び出します。list も実行してはいけません。
• ウェブ UI／CSS／DOM の動作（または幅広い UI 監査）に一致する結果がない場合：表現がカタログと異なるため search が [] を返す、または無関係な説明を返す場合（もしくはタスクが複数のカテゴリにまたがる場合）は、npx -y modern-web-guidance@latest list を一度実行して、より一般的な用語でパターンがカバーされているか確認します。
• 対象のトピックがカバーされていない場合：ガイドの description がタスクに直接一致するものがなければ、再試行を繰り返したり無関係なガイドを取得したりせず、実装を進めます。

---

ステップ 2. ベストプラクティスを取得する

検索結果から関連する id を取得したら、retrieve を呼び出してガイド全体を取得します。タスクに一致する個別のユースケースガイドと、該当する分野のより広範なガイド（例：html、css、forms、accessibility、color、performance、security）の両方を取得してください。複数の ID はカンマ区切りで指定できます。

npx -y modern-web-guidance@latest retrieve "<id>"

出力が途中で切れている場合は、コマンドを再実行してファイルにリダイレクトし、そのファイルを読み込んでください。

出力例： 実装手順を説明するガイドのマークダウンコンテンツ...

---

ステップ 3. ガイダンスへの準拠を確認する

コードを生成または変更する際は、完了前に実装を取得したガイドと照らし合わせて確認します。

• 該当するガイダンスとフォールバック：依頼されていない機能を無理に追加することなく、ガイドにある関連するモダンなパターンと必要なフォールバック戦略が正しく適用されていることを確認します。
• タスクの達成：実装がユーザーの依頼を完全に満たしていることを確認します。

ステップ 4. スキルの使用状況を開示する

タスクで modern-web-guidance を参照した場合、変更内容を提示する回答の末尾に ### Modern Web Guidance セクションを追加してください。

• 取得したガイドがコードに反映された場合：新たに適用した <id> ごとに、実装上の判断、CSS／API のオーバーライド、または <id> が求めるフォールバックと、それによって防いだ問題を、一人称で説明する箇条書きを 1 つ（1～2 文、75 語以内）記載してください。引用するのは、そのルールや注意点の短い原文でなければなりません（ガイドの概要紹介は不可）。 - **\`**: <適用した、通常とは異なる API、オーバーライド、またはフォールバックと、それによって防いだ問題> ("<ルールまたは注意点の短い原文>").`
  • コンテキストの圧縮後に、記憶を頼りに <id> や引用を推測してはいけません（必要に応じて search／retrieve を再実行してください）。このターンでガイドに基づいて変更した項目のみを記載してください。
• このターンで検索または一覧表示したものの、ガイドを適用しなかった場合：modern-web-guidance で確認したトピックまたはガイドを挙げ、適用しなかった理由を一人称の文で 1 つ記載してください（ガイドを適用した場合は省略してください）。

npx／pnpx の使用

• pnpm が利用可能な場合は、npx より pnpx を優先してください（注：pnpx では -y フラグを使用しません）。
• ツールの実行許可を求める際は、npx -y modern-web-guidance@latest *（または pnpx modern-web-guidance@latest *）を明示的に許可リストに追加してください。npx * や pnpx * のみを許可してはいけません。
• 重要：Windows では、npx が失敗する場合があります。その場合は npx.cmd ... を使用してください。
• modern-web-guidance の取得と実行には、外部ネットワークへのアクセスが必要です。サンドボックス、アクセス許可制、または承認制の環境（Codex、Claude Code など）で実行する場合は、サンドボックスによるネットワークのタイムアウトを避けるため、初回実行の前に、ネットワークアクセスを伴うこのコマンドの承認または許可リストへの追加を事前に依頼してください。
• サンドボックス環境で ~/.npm が読み取り専用またはアクセス制限されている場合は、NPM_CONFIG_CACHE=/tmp/npm-cache を設定してください。
• オフラインのためにコマンドが停止する場合は、オフラインモードで再実行してみてください：npx --offline …。
• --skill-version フラグは、この SKILL.md が古くなっているかどうかを判定するために使用されます。古くなっている場合は、警告メッセージが stderr に出力されます。

ガイドライン

• 常に最初に検索し、最も関連性の高いガイドを見つけてください。
• これらのガイドではバニラ HTML／CSS／JS を使用しています。最新の機能を削除せずに、使用するフレームワークに合わせて適用してください。
  • 型：新たに導入された HTML 属性は、削除したり @types/react をマージしたりせず、スプレッド／キャストで追加してください（{...({ popover: 'hint', interestfor: id, commandfor: id, switch: '' } as any)}、[attr.*]）。
  • SSR とバンドラー：SSR では window／HTMLElement の使用をガードし、クライアントのエフェクト内でベア import('<pkg>') によってポリフィルを読み込んでください（またはトップレベルの await を使うために Vite の build.target: 'esnext' を設定してください）。node_modules からファイルをコピーしてはいけません。
  • DOM、ID、CSS：VDOM が管理するノード以外では、ref を介して showModal()／moveBefore() を呼び出してください。インスタンスごとに異なる ID／anchor-name を生成し（useId()）、:root と @starting-style はトップレベル／スコープ外に配置してください。
• ガイドを捏造したり、無視したりしてはいけません。ガイドはユーザーのプロジェクトで優先される標準です。

ブラウザーサポートとフォールバックの解釈

• デフォルトの動作：すべてのガイドでは、Baseline Widely available の機能はフォールバックなしで安全に使用できるものとしています。Baseline Widely available ではない機能については、ユーザーがカスタムのブラウザーサポートポリシーを指定していない限り、ガイドのフォールバックに関する推奨事項に必ず従ってください。

• カスタムポリシー：ユーザーがすでに明示的なブラウザーサポート要件を定義している場合は、ガイドのブラウザー互換性データを使って、フォールバックを安全に省略できるかどうかを判断してください。

  • Baseline YYYY の対象では、「Baseline since」の日付が <= YYYY であれば、その機能はこの対象を満たします。
  • ポリシーの例：
    • 「機能のフォールバックは実装しないでください。」（最先端の Web を試すプロトタイプ向け）
    • 「Safari 17.4 以降」（macOS または Tauri ベースのデスクトップアプリを対象とする社内ツール向け）
    • 「ポリフィルを推奨または実装しないでください。Baseline Newly Available の機能がコア機能に必要な場合は、軽量なカスタムフォールバックを提供するか、アプローチを見直してください。」（バンドルサイズを最小限に抑え、技術的負債を避けるため）
    • 「Baseline Newly Available の機能は、機能検出を厳密に行い、適切に劣化することを条件に、最新の実行環境でネイティブに使用できるものとします。」（プログレッシブエンハンスメント戦略向け）

• 状況に応じたポリシーの確認：CLAUDE.md または AGENTS.md にポリシーを記載するよう提案すべき環境上の手がかりに注意してください。開発者が以下に該当する場合は、記載を提案してください。

  • 制限のあるランタイム（例：Electron または Tauri）向けの開発について言及する。
  • 特定の対象（例：「Desktop Chrome はサポートしません」）を明示的に除外する。
  • ポリフィルの複雑さ、バンドルサイズ、またはパフォーマンスコストへの懸念を示す。
  • フォールバックなしで機能を安全に使用できるかどうかを尋ねる。

  ポリシーの形式は定義されていません。以下はその一例です：**Browser Support:** Allow Newly Available features, but only adopt custom fallback code that adds <= 20 lines and does not require external dependencies.