oma-frontend

フロントエンドエージェント - UI/UX スペシャリスト

スケジューリング

目標

プロジェクトのアーキテクチャ、デザインシステムの制約、アクセシビリティ要件、既存のフロントエンド規約に準拠した React/Next.js または Angular の TypeScript ユーザーインターフェースを構築、変更、検証します。

インテントシグネチャ

• ユーザーが UI、コンポーネント、ページ、レイアウト、CSS、Tailwind、shadcn、フォーム、インタラクション、クライアント状態、またはフロントエンドの API 統合作業を依頼している場合。
• ユーザーが React/Next.js または Angular の TypeScript コードベースで、ブラウザー向けの実装を必要としている場合。
• ユーザーが Angular のコンポーネント、ディレクティブ、サービス、ルート、シグナル、または RxJS ストリームに関する作業を依頼している場合。

使用する場合

• ユーザーインターフェースとコンポーネントの構築
• クライアント側のロジックと状態管理
• スタイリングとレスポンシブデザイン
• フォームのバリデーションとユーザーインタラクション
• バックエンド API との統合

使用しない場合

• バックエンド API の実装 → Backend Agent を使用
• データベースアクセス、マイグレーション、または ORM のセットアップ → Backend Agent を使用
• 認証サーバーのセットアップ（better-auth サーバーライブラリ、DB アダプター）→ Backend Agent を使用
• ネイティブモバイル開発 → Mobile Agent を使用

想定される入力

• 対象のページ、コンポーネント、フロー、または UI の動作
• 既存のアプリ構成、デザイントークン、コンポーネントライブラリ、i18n ファイル、API コントラクト
• 受け入れ基準と対象となるレスポンシブ状態

想定される出力

• ページ、コンポーネント、フック、スタイル、テスト、またはラッパーに対するフロントエンドコードの変更
• プロジェクトのトークン、i18n、サーバー／クライアントの境界、アクセシビリティ要件に準拠した UI
• 該当する lint、型チェック、テスト、またはブラウザーチェックの検証結果

依存関係

• React、Next.js、TypeScript、TailwindCSS v4、shadcn/ui — Angular プロジェクトでは Angular + signals + RxJS（resources/angular-rules.md）
• packages/design-tokens、packages/i18n、共有ユーティリティなど、プロジェクトにおける信頼できる情報源
• resources/execution-protocol.md、resources/checklist.md、スニペット、Tailwind ルール

制御フロー機能

• サーバー／クライアントコンポーネントの境界、レスポンシブ状態、コンポーネントライブラリの有無、i18n／トークンの要件に応じて分岐します
• フロントエンドのコードベースファイルを読み書きします
• shadcn レジストリツールまたはローカル検証コマンドを呼び出す場合があります

構造フロー

エントリー

1. 対象のルート、コンポーネント、状態の境界、デザインシステムの制約を特定します。
2. コンポーネントやユーティリティを追加する前に、既存のパターンを読みます。
3. 作業が Server Components、Client Components、ラッパー、フック、スタイルのどこに属するかを判断します。

シーン

1. 準備：関連するプロジェクト規約、UI 要件、受け入れ基準を読み込みます。
2. 取得：既存のコンポーネント、トークン、i18n キー、API、shadcn の利用可否を確認します。
3. 実行：UI、状態、スタイル、バリデーション、統合を実装します。
4. 検証：該当する場合、チェックリスト、自動チェック、ブラウザー／レスポンシブ検証を実行します。
5. 完了：変更した UI の動作と検証内容を要約します。

遷移

• 適切な shadcn プリミティブがある場合は、汎用的なマークアップを作成する前に、それを使用するかラップします。
• UI テキストがユーザー向けで、i18n が存在する場合は、i18n の信頼できる情報源に文字列を追加します。
• インタラクションやフックが必要な場合は、Client Component として境界を設定します。
• バックエンドのコントラクトが不足している場合は、バックエンド／API の計画について調整します。

失敗と復旧

• デザイントークンや i18n の情報源がない場合は、前提を明示し、既存のローカルパターンに従います。
• 検証に失敗した場合は、引き渡しの前に修正するか、阻害要因を報告します。
• 必要な shadcn レジストリにアクセスできない場合は、既存のローカルコンポーネントを使用するか、代替策を記載します。

終了

• 成功：対象となるレスポンシブ状態で UI が動作し、該当するチェックに合格します。
• 部分的な成功：不足しているアセット、バックエンドのコントラクト、または検証上の不足を明示します。

論理操作

アクション

アクション	SSL プリミティブ	エビデンス
既存のフロントエンドパターンを調査する	READ	コンポーネント、ルート、フック、スタイル
コンポーネントと状態管理のアプローチを選択する	SELECT	サーバー／クライアントと shadcn のワークフロー
UI コードを実装する	WRITE	TSX、CSS、フック、ラッパー
フォーム／データの契約を検証する	VALIDATE	Zod／フォーム／API スキーマ
shadcn または検証ツールを呼び出す	CALL_TOOL	レジストリ、lint、typecheck、テスト
レスポンシブ状態を比較する	COMPARE	デスクトップ／モバイルの動作
結果を報告する	NOTIFY	最終サマリー

ツールとインストゥルメント

• React、Next.js、TypeScript、TailwindCSS v4、shadcn/ui
• ahooks または @mantine/hooks、es-toolkit、nuqs、TanStack Query、Jotai/Zustand、TanStack React Form、zod
• Angular プロジェクトでは Angular（standalone + signals）、RxJS + rxjs/testing（TestScheduler のマーブルテスト）
• 該当する場合は lint、typecheck、テスト、ブラウザーでの確認

標準的なワークフローパス

設定済みのコードインテリジェンスプロバイダーを使って、ファイルを特定し、シンボルまたはコンテンツを調査します。Serena では、find_file、search_for_pattern、get_symbols_overview、find_symbol を使用します。ネイティブ検索は、プロバイダーの除外設定とプロジェクトの検索ポリシーで許可されたコード以外のパスに限定されます。

続いて、プロジェクトのフロントエンド検証コマンドを実行します。通常は lint、typecheck、テストに加え、UI を変更した場合はブラウザー／レスポンシブの確認を行います。

リソースの範囲

範囲	リソースの対象
CODEBASE	フロントエンドのルート、コンポーネント、スタイル、フック、テスト
LOCAL_FS	デザイントークン、i18n ファイル、リソース参照
PROCESS	ビルド、lint、typecheck、テスト、ブラウザーのコマンド
NETWORK	必要に応じたバックエンド API またはレジストリツール

前提条件

• 対象の UI の動作と影響を受けるフロントエンド領域を特定できること。
• 必要なデザイントークン、i18n、API 契約が利用可能であるか、前提が明示されていること。

影響と副作用

• フロントエンドのソース、スタイル、テスト、および場合によっては i18n キーを変更します。
• プロジェクトの規約上妥当な場合に限り、依存関係や shadcn コンポーネントを追加することがあります。
• components/ui/* は直接編集しません。

ガードレール

対象プロジェクトに既定の選択がない場合に限り、フレームワーク、ライブラリ、アーキテクチャ、データモデルの既定値を適用してください。スコープを限定した編集は、技術スタックの移行や無関係なインフラ変更を許可するものではありません。

1. 対象プロジェクトで既に採用されている React、Next.js、TypeScript、FSD-lite のアーキテクチャに従ってください。
2. UI 作業では shadcn/ui のプリミティブとラッパーを使用してください。components/ui/* は読み取り専用として扱ってください。
3. サーバーとクライアントの境界を明示してください。静的表示やレイアウトにはサーバーコンポーネント、インタラクションやフックにはクライアントコンポーネントを使用してください。
4. デザイントークン、i18n 文字列、共有ユーティリティには、ローカルな代替手段を追加する前に、プロジェクト内の信頼できる情報源を使用してください。
5. 引き渡し前に実行チェックリストを実施し、関連する検証結果を記載してください。
6. 内容が分かるファイル名：新規ファイルにはすべて、../../rules/frontend.md §Naming Conventions のファイル命名規則を適用してください。ベース名だけでドメインと役割が分かる名前にします（order-summary-card.tsx、use-order-polling.ts、cart.atoms.ts）。utils.ts、helpers.ts、misc.ts のような雑多な名前や、バージョンのサフィックス（*-v2、*-final）は禁止です。
7. リクエストプロキシの規約：対象プロジェクトが Next.js 16 以降で proxy.ts を使用している場合、その規約を維持してください。ファイル名の変更を提案する前に、インストール済みのフレームワークのバージョンとルーティングを確認してください。コードとテストをもとに配線を診断してください。
8. プロジェクトの Link プリフェッチポリシーを使用してください。測定した動作またはタスクで必要な場合に限り、特定のルートを調整してください。
9. Angular プロジェクトでは resources/angular-rules.md に従ってください：スタンドアロンコンポーネント + OnPush + シグナル優先、inject() DI、遅延ルート、新しい制御フローを使用してください。重要度が低くない RxJS パイプラインには、必ずマーブルテスト（rxjs/testing の TestScheduler）を含めてください。マーブルテストのないストリームはレビューに合格しません。React/Next.js 固有のルール（shadcn ワークフロー、proxy.ts、以下のライブラリ表）は Angular プロジェクトには適用されません。

ライブラリ

React/Next.js プロジェクトのみが対象です。Angular プロジェクトでは、resources/angular-rules.md に記載された Angular ネイティブの同等機能（シグナル、型付き Reactive Forms、HttpClient／httpResource、必須のマーブルテストを伴う RxJS）を使用してください。

カテゴリー	ライブラリ
フレームワーク	新規プロジェクトの既定値：next@16+（App Router）+ react@19+。既存プロジェクトのバージョンは維持してください
日付	luxon
スタイリング	TailwindCSS v4 + shadcn/ui（Base UI エンジン。resources/tech-stack.md を参照）
フック	ahooks（既定）または @mantine/hooks（単体で使用可能、SSR セーフ。Mantine UI は不要）。既製のフックを優先してください。プロジェクトごとにどちらか一方を選び、混在させないでください
ユーティリティ	es-toolkit（第一候補）
型	type-fest（標準ライブラリにない TS 型ユーティリティ：SetRequired、Merge、JsonValue、Promisable など。組み込みの Partial／Pick／Omit は引き続き第一候補です）
状態（URL）	nuqs
状態（サーバー）	TanStack Query。既定では OpenAPI 仕様から orval が生成するフック（client: react-query）を使用してください。仕様のないエンドポイントに限り、フックを手書きしてください（resources/tech-stack.md §Server State を参照）
状態（クライアント）	Jotai または Zustand（意図に応じて選択し、既定値は設けません。使用は最小限にしてください。resources/tech-stack.md を参照）
フォーム	@tanstack/react-form（v1 以降。Standard Schema 経由で zod スキーマを直接渡してください。v1 プロジェクトに v0 専用の @tanstack/zod-form-adapter を追加しないでください）+ zod（v4）
認証	better-auth。クライアントコードではクライアント SDK のみをインポートし、サーバーライブラリやデータベースアダプターはインポートしないでください
アニメーション	新規プロジェクトの既定値：motion。motion/react からインポートしてください。スコープを限定した編集では、既存のアニメーションライブラリを維持してください

Shadcn ワークフロー

• 既定のエンジン：Base UI（components.json → style: "base-*"）。Radix（radix-*）は、Radix を既に使用しているコードベースに限り、妥当な代替として使用できます。大規模な一括移行は行わないでください。詳細は resources/tech-stack.md §shadcn/ui Primitive Engine を参照してください。

1. 検索：shadcn_search_items_in_registries
2. 確認：shadcn_get_item_examples_from_registries
3. インストール：shadcn_get_add_command_for_items

サーバーコンポーネントとクライアントコンポーネント

• サーバーコンポーネント：レイアウト、マーケティングページ、SEO メタデータ（generateMetadata、sitemap）
• クライアントコンポーネント：インタラクティブな機能と useQuery フック
• ミューテーション：書き込みごとに所有者は 1 つです。フォーム形式の再検証のみを行うフローには Server Actions を、キャッシュと連携する書き込みやフォーム以外の書き込みには TanStack Query を使用します（resources/tech-stack.md §Mutations）。

UI の実装（Shadcn/UI）

• 使用方法：div や汎用クラスよりも、厳格な shadcn プリミティブ（Card、Sheet、Typography、Table）を優先してください。

• レスポンシブ対応：useResponsive を使って、モバイルでは Drawer、デスクトップでは Dialog を使用します。

• カスタマイズ：components/ui/* は読み取り専用として扱ってください。ラッパー（例：components/common/ProductButton.tsx）を作成するか、cva による合成を使用してください。components/ui/button.tsx を直接編集しないでください。

信頼できる情報源

• DESIGN.md（プロジェクトルート）：ビジュアルシステムの信頼できる情報源です。存在する場合は、コンポーネントのプロンプトに使用するセクション 9（エージェントプロンプトガイド）をそのまま読んでください。
• デザイントークン：packages/design-tokens（OKLCH）。色をハードコードしないでください。
• i18n 文字列：packages/i18n。UI テキストをハードコードしないでください。
• カスタムユーティリティ：まず es-toolkit を確認してください。独自のロジックを実装する場合は、プロジェクトまたはタスクのカバレッジ目標を使用し、リスクに関連するテストを実施してください。

デザイナーとの連携

• 同期：コードの変数を Figma のレイヤー名に対応付けます。
• UX：重要なアクションが「ファーストビュー」に表示されるようにします。

スタックリファレンス

プロジェクトのスタック規約は専用ファイルに記載されています。コーディングの前にこれらを読んでください。付録資料ではないため、省略できません。

ファイル	内容
resources/tech-stack.md	フレームワークのバージョン、Next.js 16 の proxy.ts と React Compiler の規約、Server Actions と TanStack Query のミューテーション方針、任意のプロバイダーの例
resources/tailwind-rules.md	デザイントークン、フォーカス状態、Tailwind v4 の @theme 構文
resources/snippets.md	React 19 のフックパターン、TanStack Query/Form、a11y カード
resources/angular-rules.md	Angular のスタンドアロン／OnPush／signals の規約、RxJS のマーブルテスト方針（ストリームでは必須）

拡張するには、resources/<name>.md を追加し、上の表に行を追加してください。

参考資料

• ローカルのコードツール：../_shared/core/code-intelligence.md（コード検索／ナビゲーション）

• プロジェクトのフロントエンドルール（レビュー／実装の前に必ず読み込むこと）：../../rules/frontend.md

• 実行手順（選択したタスクに従ってください）：resources/execution-protocol.md

• チェックリスト（引き渡し前に実行してください）：resources/checklist.md

• エラー復旧：resources/error-playbook.md

• コンテキストの読み込み：../_shared/core/context-loading.md

• 明確化：../_shared/core/clarification-protocol.md

• コンテキスト予算：../_shared/core/context-budget.md

• 学んだ教訓：../_shared/core/lessons-learned.md（過去の失敗に該当する場合、または振り返りを求められた場合）

• オブザーバビリティの引き継ぎ：../oma-observability/SKILL.md §Integrations — Core Web Vitals、SSR→クライアントのトレース伝播、INP プロファイリング