Communitygithub.com

ComeOnOliver/skillshub

負責 Unite-Hub 的前端/UX/路由工作,修復 UI 錯誤、實作 React 元件、更新佈局、確保響應式設計,並維持 shadcn/ui 的一致性。

skillshub 是什麼?

這個 Frontend Agent 技能(Skill)專為 Unite-Hub Next.js 應用程式設計,負責所有與 UI/UX 相關的任務。它能協助開發者在 React 19 / Next.js 16 的 App Router 架構下,有效率地修復 UI 錯誤、實作並自訂 shadcn/ui 元件、更新版面佈局,並確保設計符合 Tailwind CSS 的響應式規範。此技能同時支援 Cursor 和 Claude Code 等 AI 代理平台。 其工作流程包含一個強制性的「生成前檢查清單」,要求代理在建立任何 UI 元件前,必須先讀取設計系統文件、檢查現有元件庫、參考進階 UI 庫(如 KokonutUI),並確認沒有使用禁止的程式碼模式(例如 `bg-white` 或 `grid-cols-3 gap-4` 等通用樣式)。此外,該技能特別強調工作區(workspace)過濾,確保所有資料庫查詢(包括 contacts、campaigns、emails 等)都必須根據使用者所屬的工作區來隔離資料,這是 V1 版本的關鍵約束條件。 技能文件也詳細說明了常見任務的實作步驟,例如修復遺漏的工作區過濾、建立新的儀表板頁面、以及為按鈕新增功能(如發送郵件)。它還提供了全面的 Loading 與 Error 狀態處理模式、無障礙(Accessibility)檢查清單、以及效能最佳化技巧(如使用 React.memo 和動態匯入)。透過遵循這些規範,開發者可以確保應用程式的 UI 一致、安全且易於維護。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ComeOnOliver/skillshub/tree/HEAD/skills/aiskillstore/marketplace/cleanexpo/frontend-agent

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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 工作:

  1. React 19 / Next.js 16 開發,搭配 App Router
  2. shadcn/ui 元件的實作與自訂
  3. Tailwind CSS 樣式設計與響應式佈局
  4. 路由建立與麵包屑設定
  5. 客戶端狀態管理(React Context、hooks)
  6. 無障礙與效能最佳化

如何使用此 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:修復遺漏的工作區過濾

範例:儀表板總覽頁面顯示所有聯絡人

步驟:

  1. 讀取 src/app/dashboard/overview/page.tsx
  2. 找出所有 Supabase 查詢
  3. 對每個查詢加入 .eq("workspace_id", workspaceId)
  4. 在查詢前加入 workspaceId 的空值檢查
  5. 使用多個工作區進行測試

程式碼:

// 修改前
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:建立新的儀表板頁面

範例:在儀表板中加入「分析」頁面

步驟:

  1. 建立 src/app/dashboard/analytics/page.tsx
  2. 在 src/app/dashboard/layout.tsx 的導航中加入該頁面
  3. 使用 shadcn/ui 元件實作頁面內容
  4. 加入麵包屑
  5. 測試導航

程式碼:

// 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 面板的「傳送郵件」按鈕

步驟:

  1. 讀取 src/components/HotLeadsPanel.tsx
  2. 找到按鈕位置
  3. 實作 onClick 處理函式
  4. 呼叫適當的 API 端點
  5. 顯示成功/錯誤提示訊息

程式碼:

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 慣例 - 以工具類優先
  • 處理載入/錯誤狀態 - 絕不顯示空白畫面
  • 測試響應式設計 - 手機、平板、桌機

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

ComeOnOliver/skillshub

Create stunning, animation-rich HTML presentations from scratch or by converting PowerPoint files. Use when the user wants to build a presentation, convert a PPT/PPTX to web, or create slides for a talk/pitch. Helps non-designers discover their aesthetic through visual exploration rather than abstract choices.

ComeOnOliver/skillshub

Next.js 16+ 和 Turbopack — 增量打包、文件系统缓存、开发速度,以及何时使用 Turbopack 与 webpack。

ComeOnOliver/skillshub

SwiftUI architecture patterns, state management with @Observable, view composition, navigation, performance optimization, and modern iOS/macOS UI best practices.

ComeOnOliver/skillshub

See, Understand, Act on video and audio. See- ingest from local files, URLs, RTSP/live feeds, or live record desktop; return realtime context and playable stream links. Understand- extract frames, build visual/semantic/temporal indexes, and search moments with timestamps and auto-clips. Act- transcode and normalize (codec, fps, resolution, aspect ratio), perform timeline edits (subtitles, text/image overlays, branding, audio overlays, dubbing, translation), generate media assets (image, audio, video), and create real time alerts for events from live streams or desktop capture.

ComeOnOliver/skillshub

AI-assisted video editing workflows for cutting, structuring, and augmenting real footage. Covers the full pipeline from raw capture through FFmpeg, Remotion, ElevenLabs, fal.ai, and final polish in Descript or CapCut. Use when the user wants to edit video, cut footage, create vlogs, or build video content.

ComeOnOliver/skillshub

Next.js 15 애플리케이션을 위한 프론트엔드 개발 가이드라인. React 19, TypeScript, Shadcn/ui, Tailwind CSS를 사용한 모던 패턴. Server Components, Client Components, App Router, 파일 구조, Shadcn/ui 컴포넌트, 성능 최적화, TypeScript 모범 사례 포함. 컴포넌트, 페이지, 기능 생성, 데이터 페칭, 스타일링, 라우팅, 프론트엔드 코드 작업 시 사용.

ComeOnOliver/skillshub

Provides Tamagui patterns for config v4, compiler optimization, styled context, and cross-platform styling. Must use when working with Tamagui projects (tamagui.config.ts, @tamagui imports).

ComeOnOliver/skillshub

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.

ComeOnOliver/skillshub

Create high-converting, visually distinctive landing pages. Use when building marketing pages, product launches, SaaS homepages, or any single-page conversion-focused website. Guides section-by-section composition with anti-AI-slop principles.

ComeOnOliver/skillshub

Auto-loaded context for Portfolio Buddy 2 development. Use for ANY task involving: React 19 development, TypeScript, portfolio analysis features, metrics calculations, trading strategy comparison, or working with the Portfolio Buddy 2 codebase. Contains tech stack, known issues, and architectural constraints.

ComeOnOliver/skillshub

Next.js development tooling via MCP. Inspect routes, components, build info, and debug Next.js apps. Use when working on Next.js applications, debugging routing, or inspecting app structure. NOT for general React or non-Next.js projects.

ComeOnOliver/skillshub

Implement UI using Shadcn MCP (atoms/theme) and 21st.dev MCP (complex sections). Use when adding buttons, layouts, or generating landing pages.

ComeOnOliver/skillshub

A conceptual skill for building an API client in Next.js that handles JWT tokens

ComeOnOliver/skillshub

Best practices and patterns for Next.js App Router, Server Actions, and Routing in this project.

ComeOnOliver/skillshub

The Design System, Theme, and UX rules for the Physical AI Hub.

ComeOnOliver/skillshub

Comprehensive frontend development skill for building modern, performant web applications using ReactJS, NextJS, TypeScript, Tailwind CSS. Includes component scaffolding, performance optimization, bundle analysis, and UI best practices. Use when developing frontend features, optimizing performance, implementing UI/UX designs, managing state, or reviewing frontend code.

ComeOnOliver/skillshub

This document captures learnings from fixing keyboard navigation issues when floating components (Select, DropdownMenu, Popover) have CSS open/close animations.

ComeOnOliver/skillshub

Build Next.js 16 applications with correct patterns and distinctive design. Use when creating pages, layouts, dynamic routes, upgrading from Next.js 15, or implementing proxy.ts. Covers breaking changes (async params/searchParams, Turbopack, cacheComponents) and frontend aesthetics. NOT when building non-React or backend-only applications.

ComeOnOliver/skillshub

Comprehensive Framer Motion animation library for React. Covers motion components, variants, gestures, page transitions, and scroll animations. Use when adding animations to React/Next.js applications.

ComeOnOliver/skillshub

Build interfaces that resonate, not just render. This skill enforces bold, intentional

相關技能