frontend-excellence

フロントエンドの卓越性

忘れられない見た目で、Lighthouse のスコアを高水準に保ち、さまざまなデバイスや支援技術でも適切に機能するウェブインターフェースを実現するための、包括的なスキルです。特定のフレームワークに依存しない設計で、すべてのルールをライブラリの API ではなく、原則と具体的なチェック項目として示します。

使用するタイミング

インターフェースの見た目、使い心地、動き、読み込み、検索順位、操作方法に影響する作業では、いつでもこのスキルを適用してください。たとえば、次のような作業です。

• ページ、フォーム、モーダル、ナビゲーション、テーブル、チャート、コンポーネントの構築やリファクタリング
• タイポグラフィ、色、余白、モーション、ビジュアルスタイルの選定
• Core Web Vitals（LCP、INP、CLS）、バンドルサイズ、ハイドレーションのコストの監査や改善
• アクセシビリティ（コントラスト、キーボード操作、スクリーンリーダー、フォーカス、文字サイズ変更）の監査や改善
• オンページ SEO（タイトル、説明、見出し、構造化データ、canonical）の監査や改善
• ビジュアルの仕上がり、階層、コントラスト、情報密度、ダークモードとライトモードの一貫性の確認
• 画一的な AI 風のスタイルを、個性のある美的方針に置き換える
• 既存の複数ページにわたるサイトを、参照デザインや本番環境の基準と照らし合わせて監査、仕上げる

バックエンドのロジック、インフラストラクチャ、データパイプライン、視覚要素のないスクリプトには、このスキルを適用しないでください。

読み込み方針（参照資料を読み込む前に確認）

references/ 内の各ファイルは、平均で 400～600 行あります。3 ファイルを超えて一度に読み込むと、不要な情報でコンテキストを消費します。以下のルーティングテーブル（タスク別、症状別、次に参照インデックス）を読んで、現在の作業に合った 2～3 ファイルを選んでください。テーブルを見ても判断できない場合は、候補ファイルの冒頭にある YAML フロントマターを読み込んでください（head -20 を使って各ファイル約 15 行を確認します）。現在の作業に合わなくなった参照資料は、読み込み対象から外してください。

目指すべき基準

インターフェースは、完了とみなす前にすべての基準を満たす必要があります。基準を満たさない項目は、仕上げの問題ではなく、リリースを妨げる不具合として扱ってください。

カテゴリ	モバイルの目標	デスクトップの目標	出典
Lighthouse パフォーマンス	>= 95	>= 99	Lighthouse
Lighthouse アクセシビリティ	100	100	Lighthouse + axe
Lighthouse ベストプラクティス	100	100	Lighthouse
Lighthouse SEO	100	100	Lighthouse
Largest Contentful Paint（LCP）	< 2.5s	< 2.0s	Core Web Vitals
Interaction to Next Paint（INP）	< 200ms	< 200ms	Core Web Vitals
Cumulative Layout Shift（CLS）	< 0.1	< 0.05	Core Web Vitals
Time to First Byte（TTFB）	< 800ms	< 600ms	Core Web Vitals
First Contentful Paint（FCP）	< 1.8s	< 1.0s	Lighthouse
Total Blocking Time（TBT）	< 200ms	< 100ms	Lighthouse
初期 JS ペイロード（gzip 圧縮後）	< 90 KB	< 130 KB	予算
初期 CSS ペイロード（gzip 圧縮後）	< 25 KB	< 35 KB	予算
ウェブフォントのペイロード（画面あたり）	<= 2 ファミリー、<= 4 ウェイト	同じ	予算

これらは、すべてのプロジェクトに適用される基準です。プロジェクトによっては、特定の画面について予算を意識的に緩和することもあります（たとえば、高度にインタラクティブなクライアントレンダリングのツールでは、正当な理由から JS を多く含める場合があります）。ただし、緩和する場合は、デフォルトではなく、記録され、根拠が示された例外としてください。

優先順位スタック（レビューでは上から順に確認）

1. クロール可能性とインデックス登録可能性（ページが適切な canonical と meta を伴ってインデックスに存在するか）
2. アクセシビリティの正確性（セマンティック HTML、コントラスト、キーボード操作、フォーカス、スクリーンリーダー）
3. Core Web Vitals（LCP、INP、CLS、TTFB）
4. レイアウトとレスポンシブの整合性（横スクロールがない、コンテンツが切れない、セーフエリアを尊重する）
5. 視覚的な階層と意図的な美しさ（タイポグラフィ、色、余白、動き、密度）
6. インタラクションの品質（ホバー、押下、フォーカス、読み込み、エラー、空、成功の状態）
7. フォームとフィードバック（検証、エラーの配置、復旧、自動入力、自動保存）
8. 動きとアニメーション（目的が明確で、視差効果を抑える設定に対応し、transform のみを使用）
9. データとグラフ（読みやすく、アクセシブルで、レスポンシブ）
10. 仕上げと完成度（アイコンの一貫性、ダーク／ライトの同等性、ブランドへの忠実さ）

優先度の高い項目は、常に低い項目よりも優先されます。美しさのためにコントラストを犠牲にしてはいけません。アニメーションのために INP を犠牲にしてはいけません。

ルールが競合する場合（優先順位の決め方）

優先順位スタックは一般的なケースを扱います。特定の 2 つのルールが競合する場合は、この表に従ってください。

競合	優先するもの
アニメーションの仕上がりと INP の予算	INP を優先します。INP が 200ms を超える原因となるアニメーションは、仕上げの問題ではなく不具合です。
美的な好みと WCAG コントラスト	コントラストを優先します。見た目の好みを理由に、大きなテキストの 3:1 や本文の 4.5:1 という最低基準を緩和することはできません。
LCP のプリロードと初期 JS の予算	JS の予算を優先します。より小さな LCP 要素を探すか、プリロードを遅らせてください。予算を超過させてはいけません。
SEO のための SSR とハイドレーションコストを抑えた INP	分割します。インデックス登録可能性のためにシェルを SSR し、INP を 200ms 未満に保つためにアイランドの読み込みを遅らせます。
動きの仕上げと prefers-reduced-motion	視差効果を抑える設定を優先します。動きは拡張要素であり、基本状態ではありません。
ブランドカラーとダークモードのテキストコントラスト	暗い背景上のテキストには明るくしたアクセントカラーを使用し、ブランドカラーは背景に使用します。design.md を参照してください。

判断：レンダリング戦略

ページは 5 つのレンダリング戦略のいずれかを採用します。次の軸に基づいて選択してください。詳しくは performance.md と seo.md を参照してください。

条件	選択肢
インデックス登録可能、主に静的なコンテンツ、パーソナライズが少ない、トラフィック急増への耐性が必要	SSG（静的サイト生成）
インデックス登録可能、リクエストごとのパーソナライズが必要、動的データがある、サーバーに計算リソースの余裕がある	SSR（サーバーサイドレンダリング）、必要に応じてストリーミング
インデックス登録不要、高度なインタラクティブ性が必要、アプリシェル型の体験、INP に敏感	CSR（クライアントサイドレンダリング）、ルート単位のコード分割を使用
インデックス登録可能、一部パーソナライズが必要、シェルに SSG と再検証を使用したい	ISR（インクリメンタル静的再生成）
主に静的で、インタラクティブなウィジェットが少数あり、JS を最小限に抑えたい	静的コンテンツ＋アイランド（部分ハイドレーション／レジューマビリティ）

経験則：まずインデックス登録可能性を優先します（インデックス登録可能な画面には SSG／SSR／ISR）。次にインタラクティブ性のコストを考慮します（SSR ページが JS の予算を超える場合はアイランドに分割）。CSR は、インデックス登録が不要で、アプリシェルがプロダクトそのものである場合に限って選択します。

ルーティング：タスク別

依頼内容に合致する行を選んでください。まず指定されたファイルを読み、別の参照先が示されている場合に限り、ほかのファイルも読み込んでください。

依頼内容	読み込むファイル
ページをゼロから新規作成する	components.md, design.md, responsive.md, performance.md
既存サイトをリファレンスと照合して監査する	audit-workflow.md, defects.md, design.md
Lighthouse の監査に失敗する問題を修正する	lighthouse.md, performance.md, debug-recipes.md
既存ページのビジュアル品質を向上させる	design.md, ui-ux.md, defects.md
フォームまたはサインインのフローを追加する	forms.md, auth.md, accessibility.md
CI ゲートとマージ前チェックを設定する	testing.md, lighthouse.md, observability.md
本番環境の問題を診断する	observability.md, debug-recipes.md, defects.md
リリース前にページの完成を確認する	pre-launch.md, quick-reference.md
画面を国際化またはローカライズする	i18n.md, responsive.md, accessibility.md
セキュリティを強化する（CSP、ヘッダー、Trusted Types、SRI）	security.md, lighthouse.md, pre-launch.md
PWA、オフライン対応、またはインストール可能な機能を追加する	pwa-offline.md, performance.md
サードパーティーのウィジェットを埋め込む、または埋め込みに対応する	embed-patterns.md, security.md, auth.md
印刷用スタイルシートまたはトランザクションメールの HTML を作成する	print-email.md
グラフ、表、またはデータ表示を追加する	data-viz.md, ui-ux.md, accessibility.md
モーションやアニメーションを追加または調整する	motion.md, performance.md
既知のアンチパターンに照らして変更をレビューする	anti-patterns.md, defects.md

ルーティング：症状別

観察できる問題の兆候を手がかりに、関連するファイルとセクションへ直接移動してください。

症状	読み込む可能性の高い根本原因、ファイル、セクション
LCP > 2.5s、LCP の低下	preload／fetchpriority／ハイドレーションのコスト：performance.md: Core Web Vitals
INP > 200ms、操作が遅い	長時間タスク／ハンドラー／ハイドレーション：performance.md: Core Web Vitals、debug-recipes.md: INP regression
CLS > 0.1、レイアウトのずれ	非同期要素の表示領域が確保されていない：performance.md: Core Web Vitals、defects.md: Defect Lookup Table
フォント切り替えによる CLS	フォールバックフォントの size-adjust／metrics-override が未設定：debug-recipes.md: Font-swap CLS、performance.md: Font Strategy
Lighthouse SEO < 100	評価対象ページに noindex がある、canonical がない：lighthouse.md: Failing Audit to Fix Map、seo.md: Indexability
Lighthouse Best Practices < 100	CSP 違反、コンソールエラー、非推奨機能：lighthouse.md: Failing Audit to Fix Map、security.md: CSP at Depth
errors-in-console、古い SRI ビーコン	サードパーティ製ビーコンの CORS／固定ハッシュの古さ、またはクライアント側ブロッカーによる誤検知：debug-recipes.md: Lighthouse flake triage
偽の開発時エラー（開発サーバーでのみスコアが低い）	本番ビルドではなく開発サーバーを評価している：lighthouse.md: Run Lighthouse Properly
Retina で画像が小さすぎる（image-size-responsive）	最大の srcset 候補が CSS 幅 × DPR を下回っている：responsive.md: Responsive Images、lighthouse.md: Failing Audit to Fix Map
コントラストの不合格、特にビルド変更後	比率が低い、または CSS の配信方法の変更によってカスケード順序が入れ替わった：accessibility.md: Color and Contrast、lighthouse.md: Failing Audit to Fix Map
id の重複	id がハードコードされたコンポーネントの再利用：components.md: Drift Detection
スクロールロック時に横へずれる	モーダルに scrollbar-width の補正がない：ui-ux.md: Modals and Overlays、defects.md: Defect Lookup Table
ハイドレーションの不一致	サーバーとクライアントの差異：debug-recipes.md: Hydration mismatch、performance.md: JavaScript Strategy
ビューポートからのはみ出し、横スクロール	子要素のはみ出し：responsive.md: Horizontal Scroll: Forbidden、defects.md: Defect Lookup Table
フォーカストラップの漏れ、フォーカスが見えない	オーバーレイのフォーカス管理：debug-recipes.md: Focus trap leak、accessibility.md: Keyboard
サードパーティスクリプトが遅い、分析処理がブロックする	サードパーティスクリプトの管理／async-defer のマトリックス：performance.md: Third-Party Strategy、build-hygiene.md: Dependency-Cost Discipline
Firefox／Safari でのみ動作しない	機能サポートに関する前提、フォールバックの不足：responsive.md: Media Preferences、motion.md: Reduced Motion
同意バナーによる CLS、バウンディングボックスのずれ	オーバーレイの表示領域が確保されていない：ui-ux.md: Modals and Overlays、seo.md: Indexability
背景の aria-hidden が読み上げられる、inert の漏れ	オーバーレイが誤った祖先要素に適用されている：accessibility.md: Modal and Dialog、ui-ux.md: Modals and Overlays
ヒーローアニメーションによる LCP または TBT の悪化	ファーストビューのアニメーションが予算に応じて制御されていない：motion.md: Hero Animations

リファレンス一覧

詳細なガイダンスは references/ にあります。各行には、ファイルの概要と、そのファイルを参照すべきキーワードを記載しています。

ファイル	参照する場面（キーワード）
lighthouse.md	Lighthouse、監査、スコア、CI ゲート、csp-xss、duplicate-id、is-crawlable、スコアのばらつき、ユーザーフロー
performance.md	LCP、INP、CLS、TTFB、パフォーマンス、ハイドレーション、バンドル、BFCache、Speculation Rules、Early Hints、fetchpriority、レンダリング戦略、SSR、SSG、CSR、サードパーティスクリプト、リストの仮想化
accessibility.md	a11y、WCAG、ARIA、スクリーンリーダー、キーボード、フォーカス、コントラスト、強制カラーモード、動きの低減、ダイナミックタイプ
seo.md	SEO、canonical、サイトマップ、robots、構造化データ、JSON-LD、AEO、GEO、llms.txt、hreflang、Open Graph
ui-ux.md	UI、UX、モーダル、ポップオーバー、ダイアログ、ドロワー、メニュー、ツールチップ、パンくずリスト、タッチターゲット、ヒットターゲット、ポップオーバー API、inert
design.md	デザイン、タイポグラフィ、色、OKLCH、P3、ダークモード、ブランド、可変フォント、@layer
responsive.md	レスポンシブ、ブレークポイント、コンテナクエリ、ビューポート、セーフエリア、dvh、srcset、サブグリッド、スクロールバーガター
motion.md	動き、アニメーション、トランジション、イージング、View Transitions、スクロール駆動、WAAPI、@starting-style
forms.md	フォーム、検証、入力、自動入力、オートコンプリート、constraintValidation
data-viz.md	グラフ、データ可視化、軸、凡例、Canvas、SVG、WebGL、タイムゾーン
pre-launch.md	リリース前、チェックリスト、リリース、ゲート、検証、エビデンス
audit-workflow.md	監査、ルート、網羅的確認、ベースライン、キャプチャ、仕上げ、複数ページ
components.md	コンポーネント、コントラクト、抽出、スロット、コンポジション、トークン、Storybook
defects.md	不具合、ジオメトリ、網羅的確認、しきい値、リグレッション、検索
security.md	CSP、COOP、COEP、CORP、クロスオリジン分離、Trusted Types、SRI、Permissions-Policy、Referrer-Policy、サプライチェーン
observability.md	RUM、オブザーバビリティ、モニタリング、ソースマップ、エラー捕捉、INP の要因分析、Reporting API、CrUX、LoAF
testing.md	テスト、ビジュアルリグレッション、axe-core、pa11y、size-limit、bundlesize、lighthouse-ci、コントラクトテスト
auth.md	認証、ログイン、パスキー、WebAuthn、OAuth、マジックリンク、セッション、アカウント復旧、CAPTCHA、Storage Access API
debug-recipes.md	デバッグ、レシピ、ハイドレーションの不一致、レイアウトのオーバーフロー、フォーカストラップ、フォント切り替えによる CLS、Lighthouse の不安定動作
anti-patterns.md	アンチパターン、避けるべきこと、間違い
i18n.md	i18n、l10n、ロケール、翻訳、Intl、複数形ルール、双方向テキスト、RTL、ミラーリング、hreflang
pwa-offline.md	PWA、オフライン、サービスワーカー、インストールプロンプト、プッシュ、バックグラウンド同期、マニフェスト
build-hygiene.md	ビルド、ツリーシェイキング、sideEffects、ロックファイル、デッドコード、コード分割、依存関係のコスト
embed-patterns.md	埋め込み、iframe、sandbox、postMessage、ホスト、ゲスト、サードパーティウィジェット
print-email.md	印刷、メール、@page、改ページ、トランザクションメール、Outlook
quick-reference.md	ルール、クイックリファレンス、効果の大きい項目

ワークフロー

1. 作業の枠組みを決める

コードを書く前に、対象ユーザーと目的、インデックス登録の可否（検索エンジンに登録される領域か、認証が必要な領域か）、デザインの方向性（大胆な方向性を1つ選び、「白地にInterと紫のグラデーション」は避ける）、制約（上の表にあるレンダリング戦略、ハイドレーションの方式、対応ブラウザーの最低要件、ロケール、記述方向）を明確にします。

どの段階でも、レンダリングされたブラウザー表示を唯一の判断基準にします。コードだけで見た目の品質を判断せず、スクリーンショットを撮って参考画像と比較し、修正してから再度撮影してください。新規構築ではなく、既存の複数ページのサイトを監査または調整する場合は、以下の「複数ページの調整ループ」に切り替えてください。

2. 構成を計画する

ページごとにH1を1つ設け、見出しの順序を守ります。LCP要素を最初のビューポート内に配置します（実際に配信されるアセットを使用し、サイズを明示して、遅延読み込みやハイドレーション待ちにしないでください）。非同期要素ごとにスペースを確保します（aspect-ratio、固定の高さ、スケルトンなど）。どのセクションをサーバー側でレンダリングするか、ストリーミングするか、遅延させるか、クライアント側のみで処理するかを決め、クライアント側のみで処理する選択にはすべて理由を付けてください。

3. 予算を設定して構築する

各領域について、以下を設定し、検証します。JSペイロード（初期ルート、gzip圧縮後）、CSSペイロード（初期ルート、gzip圧縮後）、画像ペイロード（ファーストビュー内）、フォントの予算（ファミリー、ウェイト、サブセット、合計バイト数）、サードパーティスクリプトの予算（数、メインスレッド時間の合計ミリ秒）。明示的かつ記録済みの例外がない限り、予算を超える追加は認めません。

4. 検証する

作業完了とする前に、Lighthouse、axe、ビジュアル、レスポンシブ、ダークモード、視差効果の軽減、キーボード、スクリーンリーダーの全項目を検証してください。pre-launch.mdを参照してください。

複数ページの調整ループ

既存の複数ページのサイトを監査または調整する場合は、まず audit-workflow.mdを読み、手順全体（作業ルール、キャプチャスクリプト、フェーズごとの詳細、最終受け入れ基準）を確認してください。19のフェーズは次のとおりです。

1. 背景を把握する。2. ルートを一覧化する。3. 繰り返し使われるウィジェットを一覧化する。4. ベースラインを記録する。5. 参考画像を記録する。6. 各ルートを監査する。7. 修正の優先順位を付ける。8. コンポーネントの規律を守って修正する。9. デザインの規律を守って修正する。10. 修正グループごとに検証する。11. プログラムによるジオメトリの確認（およびコンテンツとマークアップの一括確認）。12. コンポーネントの差異を確認する。13. インタラクションのQAを行う。14. アクセシビリティを検証する。15. Lighthouseとパフォーマンスを調整する。16. 参考画像レベルのデザインヒューリスティクスを適用する。17. よくある不具合と修正方法を確認する。18. 成果物をまとめる。19. 最終受け入れ基準を確認する。

コンポーネント抽出の指針はcomponents.mdに、不具合の検索とジオメトリの一括確認はdefects.mdに記載されています。

クイックリファレンス

パフォーマンス、アクセシビリティ、SEO、UI/UX、デザイン、複数ページ間の一貫性に関する、効果の高いルールはreferences/quick-reference.mdにまとめられています。変更内容と照らし合わせるために、要点を1つにまとめたものを確認したい場合は、このファイルを開いてください。

スキルの最新性

このスキルには、ある時点でのウェブプラットフォームの挙動が記載されています。古いルールを適用する前に、次の場合は現在も有効か確認してください。

• Lighthouseの監査ID、重み、カテゴリのしきい値が記載されている場合（Lighthouseのカテゴリは数回のリリースごとに再調整されます）。
• ブラウザー対応の最低要件が記載されている場合（Baselineのステータスは変化するため、caniuse.comまたはMDN Baselineウィジェットで確認してください）。
• Core Web Vitalsの具体的なしきい値や指標名が記載されている場合（2024年にFIDはINPに置き換わりました。しきい値も見直されます）。
• CSSまたはJSのAPI（[@layer、View Transitions、Anchor Positioning、Popover、:has()]）が挙げられている場合（これらの対応状況は2023年から2026年の間に変化しました）。

追加および改善の履歴については、日付付きのCHANGELOG.mdを参照してください。

自己改善

このスキルを適用した後、作業完了を宣言する前に、次の点を確認してください。

• Lighthouse は、開発モードではなく実際の本番ビルドに対して、モバイルとデスクトップのスロットリング済みプリセットで実行しましたか？
• 変更したすべてのページで axe（または同等のツール）を実行し、違反がゼロであることを確認しましたか？
• ページは 320px、375px、768px、1024px、1280px、1920px で正しく表示されましたか？
• ページはライトモードとダークモードの両方で、それぞれ独立して（片方を CSS で反転させるのではなく）正しく表示されましたか？
• ページは prefers-reduced-motion: reduce の設定で正しく表示されましたか？
• キーボードのみでページを最後まで操作できましたか？
• 主要なタスクについて、スクリーンリーダー（VoiceOver または NVDA）でページを確認し、問題なく使えることを確認しましたか？
• LCP 要素には fetchpriority="high" と寸法が指定され、実際に配信されるアセットが設定されていましたか？
• カスタムフォントはすべて font-display を設定して読み込まれ、ファミリー数は 2 以下、ウェイト数は 4 以下ですか？
• すべての非同期セクションでスペースが確保されていますか？
• すべてのインタラクティブ要素でフォーカスが視認でき、コントラスト要件を満たしていますか？
• ページには固有のタイトル、説明、canonical、OG、Twitter、および（該当する場合）JSON-LD が設定されていますか？
• ソース設定だけでなく、配信されるビルドの出力（コピーされたヘッダー、静的ファイル、生成された画像）を確認しましたか？

複数ページの監査と仕上げ作業では、さらに次の点も確認してください。

• 共通ファミリー（ヘッダー、ヒーロー、セクション、CTA、カード、メディア、リスト、インタラクティブ、空の状態、法的情報、404）ごとに、すべてのウィジェットを一覧化しましたか？
• 編集前に、1440x900 と 375x812 のベースラインスクリーンショットを撮影しましたか？
• 変更したすべてのルートについて、1440x900 と 375x812 の編集後スクリーンショットを撮影しましたか？
• 監査したすべてのルートの両方のビューポートで、ジオメトリチェックの問題はゼロでしたか？
• すべてのルートで、プログラムによるチェック（ジオメトリ、およびコンテンツとマークアップ）の両方を実行しましたか？
• ドリフト収集ツールの結果として、共通ウィジェットファミリーに説明のつかない差異はありませんでしたか？
• ルートごとの監査表（見つかった問題、適用した修正、修正前、修正後）を変更とともに提出しましたか？

いずれかの回答が「いいえ」または「未確認」の場合、作業は完了していません。