software-frontend

フロントエンドエンジニアリング

React、Next.js、Vue、Nuxt、Angular、Svelte、および関連ツールを使った、本番環境向けのWebフロントエンド開発にはこのスキルを使用します。フレームワークの選定、フロントエンドの実装パターン、ハイドレーションとSSRのデバッグ、状態管理とデータ取得のパターン、フロントエンドのリリース規律を扱います。

クイックリファレンス

タスク	使用するもの
フルスタックReactアプリ	references/fullstack-patterns.md、assets/nextjs/template-nextjs-tailwind-shadcn.md
React SPA	references/vite-react-patterns.md、assets/vite-react/template-vite-react-ts.md
React RouterまたはRemix	references/remix-react-patterns.md、assets/remix/template-remix-react.md
VueまたはNuxt	references/vue-nuxt-patterns.md、assets/vue-nuxt/template-nuxt4-tailwind.md
Angular	references/angular-patterns.md、assets/angular/template-angular21-standalone.md（スキャフォールド後のチェックリスト。インストール済みのCLIを使用してください）
SvelteまたはSvelteKit	references/svelte-sveltekit-patterns.md、assets/svelte/template-sveltekit-runes.md
状態管理、テスト、パフォーマンス、注意点	references/state-management-patterns.md、references/testing-frontend-patterns.md、references/performance-optimization.md、references/production-gotchas.md、references/operational-playbook.md

このスキルを使用する場面

• フロントエンドアプリを構築またはスキャフォールドする。
• ハイドレーション、SSR、ビルド、またはクライアントとサーバーの境界に関する問題を修正する。
• ルーティング、状態管理、データ取得、コンポーネントのパターンを選定する。
• フロントエンドのテスト、パフォーマンス予算、リリースゲートを設定する。
• 本番環境で安全に使えるデフォルト設定で、モダンなフレームワークのUIを実装する。

別のスキルを使用する場面

• バックエンドAPIまたはサービスの実装：software-backendを使用してください。
• APIコントラクトの設計：dev-api-designを使用してください。
• UIまたはUXの設計：software-ui-ux-designを使用してください。アクセシビリティの実装や修正にはsoftware-accessibility、正式な監査やテストにはqa-testing-accessibility、パフォーマンス監査にはsoftware-performanceを使用してください。
• モバイルネイティブ開発：software-mobileを使用してください。
• 国際化の設定：software-localisationを使用してください。
• E2Eテストの作成に特化した作業：qa-testing-playwrightを使用してください。
• Webアプリでの自然な会話型チャットUI（Chromeの組み込みAI window.ai、ブラウザー内推論用のWebLLM / transformers.js、クラウドLLMのストリーミング、デバイス上での処理が利用できない場合の決定論的フォールバック）：ai-context-layer/references/conversational-surfaces-cross-platform.mdを使用してください。

デフォルト

• やみくもに特定のスタックを選ぶのではなく、ルーティングとレンダリングのニーズに合ったフレームワークを選びます。
• 最新のフレームワーク機能よりも、リポジトリですでに採用されている無難な選択肢を優先します。新しいプリミティブ（レンダリングモード、コンパイラー、ルーティング規約など）を採用するのは、しばらく安定版としてリリースされ、チームに具体的な理由がある場合に限ります。新しいという理由だけでは採用しません。
• リポジトリの構成を維持します。新しいアプリでは、公式 CLI のスキャフォールドと、それに対応するスキャフォールド後のチェックリストを使用します。
• 新しいプロバイダー、ストア、規約を追加する前に、リポジトリ内のフロントエンドのパターンを確認します。
• アクセシビリティとパフォーマンスをリリースの必須条件として扱います。
• API を採用する前に、インストール済みのフレームワーク、ロックファイル、公式の移行ガイドを確認します。data/versions.json は日付時点の調査用スナップショットとしてのみ使用し、バージョンを固定する前にサポート状況を確認します。
• TypeScript コンパイラーを移行する場合は、公式のリリースノートと、API に依存する各ツールのサポート状況（型付き ESLint、vue-tsc、Angular コンパイラー、svelte-check）を確認します。互換性が確認されるまでは、それらがサポートするコンパイラーの系統を維持し、ロックファイルの正確な解決結果を保持します。

機能別 React プリミティブ

採用前に、インストール済みの React/react-dom とフレームワークの互換性を確認します。以下のバージョンは機能の境界を示すもので、現在のバージョンを固定するものではありません。

• React 19.2：Activity は非表示の UI 状態を保持しながら Effect をクリーンアップします。useEffectEvent は、Effect がトリガーするロジック内で、Effect のリアクティブな依存関係を変更せずに、呼び出し時点の props/state を読み取ります。依存関係の抑制に使うものではありません。cacheSignal は RSC のキャッシュのライフタイムとキャンセルに属するものであり、クライアントキャッシュには使いません。リリースノートを参照してください。
• React 19.3：ViewTransition はトランジションによる更新をアニメーション化します。Fragment refs は余分なラッパーを追加せずに、グループ化された DOM 操作を公開します。React/react-dom の use(browser()) は、Suspense フォールバックを介してブラウザー専用コンポーネントを SSR の対象外にします。可能な限り、意味のあるサーバー HTML を維持してください。リリースノートを参照してください。
• 生の React プリレンダー／再開パイプラインを導入するのではなく、フレームワークがサポートするレンダー／キャッシュ連携を使用します。選択したプリミティブについて、Hooks の Lint サポートと、ブラウザーおよび動きを抑える設定での動作を確認します。

ワークフロー

1. レンダリングモデル、ルーティングのニーズ、SEO の制約、デプロイ形態を明確にします。
2. 問題に適したフレームワークとテンプレートを選びます。
3. ユーザーのフレームワークまたは課題に合ったリファレンスだけを読み込みます。
4. 状態管理、データ取得、スタイリング、テストには、リポジトリ内のパターンを使って実装します。
5. 承認前に、ハイドレーション、アクセシビリティ、パフォーマンス、引き継ぎの要件を確認します。

主な判断事項

フレームワークの選定

ニーズ	フレームワーク	備考
フルスタック React、SEO	Next.js	App Router。サーバーコンポーネントには RSC を使用します。マイナーバージョンを固定する前に、現在のメジャーバージョンを data/versions.json の next で確認してください
ルート中心のプログレッシブエンハンスメント	React Router（フレームワークモード、デフォルト）	Loader/action のデータ契約を使用します。レガシーな Remix を使う場合は、新しいスキャフォールドを選ぶ前に公式の移行／サポートガイダンスを確認してください。別系統の Remix が React Router のフレームワーク API を共有しているとは想定しないでください
クライアントのみの React SPA	Vite + React	SSR の複雑さがありません
Vue フルスタック	Nuxt	自動インポート、サーバールートを利用できます。仮想 DOM を使わない Vapor モードはオプトイン方式です。Nuxt、Pinia、VueUse のサポートが確認されるまではデフォルトではありません。バージョンを記載する前に、data/versions.json の vue エントリと vuejs.org/about/releases を確認してください
Angular アプリ	Angular（現在のメジャーバージョン。data/versions.json の @angular/core を参照）	スタンドアロンコンポーネント、シグナル優先、ゾーンレス変更検知を使用します。バージョンを固定する前に、現在のメジャーバージョンと LTS 系統を angular.dev/reference/releases で、該当メジャーバージョンのゾーンレスのデフォルト設定を angular.dev で確認してください
Svelte を優先	SvelteKit	Runes ベースのリアクティビティを使用します。現在のメジャーバージョンは data/versions.json の svelte で確認してください

まずレンダリングモデル（CSR／SSR／SSG／ハイブリッド）を選び、その後にフレームワークを選びます。どちらのフレームワークも適している場合は、チームが本番環境ですでに運用しているものをデフォルトにしてください。2つ目のフレームワークを導入すると、ビルドツール、テスト環境、採用、思考の切り替えといった継続的なコストが発生し、単一の機能では割に合わないことがほとんどです。

サーバー／クライアントレンダリングの判断

• 主にコンテンツを扱うもの、SEO が重要なもの、またはクライアント側のデータ取得の連鎖を送信せずに初回表示を高速化できるものには、サーバーレンダリング（RSC、SSR、SSG）をデフォルトで使用します。
• クライアント側レンダリングは意図的に選択してください。高度にインタラクティブなウィジェット、SEO が重要ではない認証後のアプリ、往復通信なしで維持する必要がある状態（ドラッグ＆ドロップ、Canvas／WebGL、リアルタイムコラボレーション）などが対象です。
• すべてのクライアントコンポーネントにはハイドレーションのコストがあります。コンポーネントがインタラクティブになる前に、JS が送信、解析、実行されます。'use client'（またはフレームワークにおける相当機能）は無料の回避策ではなく、オプトインのコストとして扱ってください。子コンポーネントの1つが onClick を必要とするからといってルートツリー全体をクライアント側にするのではなく、インタラクティビティが実際に必要とする範囲まで適用を絞り込んでください。
• アコーディオンの切り替えやツールチップなど、小さな部分だけにインタラクティビティが必要なコンポーネントは、ページ全体をクライアントレンダリングにするのではなく、その部分だけを小さなクライアントアイランドで囲み、通常はサーバーレンダリングのままにできます。

デザインシステムとコンポーネントライブラリ

• コンポーネントライブラリ（shadcn/ui、Radix、Angular Material、PrimeNG、Nuxt UI）は、特定のスタイルを押し付けない、またはその度合いが小さい基本要素（ボタン、ダイアログ、フォームコントロール）を提供します。動作のプリミティブが備わっていますが、アクセシブルな組み合わせ、ラベル、フォーカス管理、検証は引き続き必要です。ビジュアル言語は主に利用側に委ねられます。
• デザインシステムはプロダクト上の判断です。色、間隔、文字のスケールなどのトークン、使用ルール、さらに多くの場合は1つ以上のコンポーネントライブラリ上に構築されたコンポーネント API を、文書化してバージョン管理したものです。チームや時間を超えて、プロダクトの見た目と振る舞いに一貫性を保つために存在します。
• コンポーネントライブラリで問題が解決するなら、デザインシステムを構築しないでください。単一のアプリや小規模なチームには、たいてい過剰設計です。複数のチームやプロダクトで見た目と振る舞いを一貫させる必要がある場合や、PR をまたいで同じ見た目の不整合が繰り返し発生する場合は、デザインシステム（少なくとも共有トークン）を必ず用意してください。
• リポジトリにすでにデザインシステムがある場合は、そのコンポーネント API を、基盤となるライブラリの生のコンポーネントより優先される唯一の情報源として扱ってください。デザインシステムに実際の不足がある場合を除き、デザインシステムを介さずに Radix／shadcn のプリミティブを直接使わないでください。

状態管理とデータ取得

データの種類	デフォルトのツール	次の場合にのみ追加
サーバー状態（非同期、キャッシュ済み）	TanStack Query（またはルーターがすでに提供している場合はフレームワークのローダー）	リポジトリですでに標準採用されている場合にのみSWRを使用します
グローバルなクライアント状態（ルート間で共有）	Zustand（VueではPinia）	状態が単に共有されているのではなく、真にアトミック／粒度の細かいものである場合にのみJotaiに切り替えます
RSCアプリでサーバーが所有する状態	サーバーコンポーネント＋React cache	クライアントストアが必要なのは、インタラクティブ／楽観的UIの場合に限ります
URL駆動の状態（フィルター、ページネーション）	URL検索パラメーター	ストアに重複して保存しないでください

ローカル状態やサーバー駆動のパターンで十分な場合、新たなグローバル状態レイヤーを作成しないでください。

UI状態の網羅性ゲート

画面で実際に到達しうるすべての状態を列挙し、それぞれに意図的に対応してください。該当する場合、読み込み中、空、エラー、成功を基本とします。バックグラウンド更新、一部のみ取得済み、古いデータ、権限拒否、回復可能、終了状態の各パターンは、データおよび認可の契約上発生しうる場合にのみ追加してください。レビュー時には、該当しない状態も明示してください。適切な場合は、再試行をまたいでユーザーの入力と最後に安全に表示された状態を保持してください。

ハイドレーションとSSRの安全性

次の点に注意してください。

• SSR中にブラウザー専用の値を使用していないか
• サーバーコンポーネント内でクライアントフックを使用していないか
• エフェクトの依存関係が古くなっていないか
• リファクタリング後にルートやリンクがずれていないか

バグの原因がハイドレーションにありそうな場合は、references/production-gotchas.mdから確認してください。

リリースの規律

最低限のリリースゲート：

• 編集したファイルのリンターを実行する
• 変更した範囲の型チェックを行う（tsc --noEmitまたは同等のコマンド）
• 引き渡し前に、より広い範囲でリンター、型チェック、ビルドを一度実行する
• アクセシビリティゲート：自動チェックに加え、影響を受ける動作についてキーボード／支援技術で検証する。axe-coreのチェックに合格しただけでは、WCAG 2.2 AAへの適合は確認できません。WCAG 2.2では達成基準が追加されていますが、4.1.1「構文解析」は削除されています。ポリシーで2.1が求められる場合は、必要に応じて引き続きこの基準をテスト／報告してください。EU（EAA）：法的な参照基準となるのは、EU官報で引用されているEN 301 549のバージョンです。WCAG 2.2を採用した新しいバージョンも、引用されるまでは法的な最低基準ではありません。2.2 AAをエンジニアリング目標とし、引用状況はsoftware-accessibilityで確認してください
• パフォーマンス予算：ユーザー向けの経路において、ページ読み込みの75パーセンタイルでLCP ≤ 2.5s、INP ≤ 200ms、CLS ≤ 0.1を満たすこと（フィールドデータを使用し、モバイルとデスクトップを個別に測定）
• ハイドレーションを検証する：ページ遷移後、SSR／RSCページでコンソールエラーがないこと
• AI生成コードについて、フック規則違反、不十分なネイティブセマンティクス、不適切なARIAを確認する

AI生成フロントエンドのリスク

AI特有のフロントエンドでよくある問題：

• フック規則違反
• クライアント／サーバー境界の混同
• divだらけの構造と不十分なセマンティクス
• 古いクロージャーや依存関係の不足
• コンポーネントによる過剰なデータ取得
• キーボード操作やスクリーンリーダーへの対応不足
• プロジェクトの実際の依存関係ツリーに存在しないインポート、または存在していても、生成コードが想定するものとはバージョンやAPIの形が異なるインポート
• 既存のパターンに合わせる代わりに、リポジトリにすでにあるパターンを再実装するコンポーネント（モーダルの別実装や、並行するデータ取得ラッパーなど）

これらはまれな例外ではなく、想定して確認すべき不具合として扱ってください。AI生成のフロントエンドコードを受け入れる前に、そのコードの内部的なもっともらしさだけでなく、実際のコードベースに照らして検証してください。すべてのインポートがpackage.json／ロックファイル上で解決できること、使用するコンポーネント／フックのAPIがインストール済みのバージョンに合っていること（モデルの学習時に使われていた、より新しい、または古いバージョンではないこと）、スタイルとデータ取得が新たに競合する別のパターンを持ち込まず、リポジトリ内の慣習に合っていることを確認してください。

出力モード

以下のいずれかをデフォルトとして使用します。

• フロントエンド実装計画： フレームワーク、テンプレート、状態管理、テスト、リリースゲート。
• 問題の診断： 起こりそうなフロントエンドの障害モード、影響を受けるレイヤー、修正方法。
• スキャフォールドの推奨： フレームワークの選択、テンプレート、その理由。
• 本番環境向け強化の概要： ハイドレーション、パフォーマンス、アクセシビリティ、テストのチェックリスト。

よくある落とし穴

• SSR や RSC に対応したスタックで、サーバーとクライアントの境界を安易にまたぎ、レンダリングモデルに起因するハイドレーションの不一致を後からデバッグすること。
• サーバーレンダリング中にブラウザー専用の値を読み取り、フレームワークが安全に差異を調整してくれると思い込むこと。
• ローカル状態とサーバー状態向けのツールですでに問題を解決できるか確認せず、新しいグローバルストアを導入すること。
• SEO、ナビゲーションのセマンティクス、URL の挙動が維持されることを検証せず、ルート、リンク、レイアウト構成をリファクタリングすること。
• 見た目はもっともらしくても、セマンティクス、キーボード操作への対応、フックの正しさをひそかに損なう AI 生成コンポーネントの出力を受け入れること。インストール済みのバージョンでは解決できないインポートや、リポジトリですでに使っているパターンの隣に別のモーダルやフェッチのパターンを追加することも含まれます。
• レンダリングモデルとの適合性ではなく、流行を理由にフレームワークを選ぶこと。

ナビゲーション

• フレームワークのリファレンス：references/fullstack-patterns.md、references/vite-react-patterns.md、references/remix-react-patterns.md、references/vue-nuxt-patterns.md、references/angular-patterns.md、references/svelte-sveltekit-patterns.md
• 運用に関するリファレンス：references/production-gotchas.md、references/operational-playbook.md、references/state-management-patterns.md、references/testing-frontend-patterns.md、references/performance-optimization.md、references/web-platform-apis.md（ネイティブのブラウザー向け代替手段。機能検出で対応状況を確認してください）、references/artifacts-builder.md、references/mui-integration-notes.md（MUI テーマ、SSR、MUI X のライセンス、フォーム連携）
• テンプレート：assets/nextjs/template-nextjs-tailwind-shadcn.md、assets/vite-react/template-vite-react-ts.md、assets/remix/template-remix-react.md、assets/vue-nuxt/template-nuxt4-tailwind.md、assets/angular/template-angular21-standalone.md（スキャフォールド後のチェックリスト）、assets/svelte/template-sveltekit-runes.md
• 関連スキル：software-backend、software-ui-ux-design、software-localisation、qa-testing-playwright、ops-devops-platform

ソースのマッピングはdata/sources.jsonにあります。

学びのループ

過去の決定事項や落とし穴が関連する場合は、learnings.consolidated.mdがあれば参照してください。必要な履歴を確認する場合、または利用可能な代替ファイルとして使う場合に限り、learnings.mdを参照してください。それ以外の場合は、どちらも参照しないでください。

適用後、記憶に残す価値のあるパターン、再発防止が必要なミス、または意外だったドメイン知識に遭遇した場合は、agents-skills-feedback-loop/scripts/append_learning.pyを使って、日付付きの箇条書きをlearnings.mdに1つ追記してください。SKILL.md自体は変更しないでください。