フロントエンドエージェントスキル
⚠️ 事前生成チェックリスト(必須)
UIコンポーネントを作成する前に、このチェックリストを完了してください:
事前生成チェックリスト:
1. デザインシステムを読む:
- [ ] /DESIGN-SYSTEM.md で禁止パターンを確認
- [ ] /src/app/globals.css の @theme ブロックでトークンを確認
- [ ] 注意: accent-500 = #ff6b35(オレンジ)
2. 既存コンポーネントを確認:
- [ ] まず /src/components/ui/ を確認(48コンポーネント)
- [ ] components.json でshadcn設定を確認
- [ ] ランディングページの既存パターンを確認
3. UIライブラリを参照:
- [ ] /docs/UI-LIBRARY-INDEX.md でプレミアムコンポーネントを確認
- [ ] 優先順位: プロジェクト → StyleUI/KokonutUI/Cult UI → shadcnベース
- [ ] カスタマイズせずにshadcnのデフォルトを使用しないでください
4. 禁止パターンがないことを確認:
- [ ] bg-white、text-gray-600、またはジェネリックなホバー状態は不可
- [ ] 均一な grid-cols-3 gap-4 レイアウトは不可
- [ ] スタイルなしの <Card className="p-6"> は不可
- [ ] ブランドカラーのないアイコンは不可
禁止コードパターン:
// ❌ 絶対に生成しないでください
className="bg-white rounded-lg shadow p-4" // ジェネリックなカード
className="grid grid-cols-3 gap-4" // 均一なグリッド
className="text-gray-600" // デフォルトのミュート
className="hover:bg-gray-100" // ジェネリックなホバー
<Card className="p-6"> // スタイルなしのshadcn
必須パターン:
// ✅ 常にデザイントークンを使用
className="bg-bg-card border border-border-base hover:border-accent-500"
className="text-text-primary"
className="text-text-secondary"
className="bg-accent-500 hover:bg-accent-400"
概要
フロントエンドエージェントは、Unite-Hub Next.jsアプリケーションにおけるすべてのUI/UX作業を担当します:
- React 19 / Next.js 16 開発(App Router)
- shadcn/uiコンポーネントの実装とカスタマイズ
- Tailwind CSSスタイリングとレスポンシブデザイン
- ルート作成とパンくずリストの設定
- クライアントサイドの状態管理(React Context、フック)
- アクセシビリティとパフォーマンスの最適化
このエージェントの使い方
トリガー
ユーザーが言う:「ダッシュボードのレイアウトを修正して」「新しい連絡先ページを追加して」「ナビゲーションを更新して」「モーダルコンポーネントを作成して」
エージェントの動作
1. リクエストを理解する
質問事項:
- どのページ/コンポーネントに作業が必要ですか?
- 望ましい動作は何ですか?
- デザインの参考資料(スクリーンショット、ワイヤーフレーム)はありますか?
- 優先度は何ですか(P0/P1/P2)?
2. 現在の実装を分析する
ステップA: ファイルを見つける
# コンポーネントまたはページを見つける
find src/app -name "*.tsx" | grep -i "contacts"
find src/components -name "*.tsx" | grep -i "hotleads"
ステップB: 現在のコードを読む
// text_editorツールを使用
text_editor.view("src/app/dashboard/contacts/page.tsx")
ステップC: 依存関係を特定する
- どのshadcn/uiコンポーネントが使用されていますか?
- どのコンテキストが消費されていますか(AuthContextなど)?
- どのAPIルートが呼び出されていますか?
- どのデータベースクエリが実行されていますか?
3. 変更を実装する
ステップA: コンポーネントの更新
既存コンポーネントの場合:
// src/components/HotLeadsPanel.tsx
import { Button } from "@/components/ui/button";
import { Card } from "@/components/ui/card";
import { useAuth } from "@/contexts/AuthContext";
export function HotLeadsPanel({ workspaceId }: { workspaceId: string }) {
const { currentOrganization } = useAuth();
// ホットリードを取得
const [leads, setLeads] = useState([]);
useEffect(() => {
async function fetchLeads() {
const res = await fetch("/api/agents/contact-intelligence", {
method: "POST",
body: JSON.stringify({ action: "get_hot_leads", workspaceId }),
});
const data = await res.json();
setLeads(data.leads || []);
}
if (workspaceId) fetchLeads();
}, [workspaceId]);
return (
<Card>
{/* UI実装 */}
</Card>
);
}
ステップB: ルート作成
新しいページの場合:
// src/app/dashboard/new-page/page.tsx
import { Metadata } from "next";
export const metadata: Metadata = {
title: "新規ページ | Unite Hub",
description: "新規ページの説明"
};
export default async function NewPage() {
return (
<div className="container mx-auto py-8">
<h1 className="text-3xl font-bold">新規ページ</h1>
{/* コンテンツ */}
</div>
);
}
ステップC: shadcn/uiコンポーネント
必要に応じて新しいコンポーネントをインストール:
npx shadcn@latest add dialog
npx shadcn@latest add dropdown-menu
npx shadcn@latest add toast
shadcnパターンに従ってコンポーネントを使用:
import {
Dialog,
DialogContent,
DialogDescription,
DialogHeader,
DialogTitle,
DialogTrigger,
} from "@/components/ui/dialog";
<Dialog>
<DialogTrigger asChild>
<Button>ダイアログを開く</Button>
</DialogTrigger>
<DialogContent>
<DialogHeader>
<DialogTitle>タイトル</DialogTitle>
<DialogDescription>説明</DialogDescription>
</DialogHeader>
{/* コンテンツ */}
</DialogContent>
</Dialog>
4. ワークスペースフィルタリングを追加(V1では重要)
すべてのデータベースクエリはワークスペースでフィルタリングする必要があります:
// ❌ 悪い例 - すべてのワークスペースのデータを表示
const { data: contacts } = await supabase
.from("contacts")
.select("*");
// ✅ 良い例 - ユーザーのワークスペースのデータのみを表示
const { data: contacts } = await supabase
.from("contacts")
.select("*")
.eq("workspace_id", workspaceId);
以下のテーブルで必須:
contacts-.eq("workspace_id", workspaceId)campaigns-.eq("workspace_id", workspaceId)drip_campaigns-.eq("workspace_id", workspaceId)emails-.eq("workspace_id", workspaceId)generatedContent-.eq("workspace_id", workspaceId)
5. ローディングとエラー状態を処理
ローディング状態:
const [isLoading, setIsLoading] = useState(true);
const [error, setError] = useState<string | null>(null);
useEffect(() => {
async function fetchData() {
try {
setIsLoading(true);
const data = await fetch("...");
setData(data);
} catch (err) {
setError(err.message);
} finally {
setIsLoading(false);
}
}
fetchData();
}, []);
if (isLoading) return <Spinner />;
if (error) return <ErrorBanner message={error} />;
return <DataDisplay data={data} />;
6. レスポンシブデザイン
Tailwindブレークポイント:
<div className="
grid grid-cols-1 // モバイル: 1列
md:grid-cols-2 // タブレット: 2列
lg:grid-cols-3 // デスクトップ: 3列
gap-4
">
{/* カード */}
</div>
モバイルファーストアプローチ:
- モバイルレイアウトから開始(デフォルトクラス)
- タブレットには
md:クラスを追加 - デスクトップには
lg:とxl:を追加
7. 変更をテスト
ステップA: ビジュアルテスト
# 開発サーバーを起動
npm run dev
# ブラウザでページに移動
# モバイルビューポートでテスト(DevTools)
# ダークテーマをテスト
ステップB: アクセシビリティ
// 以下を確認:
// - 適切なARIAラベル
// - キーボードナビゲーション
// - フォーカス状態
// - スクリーンリーダーサポート
<button aria-label="ダイアログを閉じる">×</button>
<input aria-describedby="email-help" />
<div role="alert" aria-live="polite">{error}</div>
ステップC: パフォーマンス
// 負荷の高いコンポーネントにはReact.memoを使用
import { memo } from "react";
export const ExpensiveComponent = memo(function ExpensiveComponent({ data }) {
return <div>{/* レンダリング */}</div>;
});
// 重いコンポーネントには動的インポートを使用
import dynamic from "next/dynamic";
const HeavyChart = dynamic(() => import("@/components/HeavyChart"), {
loading: () => <Spinner />,
ssr: false
});
一般的なタスク
タスク1: 欠落しているワークスペースフィルターを修正
例: ダッシュボード概要ページですべての連絡先が表示される
手順:
src/app/dashboard/overview/page.tsxを読む- すべてのSupabaseクエリを見つける
- 各クエリに
.eq("workspace_id", workspaceId)を追加 - クエリの前にworkspaceIdのnullチェックを追加
- 複数のワークスペースでテスト
コード:
// 修正前
const { data: contacts } = await supabase.from("contacts").select("*");
// 修正後
if (!workspaceId) {
return <div>ワークスペースが選択されていません</div>;
}
const { data: contacts, error } = await supabase
.from("contacts")
.select("*")
.eq("workspace_id", workspaceId);
if (error) {
console.error("連絡先の取得エラー:", error);
return <ErrorBanner />;
}
タスク2: 新しいダッシュボードページを作成
例: ダッシュボードに「アナリティクス」ページを追加
手順:
src/app/dashboard/analytics/page.tsxを作成src/app/dashboard/layout.tsxのナビゲーションに追加- shadcn/ui コンポーネントを使用してページコンテンツを実装
- パンくずリストを追加
- ナビゲーションをテスト
コード:
// src/app/dashboard/analytics/page.tsx
import { Metadata } from "next";
import { Card } from "@/components/ui/card";
export const metadata: Metadata = {
title: "アナリティクス | Unite Hub",
};
export default async function AnalyticsPage() {
return (
<div className="container mx-auto py-8 space-y-6">
<div>
<h1 className="text-3xl font-bold">アナリティクス</h1>
<p className="text-muted-foreground">キャンペーンのパフォーマンスを追跡</p>
</div>
<div className="grid grid-cols-1 md:grid-cols-3 gap-6">
<Card>
{/* 統計カード1 */}
</Card>
<Card>
{/* 統計カード2 */}
</Card>
<Card>
{/* 統計カード3 */}
</Card>
</div>
</div>
);
}
// src/app/dashboard/layout.tsx - ナビゲーションに追加
const navigation = [
{ name: "ダッシュボード", href: "/dashboard/overview", icon: HomeIcon },
{ name: "連絡先", href: "/dashboard/contacts", icon: UsersIcon },
{ name: "キャンペーン", href: "/dashboard/campaigns", icon: MailIcon },
{ name: "アナリティクス", href: "/dashboard/analytics", icon: ChartIcon }, // 新規
];
タスク3: ボタン機能を実装
例: ホットリードパネルの「メール送信」ボタン
手順:
src/components/HotLeadsPanel.tsxを読む- ボタンの位置を見つける
- onClickハンドラーを実装
- 適切なAPIエンドポイントを呼び出す
- 成功/エラートーストを表示
コード:
import { useToast } from "@/components/ui/use-toast";
function HotLeadsPanel() {
const { toast } = useToast();
async function handleSendEmail(contactId: string) {
try {
const res = await fetch("/api/emails/send", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ contactId, templateType: "followup" }),
});
if (!res.ok) throw new Error("メールの送信に失敗しました");
toast({
title: "メール送信完了",
description: "メールが送信キューに追加されました。",
});
} catch (error) {
toast({
variant: "destructive",
title: "エラー",
description: error.message,
});
}
}
return (
<Button onClick={() => handleSendEmail(contact.id)}>
メール送信
</Button>
);
}
スタイリングガイドライン
Tailwind CSSのベストプラクティス
ユーティリティクラスを使用:
// ✅ 良い例
<div className="flex items-center justify-between p-4 bg-background border rounded-lg">
// ❌ 悪い例(カスタムCSS)
<div style={{ display: "flex", padding: "16px" }}>
テーマのCSS変数を使用:
// globals.css で定義
@layer base {
:root {
--background: 0 0% 100%;
--foreground: 222.2 84% 4.9%;
--card: 0 0% 100%;
--primary: 222.2 47.4% 11.2%;
}
}
// コンポーネントで使用
<div className="bg-background text-foreground">
<div className="bg-card text-card-foreground">
<div className="bg-primary text-primary-foreground">
レスポンシブデザイン:
<div className="
text-sm md:text-base lg:text-lg
p-2 md:p-4 lg:p-6
grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3
">
コンポーネントライブラリリファレンス
利用可能なshadcn/uiコンポーネント
accordion- 折りたたみ可能なコンテンツパネルalert-dialog- モーダル確認ダイアログavatar- ユーザープロフィール画像badge- ステータスバッジbutton- インタラクティブなボタンcard- コンテンツコンテナcheckbox- フォームチェックボックスdialog- モーダルダイアログdropdown-menu- ドロップダウンメニューinput- テキスト入力label- フォームラベルpopover- フローティングコンテンツprogress- 進捗インジケーターradio-group- ラジオボタンselect- セレクトドロップダウンswitch- トグルスイッチtabs- タブ付きインターフェースtoast- 通知トーストtooltip- ホバーツールチップ
新しいコンポーネントをインストール:
npx shadcn@latest add [component-name]
エラーハンドリングパターン
APIエラー
try {
const res = await fetch("/api/...");
const data = await res.json();
if (!res.ok) {
throw new Error(data.error || "問題が発生しました");
}
return data;
} catch (error) {
console.error("APIエラー:", error);
toast({
variant: "destructive",
title: "エラー",
description: error.message,
});
return null;
}
Supabaseエラー
const { data, error } = await supabase.from("contacts").select("*");
if (error) {
console.error("Supabaseエラー:", error);
return <ErrorBanner message="連絡先の読み込みに失敗しました" />;
}
if (!data || data.length === 0) {
return <EmptyState message="連絡先が見つかりません" />;
}
return <ContactsList contacts={data} />;
バージョン1の制約
V1で修正するもの:
- ✅ 全ページでのワークスペースフィルタリング
- ✅ ホットリードボタン機能
- ✅ 連絡先詳細ページのナビゲーション
- ✅ ダッシュボード統計カード
- ✅ ローディングおよびエラー状態
- ✅ レスポンシブデザインの修正
V1で構築しないもの:
- ❌ 高度なアニメーション
- ❌ カスタムテーマビルダー
- ❌ ドラッグ&ドロップインターフェース
- ❌ リアルタイムコラボレーションUI
- ❌ モバイルアプリ
重要なポイント
- 常にワークスペースでフィルタリング - データの分離は重要
- shadcn/uiコンポーネントを使用 - 車輪の再発明をしない
- Tailwindの規則に従う - ユーティリティファーストアプローチ
- ローディング/エラー状態を処理 - 空白の画面を表示しない
- レスポンシブデザインをテスト - モバイル、タブレット、デスクトップ