AIに「モダンなコードの書き方」を教えるModern Web Guidance
X-tech推進本部 倉原AI駆動開発が普及し、フロントエンドの実装をAIエージェントに任せる場面が増えてきました。ところが、エージェントが書くHTML/CSS/JavaScriptには、古い書き方が混ざることがあります。AIはWeb上に蓄積された過去のコードからも学習しているため、現在はより適切な実装方法がある場合でも、古い実装パターンを提案することがあります。
こうした問題に向けて、GoogleはAIエージェントにモダンな書き方を教えるためのModern Web Guidanceを公開しています。本記事では、その概要と、モーダルの実装をモダンな書き方へ変更する例を紹介します。
Modern Web Guidanceとは
Modern Web Guidanceは、Claude CodeなどのAIエージェントに追加して使うAIスキルです。中身はWebの実装パターンごとにまとめたガイド集で、2026年11月13日に確認した時点では約200本が収録されています。主な分野と、扱っている内容の例は次のとおりです。
| 分野 | 例 |
|---|---|
| UIコンポーネント | ダイアログ、タブ、アコーディオン、カルーセル、トースト |
| UIの動き | View Transitions、スクロール連動アニメーション、ツールチップ |
| CSS | :has()、コンテナクエリ、流体的なサイズ指定 |
| フォーム | 自動入力、カスタマイズできる<select>、バリデーション |
| パフォーマンス | LCP/INP/CLSの改善、読み込み優先度の調整 |
| セキュリティ | パスキー、HTMLのサニタイズ |
| その他 | アクセシビリティ、ダークモード、ブラウザ組み込みAI、WebMCP |
各ガイドには、望ましい書き方だけでなく、やってはいけない書き方や、対応していないブラウザ向けの代替手段も書かれています。AIエージェントはこれらのガイドを参照して、その内容に沿ってコードを書きます。
インストール方法
プロジェクトのフォルダで次のコマンドを実行すると、対話形式でインストールできます。
npx modern-web-guidance@latest install
仕組み
インストール後、AIエージェントは作業内容に合ったガイドを検索して読み込み、その内容に沿ってコードを書きます。このとき使われるのが、次に紹介する3つのコマンドです。いずれもAIエージェントが必要に応じて自動で実行するので、プロンプトでコマンドを指定する必要はありません。
search:ガイドを探す
「何を作りたいか」を指定すると、関係するガイドのidと説明が返ってきます。
npx modern-web-guidance@latest search "modal dialog"
モーダルダイアログについて検索した結果の一部は、次のとおりです。
[
{
"id": "declarative-dialog-popover-control",
"description": "Toggle the visibility of a dialog or popover from a button without writing JavaScript."
},
{
"id": "dialog",
"description": "Build a modal or non-modal dialog component that is accessible, manages focus appropriately, and can be dismissed the way users expect on each platform."
}
]
retrieve:ガイドの本文を読み込む
searchで見つけたidを指定すると、ガイドの本文(Markdown)が返ってきます。カンマ区切りで複数まとめて取得できます。
npx modern-web-guidance@latest retrieve "dialog,light-dismiss-a-dialog"
legacy-scan:古い書き方が残っている箇所を探す
フォルダを指定すると、その中のコードから、新しい書き方に置き換えられる決まったパターンを探します。--jsonを付けると、結果をJSONで受け取れます。
npx modern-web-guidance@latest legacy-scan ./src --json
ただし、legacy-scanがチェックするのはガイドの一部です。2026年11月13日に確認した時点では、約200本のうち33本のガイドに対応する35ルールが対象で、ガイド全体の約2割にあたります。残りのガイドが扱う書き方は見ていないので、検出結果が0件でも、古い書き方が残っていることがあります。
どこまで新しい機能を使うか
モダンな機能の中には、まだ一部のブラウザで使えないものもあります。ガイドはBaselineを基準にしています。Baselineは、Webの機能が主要なブラウザでどの程度利用できるかを把握するための指標です。
- Baseline Widely available(すべての主要ブラウザで使えるようになって2年半以上経過した)の機能は、そのまま使う
- それより新しい機能は、ガイドに書かれた代替手段もあわせて実装する
対応ブラウザの条件はプロジェクトによって異なります。「Safari 17以降に対応」のような条件がある場合は、CLAUDE.mdなどに書いておくと、AIはその条件に照らして代替手段が必要かどうかを判断します。今回の使用例では、CLAUDE.mdに次のように書いています。
## Browser Support
- Baseline: Baseline 2025 を対象とする。
使用例:レガシーな書き方が残ったモーダルを書き換える
ここからは、<dialog>要素で作ったモーダルを例に、Modern Web Guidanceで古い書き方を見つけて書き換えるまでの流れを紹介します。
書き換え前のコード
ダイアログの開閉には、ボタンのcommand属性とcommandfor属性を使用しています。背景側のスクロールはCSSで制御しています。ただし、「ダイアログの外側をクリックしたら閉じる」処理だけは、JavaScriptで書いています。
<button type="button" command="show-modal" commandfor="notice">詳細を見る</button>
<dialog id="notice" aria-labelledby="notice-title">
<h2 id="notice-title">メンテナンスのお知らせ</h2>
<p>11月30日 2:00〜5:00 はサービスを停止します。</p>
<button type="button" command="close" commandfor="notice" autofocus>閉じる</button>
</dialog>
<script src="modal.js"></script>
dialog {
padding: 24px;
border: none;
}
dialog:modal {
overscroll-behavior: contain;
}
dialog::backdrop {
background: rgb(0 0 0 / .5);
overflow: hidden;
overscroll-behavior: contain;
}
// modal.js
var dialog = document.getElementById('notice');
// 背景(ダイアログの外側)のクリックで閉じる
dialog.addEventListener('click', function (e) {
var rect = dialog.getBoundingClientRect();
var isInside =
e.clientX >= rect.left && e.clientX <= rect.right &&
e.clientY >= rect.top && e.clientY <= rect.bottom;
if (!isInside) {
dialog.close();
}
});
この「外側をクリックしたら閉じる」処理は、これまでJavaScriptで実装することが多かったのですが、現在はHTML属性でも実現できます。
legacy-scanで古い書き方を探す
このコードにlegacy-scanを実行します。
npx modern-web-guidance@latest legacy-scan sample --json
実行結果は次のとおりです。ファイルパスの一部は記事掲載用に置き換えています。
{
"totalFindings": 1,
"guides": [
{
"guideId": "dialog",
"retrieveCommand": "npx modern-web-guidance retrieve dialog",
"count": 1,
"rules": [
{
"ruleId": "dialog",
"summary": "Manual backdrop click listeners dismissing <dialog> should be modernized with declarative <dialog closedby=\"any\">.",
"verifierRubric": {
"keepWhen": [
"A click event listener attached to a <dialog> or modal checks event.target === dialog, event.target === event.currentTarget, or bounding box coordinates to dismiss the dialog via .close().",
"A script implements manual light-dismiss for an HTML <dialog> element when clicking outside the content area on the backdrop."
],
"dropWhen": [
"The listener is guarded by \"closedBy\" in HTMLDialogElement.prototype for progressive enhancement.",
"The click handler is attached to a dedicated close button (.btn-close, [data-dismiss]) rather than the dialog backdrop.",
"The dialog is opened as a non-modal dialog with .show() rather than .showModal().",
"The listener handles custom menu or popover light dismiss covered by popover attribute."
]
},
"count": 1,
"findings": [
{
"file": "XXXXXX/sample/modal.js",
"line": 4,
"message": "Manual backdrop click listener dismisses dialog; modernize with declarative <dialog closedby=\"any\">.",
"lineContent": "dialog.addEventListener('click', function (e) {"
}
]
}
]
}
],
"activeRuleCount": 35,
"activeGuideCount": 33,
"note": "Checked 33 guides (35 deterministic rules; ~20% of the guidance corpus). Finding 1 item here only reflects deterministic legacy patterns; use 'search <topic>' for the rest of the catalog."
}
modal.jsの4行目にある、ダイアログの外側をクリックしたかを座標で判定して閉じる処理が、古い書き方として1件検出されました。<dialog closedby="any">に置き換えるよう指摘されています。
書き換え後のコード
続いて、Claude Codeに「modern-web-guidanceを使って、sampleのコードを書き直して」と指示しました。書き換え後のHTMLとJavaScriptは次のとおりです。
<button type="button" command="show-modal" commandfor="notice">詳細を見る</button>
<dialog id="notice" aria-labelledby="notice-title" closedby="any">
<h2 id="notice-title">メンテナンスのお知らせ</h2>
<p>11月30日 2:00〜5:00 はサービスを停止します。</p>
<button type="button" command="close" commandfor="notice" autofocus>閉じる</button>
</dialog>
<script src="modal.js"></script>
// modal.js
// closedby="any"(外側クリックで閉じる)に未対応のブラウザ(Safari)でのみ補う
if (!('closedBy' in HTMLDialogElement.prototype)) {
// event.target ではなく座標で判定する(ダイアログ自身の padding 部分も target が dialog になるため)
const outside = (e, dialog) => {
const r = dialog.getBoundingClientRect();
return e.clientX < r.left || e.clientX > r.right || e.clientY < r.top || e.clientY > r.bottom;
};
for (const dialog of document.querySelectorAll('dialog[closedby="any"]')) {
let pressedOutside = false;
dialog.addEventListener('pointerdown', (e) => { pressedOutside = outside(e, dialog); });
// 押した位置と離した位置の両方が外側のときだけ閉じる(テキスト選択のドラッグで閉じないように)
dialog.addEventListener('pointerup', (e) => { if (pressedOutside && outside(e, dialog)) dialog.close(); });
}
}
<dialog>にclosedby="any"を付けると、外側のクリックで閉じる動作をブラウザが担当してくれます。
JavaScriptが残っているのは、2026年11月13日に確認した時点では、closedbyがSafari未対応で、CLAUDE.mdで指定したBaseline 2025の対象外だからです。AIは、Safariなどの未対応ブラウザ向けに、ダイアログの外側をポインターで操作したときに閉じる補完コードを残しました。
まとめ
Modern Web Guidanceを使うと、AIエージェントが古い書き方を見つけてモダンな書き方に置き換え、対応ブラウザの方針に合わせて未対応ブラウザ向けの代替手段まで用意してくれます。
今回紹介したモーダルの書き換え以外にも、フォームやパフォーマンス、アクセシビリティなど、さまざまな場面で活用できるので、ぜひ試してみてください。