moai-domain-frontend

フロントエンド開発スペシャリスト

クイックリファレンス

モダンなフロントエンド開発 — React 19、Next.js 16、Vue 3.5 の包括的なパターンです。

主な機能：

• React 19：サーバーコンポーネント、並行処理機能、cache()、Suspense
• Next.js 16：App Router、Server Actions、ISR、Route ハンドラー
• Vue 3.5：Composition API、TypeScript、Pinia による状態管理
• コンポーネントアーキテクチャ：デザインシステム、複合コンポーネント、CVA
• パフォーマンス：コード分割、動的インポート、メモ化、Framer Motion アニメーション

使用する場面：

• モダンなウェブアプリケーションの開発
• コンポーネントライブラリの作成
• フロントエンドのパフォーマンス最適化
• アクセシビリティに配慮した UI/UX

---

パターン

フレームワークパターン

React 19 のパターン：

• サーバーコンポーネント、並行処理機能、cache() API、フォーム処理

Next.js 16 のパターン：

• App Router、Server Actions、ISR、Route ハンドラー、Parallel Routes

Vue 3.5 のパターン：

• Composition API、コンポーザブル、リアクティビティ、Pinia、Provide/Inject

アーキテクチャパターン

コンポーネントアーキテクチャ：

• デザイントークン、CVA バリアント、複合コンポーネント、アクセシビリティ

状態管理：

• Zustand、Redux Toolkit、React Context、Pinia

パフォーマンス最適化：

• コード分割、動的インポート、画像最適化、メモ化

AI 支援フロントエンドのパターン：

• ビジュアルリファレンス戦略、Playwright による検証、モーションデザイン、推論レベルの調整

Vercel React のベストプラクティス：

• Vercel Engineering による 8 カテゴリ、45 のルール
• ウォーターフォールの排除、バンドルの最適化、サーバーサイドのパフォーマンス
• クライアントサイドのデータ取得、再レンダーの最適化、レンダリングパフォーマンス

---

実装クイックスタート

React 19 サーバーコンポーネント

React の cache 関数を使用してデータ取得をメモ化する、非同期のページコンポーネントを作成します。ローディング状態に使用する Suspense をインポートします。id パラメーターを使って API エンドポイントからデータを取得し、JSON を返す getData 関数を定義します。ページコンポーネントでは、DataDisplay コンポーネントを Skeleton フォールバック付きの Suspense でラップし、getData の結果を await して data プロパティとして渡します。

Next.js Server Action

use server ディレクティブを含む Server Action ファイルを作成します。next/cache から revalidatePath を、検証用に zod から z をインポートします。title（最小 1 文字）と content（最小 10 文字）を含むスキーマを定義します。createPost 関数は FormData を受け取り、safeParse で検証します。失敗時にはエラーを返し、データベースに投稿を作成して、投稿ページに対して revalidatePath を呼び出します。

Vue コンポーザブル

userId ref パラメーターを受け取る useUser コンポーザブルを作成します。user を null 許容の ref、loading をブール値の ref として定義し、firstName と lastName を連結する computed プロパティとして fullName を定義します。watchEffect を使って loading を true に設定し、ユーザーデータを非同期で取得して user ref に代入し、loading を false に設定します。user、loading、fullName の各 ref を返します。

CVA コンポーネント

class-variance-authority から cva と VariantProps をインポートします。inline-flex、items-center、justify-center、rounded-md、font-medium のベースクラスを指定した buttonVariants を定義します。variant オプションに、default（ホバー時のスタイルを含むプライマリ背景）と outline（ホバー時のアクセント付きボーダー）を指定した variants オブジェクトを追加します。サイズオプションには、sm（h-9、px-3、text-sm）、default（h-10、px-4）、lg（h-11、px-8）を追加します。variant と size に defaultVariants を設定します。variants をボタン要素の className に適用する Button コンポーネントをエクスポートします。

---

相性の良いツール

• moai-domain-backend - フルスタック開発
• moai-ref-ui-polish - コンポーネントライブラリの統合
• moai-ref-ui-polish - UI/UX デザインの原則
• .claude/rules/moai/languages/typescript.md - TypeScript のパターン（paths frontmatter により自動読み込み）
• moai-workflow-testing - フロントエンドのテスト

---

技術スタック

フレームワーク：React 19、Next.js 16、Vue 3.5、Nuxt 3

言語：TypeScript 5.9+、JavaScript ES2024

スタイリング：Tailwind CSS 3.4+、CSS Modules、shadcn/ui

アニメーション：Framer Motion

状態管理：Zustand、Redux Toolkit、Pinia

テスト：Vitest、Testing Library、Playwright

検証：Playwright（目視検査、機能テスト）

---

リソース

公式ドキュメント：

• React：https://react.dev/
• Next.js：https://nextjs.org/docs
• Vue：https://vuejs.org/

---

バージョン：2.1.0

よくある誤った正当化

誤った正当化	実際
「アクセシビリティはリリース後に追加すればよい」	リリース後のアクセシビリティ対応は追加ではなく、書き直しになります。セマンティック HTML と ARIA は装飾ではなく、基盤となるものです。
「このコンポーネントは単純なので、独自のテストは必要ない」	単純なコンポーネントを組み合わせると複雑な UI になります。単純なコンポーネントが壊れると、使用されているあらゆる場所で障害が連鎖します。
「サーバーコンポーネントは常に高速」	サーバーコンポーネントではネットワークの往復が発生します。適切にキャッシュされたクライアントコンポーネントは、単純なサーバーコンポーネントより高い性能を発揮することがあります。思い込まず、測定してください。
「今のところ、TypeScript の型には any を使えばよい」	any を使うと、それ以降のすべてに対して型チェッカーが無効になります。1 つの any が呼び出しチェーン全体に影響します。
「このプロジェクトではグローバル CSS で問題ない」	プロジェクトの拡大に伴い、グローバル CSS は詳細度の競合を引き起こします。スコープ化されたスタイル（CSS modules、Tailwind）を使うと、衝突を防げます。

危険信号

• ユーザー提供の HTML をサニタイズせずにコンポーネントがレンダリングしている（XSS の脆弱性）
• コンポーネントの props または状態の定義に TypeScript の any 型が使われている
• 非同期データを取得するコンポーネントに、ローディング状態やエラー状態が定義されていない
• インタラクティブ要素にアクセシビリティ属性（aria-label、role）がない
• 正当な理由なくバンドルサイズが 50KB を超えて増加している
• サブコンポーネントに分割されず、コンポーネントが 300 行を超えている

検証

• すべてのインタラクティブ要素に、アクセシブルな名前（aria-label または表示テキスト）がある
• コンポーネントがローディング、エラー、空の状態に対応している
• 新規コードまたは変更したコードに TypeScript の any がない（grep の結果を提示する）
• 新しい依存関係がバンドルサイズに与える影響を測定している（アナライザーの出力を提示する）
• ユーザー提供のコンテンツを適切なエスケープまたはサニタイズ処理を施してレンダリングしている
• コンポーネントが 300 行未満であるか、明確な境界を設けてサブコンポーネントに分割されている