# Cursor Rules for ERP-node Project
## shadcn/ui 웹 스타일 가이드라인
모든 프론트엔드 개발 시 다음 shadcn/ui 기반 스타일 가이드라인을 준수해야 합니다.
### 1. Color System (색상 시스템)
#### CSS Variables 사용
shadcn은 CSS Variables를 사용하여 테마를 관리하며, 모든 색상은 HSL 형식으로 정의됩니다.
**기본 색상 토큰 (항상 사용):**
- `--background`: 페이지 배경
- `--foreground`: 기본 텍스트
- `--primary`: 메인 액션 (Indigo 계열)
- `--primary-foreground`: Primary 위 텍스트
- `--secondary`: 보조 액션
- `--muted`: 약한 배경
- `--muted-foreground`: 보조 텍스트
- `--destructive`: 삭제/에러 (Rose 계열)
- `--border`: 테두리
- `--ring`: 포커스 링
**Tailwind 클래스로 사용:**
```tsx
bg-primary text-primary-foreground
bg-secondary text-secondary-foreground
bg-muted text-muted-foreground
bg-destructive text-destructive-foreground
border-border
```
**추가 시맨틱 컬러:**
- Success: `--success` (Emerald-600 계열)
- Warning: `--warning` (Amber-500 계열)
- Info: `--info` (Cyan-500 계열)
### 2. Spacing System (간격)
**Tailwind Scale (4px 기준):**
- 0.5 = 2px, 1 = 4px, 2 = 8px, 3 = 12px, 4 = 16px, 6 = 24px, 8 = 32px
**컴포넌트별 권장 간격:**
- 카드 패딩: `p-6` (24px)
- 카드 간 마진: `gap-6` (24px)
- 폼 필드 간격: `space-y-4` (16px)
- 버튼 내부 패딩: `px-4 py-2`
- 섹션 간격: `space-y-8` 또는 `space-y-12`
### 3. Typography (타이포그래피)
**용도별 타이포그래피 (필수):**
- 페이지 제목: `text-3xl font-bold`
- 섹션 제목: `text-2xl font-semibold`
- 카드 제목: `text-xl font-semibold`
- 서브 제목: `text-lg font-medium`
- 본문 텍스트: `text-sm text-muted-foreground`
- 작은 텍스트: `text-xs text-muted-foreground`
- 버튼 텍스트: `text-sm font-medium`
- 폼 라벨: `text-sm font-medium`
### 4. Button Variants (버튼 스타일)
**필수 사용 패턴:**
```tsx
// Primary (기본)
// Secondary
// Outline
// Ghost
// Destructive
```
**버튼 크기:**
- `size="sm"`: 작은 버튼 (h-9 px-3)
- `size="default"`: 기본 버튼 (h-10 px-4 py-2)
- `size="lg"`: 큰 버튼 (h-11 px-8)
- `size="icon"`: 아이콘 전용 (h-10 w-10)
### 5. Input States (입력 필드 상태)
**필수 적용 상태:**
```tsx
// Default
className="border-input"
// Focus (모든 입력 필드 필수)
className="focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2"
// Error
className="border-destructive focus-visible:ring-destructive"
// Disabled
className="disabled:opacity-50 disabled:cursor-not-allowed"
```
### 6. Card Structure (카드 구조)
**표준 카드 구조 (필수):**
```tsx
제목설명
{/* 내용 */}
{/* 액션 버튼들 */}
```
### 7. Border & Radius (테두리 및 둥근 모서리)
**컴포넌트별 권장:**
- 버튼: `rounded-md` (6px)
- 입력 필드: `rounded-md` (6px)
- 카드: `rounded-lg` (8px)
- 배지: `rounded-full`
- 모달/대화상자: `rounded-lg` (8px)
- 드롭다운: `rounded-md` (6px)
### 8. Shadow (그림자)
**용도별 권장:**
- 카드: `shadow-sm`
- 드롭다운: `shadow-md`
- 모달: `shadow-lg`
- 팝오버: `shadow-md`
- 버튼 호버: `shadow-sm`
### 9. Interactive States (상호작용 상태)
**필수 적용 패턴:**
```tsx
// Hover
hover:bg-primary/90 // 버튼
hover:bg-accent // Ghost 버튼
hover:underline // 링크
hover:shadow-md transition-shadow // 카드
// Focus (모든 인터랙티브 요소 필수)
focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2
// Active
active:scale-95 transition-transform // 버튼
// Disabled
disabled:opacity-50 disabled:cursor-not-allowed
```
### 10. Animation (애니메이션)
**권장 Duration:**
- 빠른 피드백: `duration-75`
- 기본: `duration-150`
- 부드러운 전환: `duration-300`
**권장 패턴:**
- 버튼 클릭: `transition-transform duration-150 active:scale-95`
- 색상 전환: `transition-colors duration-150`
- 드롭다운 열기: `transition-all duration-200`
### 11. Responsive (반응형)
**Breakpoints:**
- `sm`: 640px (모바일 가로)
- `md`: 768px (태블릿)
- `lg`: 1024px (노트북)
- `xl`: 1280px (데스크톱)
**반응형 패턴:**
```tsx
// 모바일 우선 접근
className="flex-col md:flex-row"
className="grid-cols-1 md:grid-cols-2 lg:grid-cols-3"
className="text-2xl md:text-3xl lg:text-4xl"
className="p-4 md:p-6 lg:p-8"
```
### 12. Accessibility (접근성)
**필수 적용 사항:**
1. 포커스 표시: 모든 인터랙티브 요소에 `focus-visible:ring-2` 적용
2. ARIA 레이블: 적절한 `aria-label`, `aria-describedby` 사용
3. 키보드 네비게이션: Tab, Enter, Space, Esc 지원
4. 색상 대비: 최소 4.5:1 (일반 텍스트), 3:1 (큰 텍스트)
### 13. Class 순서 (일관성 유지)
**항상 이 순서로 작성:**
1. Layout: `flex`, `grid`, `block`
2. Sizing: `w-full`, `h-10`
3. Spacing: `p-4`, `m-2`, `gap-4`
4. Typography: `text-sm`, `font-medium`
5. Colors: `bg-primary`, `text-white`
6. Border: `border`, `rounded-md`
7. Effects: `shadow-sm`, `opacity-50`
8. States: `hover:`, `focus:`, `disabled:`
9. Responsive: `md:`, `lg:`
### 14. 실무 적용 규칙
1. **shadcn 컴포넌트 우선 사용**: 커스텀 스타일보다 shadcn 기본 컴포넌트 활용
2. **cn 유틸리티 사용**: 조건부 클래스는 `cn()` 함수로 결합
3. **테마 변수 사용**: 하드코딩된 색상 대신 CSS 변수 사용
4. **다크모드 고려**: 모든 컴포넌트는 다크모드 호환 필수
5. **일관성 유지**: 같은 용도의 컴포넌트는 같은 스타일 사용
### 15. 금지 사항
1. ❌ 하드코딩된 색상 값 사용 (예: `bg-blue-500` 대신 `bg-primary`)
2. ❌ 인라인 스타일로 색상 지정 (예: `style={{ color: '#3b82f6' }}`)
3. ❌ 포커스 스타일 제거 (`outline-none`만 단독 사용)
4. ❌ 접근성 무시 (ARIA 레이블 누락)
5. ❌ 반응형 무시 (데스크톱 전용 스타일)
6. ❌ **중첩 박스 금지**: 사용자가 명시적으로 요청하지 않는 한 Card 안에 Card, Border 안에 Border 같은 중첩된 컨테이너 구조를 만들지 않음
### 16. 중첩 박스 금지 상세 규칙
**금지되는 패턴 (사용자 요청 없이):**
```tsx
// ❌ Card 안에 Card
// 중첩 금지!
내용
// ❌ Border 안에 Border
// 중첩 금지!
내용
// ❌ 불필요한 래퍼
// 중첩 금지!
내용
```
**허용되는 패턴:**
```tsx
// ✅ 단일 Card
제목
내용
// ✅ 의미적으로 다른 컴포넌트 조합
// ✅ 그리드/리스트 내부의 Card들
항목 1항목 2항목 3
```
**예외 상황 (사용자가 명시적으로 요청한 경우만):**
- 대시보드에서 섹션별 그룹핑이 필요한 경우
- 복잡한 데이터 구조를 시각적으로 구분해야 하는 경우
- 드래그앤드롭 등 특수 기능을 위한 경우
**원칙:**
- 심플하고 깔끔한 디자인 유지
- 불필요한 시각적 레이어 제거
- 사용자가 명시적으로 "박스 안에 박스", "중첩된 카드" 등을 요청하지 않으면 단일 레벨 유지
### 17. 표준 모달(Dialog) 디자인 패턴
**프로젝트 표준 모달 구조 (플로우 관리 기준):**
```tsx
```
**필수 적용 사항:**
1. **반응형 크기**
- 모바일: `max-w-[95vw]` (화면 너비의 95%)
- 데스크톱: `sm:max-w-[500px]` (고정 500px)
2. **헤더 구조**
- DialogTitle: `text-base sm:text-lg` (16px → 18px)
- DialogDescription: `text-xs sm:text-sm` (12px → 14px)
- 항상 제목과 설명 모두 포함
3. **컨텐츠 간격**
- 필드 간 간격: `space-y-3 sm:space-y-4` (12px → 16px)
- 각 필드는 `
` 로 감싸기
4. **입력 필드 패턴**
- Label: `text-xs sm:text-sm` + 필수 필드는 `*` 표시
- Input/Select: `h-8 text-xs sm:h-10 sm:text-sm` (32px → 40px)
- 도움말: `text-muted-foreground mt-1 text-[10px] sm:text-xs`
5. **푸터 버튼**
- 컨테이너: `gap-2 sm:gap-0` (모바일에서 간격, 데스크톱에서 자동)
- 버튼: `h-8 flex-1 text-xs sm:h-10 sm:flex-none sm:text-sm`
- 모바일: 같은 크기 (`flex-1`)
- 데스크톱: 자동 크기 (`flex-none`)
- 순서: 취소(outline) → 확인(default)
6. **접근성**
- Label의 `htmlFor`와 Input의 `id` 매칭
- Button에 적절한 `onClick` 핸들러
- Dialog의 `open`과 `onOpenChange` 필수
**확인 모달 (간단한 경고/확인):**
```tsx
```
**원칙:**
- 모든 모달은 모바일 우선 반응형 디자인
- 일관된 크기, 간격, 폰트 크기 사용
- 사용자가 다른 크기를 명시하지 않으면 `sm:max-w-[500px]` 사용
- 삭제/위험한 작업은 `variant="destructive"` 사용
### 18. 검색 가능한 Select 박스 (Combobox 패턴)
**적용 조건**: 사용자가 "검색 기능이 있는 Select 박스" 또는 "Combobox"를 명시적으로 요청한 경우만 사용
**표준 Combobox 구조 (플로우 관리 기준):**
```tsx
import { Check, ChevronsUpDown } from "lucide-react";
import { Button } from "@/components/ui/button";
import { Command, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList } from "@/components/ui/command";
import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover";
import { cn } from "@/lib/utils";
// 상태 관리
const [open, setOpen] = useState(false);
const [value, setValue] = useState("");
// 렌더링
항목을 찾을 수 없습니다.
{items.map((item) => (
{
setValue(currentValue === value ? "" : currentValue);
setOpen(false);
}}
className="text-xs sm:text-sm"
>
{item.label}
))}
```
**복잡한 데이터 표시 (라벨 + 설명):**
```tsx
{
setValue(currentValue);
setOpen(false);
}}
className="text-xs sm:text-sm"
>