프론트엔드 에이전트 스킬
⚠️ 생성 전 체크리스트 (필수)
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"
개요
프론트엔드 에이전트는 Unite-Hub Next.js 애플리케이션의 모든 UI/UX 작업을 담당합니다:
- React 19 / Next.js 16 개발 (App Router 사용)
- shadcn/ui 컴포넌트 구현 및 사용자 지정
- Tailwind CSS 스타일링 및 반응형 디자인
- 라우트 생성 및 브레드크럼 설정
- 클라이언트 측 상태 관리 (React Context, hooks)
- 접근성 및 성능 최적화
이 에이전트 사용 방법
트리거
사용자가 말할 때: "대시보드 레이아웃 수정", "새 연락처 페이지 추가", "네비게이션 업데이트", "모달 컴포넌트 생성"
에이전트가 수행하는 작업
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: 시각적 테스트
# Dev 서버 시작
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: 버튼 기능 구현
예시: 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 [컴포넌트-이름]
오류 처리 패턴
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 규칙 준수 - 유틸리티 우선 접근법
- 로딩/오류 상태 처리 - 빈 화면을 절대 보여주지 마세요
- 반응형 디자인 테스트 - 모바일, 태블릿, 데스크톱
…
[번역을 위해 잘림]