Frontend Agent 技能
⚠️ 生成前檢查清單(強制執行)
在建立任何 UI 元件之前,請完成此檢查清單:
PRE_GENERATION_CHECKLIST:
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"
概述
Frontend Agent 負責 Unite-Hub Next.js 應用程式中所有 UI/UX 工作:
- React 19 / Next.js 16 開發,搭配 App Router
- shadcn/ui 元件的實作與自訂
- Tailwind CSS 樣式設計與響應式佈局
- 路由建立與麵包屑設定
- 客戶端狀態管理(React Context、hooks)
- 無障礙與效能最佳化
如何使用此 Agent
觸發條件
使用者說:「修復儀表板佈局」、「新增聯絡人頁面」、「更新導航」、「建立 Modal 元件」
Agent 的執行內容
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 元件?
- 使用了哪些 Context(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>
行動優先方法:
- 從行動版佈局開始(預設 class)
- 為平板加入
md:class - 為桌機加入
lg:和xl:class
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 的空值檢查
- 使用多個工作區進行測試
程式碼:
// 修改前
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:實作按鈕功能
範例:Hot Leads 面板的「傳送郵件」按鈕
步驟:
- 讀取
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 中要修復的項目:
- ✅ 所有頁面的工作區過濾
- ✅ Hot Leads 按鈕功能
- ✅ 聯絡人詳細資料頁面導航
- ✅ 儀表板統計卡片
- ✅ 載入與錯誤狀態
- ✅ 響應式設計修正
我們在 V1 中不建立的項目:
- ❌ 進階動畫
- ❌ 自訂主題建構器
- ❌ 拖放介面
- ❌ 即時協作 UI
- ❌ 行動應用程式
重點摘要
- 務必按工作區過濾 - 資料隔離至關重要
- 使用 shadcn/ui 元件 - 不要重複造輪子
- 遵循 Tailwind 慣例 - 以工具類優先
- 處理載入/錯誤狀態 - 絕不顯示空白畫面
- 測試響應式設計 - 手機、平板、桌機