436 lines
11 KiB
Markdown
436 lines
11 KiB
Markdown
|
# 관리자 페이지 스타일 가이드 적용 예시
|
||
|
|
|
||
|
|
## 개요
|
||
|
|
|
||
|
|
사용자 관리 페이지를 예시로 shadcn/ui 스타일 가이드에 맞춰 재작성했습니다.
|
||
|
|
이 예시를 기준으로 다른 관리자 페이지들도 일관된 스타일로 통일할 수 있습니다.
|
||
|
|
|
||
|
|
## 적용된 주요 원칙
|
||
|
|
|
||
|
|
### 1. Color System (색상 시스템)
|
||
|
|
|
||
|
|
**CSS Variables 사용 (하드코딩된 색상 금지)**
|
||
|
|
```tsx
|
||
|
|
// ❌ 잘못된 예시
|
||
|
|
<div className="bg-gray-50 text-gray-900">
|
||
|
|
|
||
|
|
// ✅ 올바른 예시
|
||
|
|
<div className="bg-background text-foreground">
|
||
|
|
<div className="bg-card text-card-foreground">
|
||
|
|
<div className="bg-muted text-muted-foreground">
|
||
|
|
<div className="text-primary">
|
||
|
|
<div className="text-destructive">
|
||
|
|
```
|
||
|
|
|
||
|
|
**적용 사례:**
|
||
|
|
- 페이지 배경: `bg-background`
|
||
|
|
- 카드 배경: `bg-card`
|
||
|
|
- 보조 텍스트: `text-muted-foreground`
|
||
|
|
- 주요 액션: `text-primary`, `border-primary`
|
||
|
|
- 에러 메시지: `text-destructive`, `bg-destructive/10`
|
||
|
|
|
||
|
|
### 2. Typography (타이포그래피)
|
||
|
|
|
||
|
|
**일관된 폰트 크기와 가중치**
|
||
|
|
```tsx
|
||
|
|
// 페이지 제목
|
||
|
|
<h1 className="text-3xl font-bold tracking-tight">사용자 관리</h1>
|
||
|
|
|
||
|
|
// 섹션 제목
|
||
|
|
<h4 className="text-sm font-semibold">고급 검색 옵션</h4>
|
||
|
|
|
||
|
|
// 본문 텍스트
|
||
|
|
<p className="text-sm text-muted-foreground">설명 텍스트</p>
|
||
|
|
|
||
|
|
// 라벨
|
||
|
|
<label className="text-sm font-medium">필드 라벨</label>
|
||
|
|
|
||
|
|
// 보조 텍스트
|
||
|
|
<p className="text-xs text-muted-foreground">도움말</p>
|
||
|
|
```
|
||
|
|
|
||
|
|
### 3. Spacing System (간격)
|
||
|
|
|
||
|
|
**일관된 간격 사용 (4px 기준)**
|
||
|
|
```tsx
|
||
|
|
// 컴포넌트 간 간격
|
||
|
|
<div className="space-y-6"> // 24px (페이지 레벨)
|
||
|
|
<div className="space-y-4"> // 16px (섹션 레벨)
|
||
|
|
<div className="space-y-2"> // 8px (필드 레벨)
|
||
|
|
|
||
|
|
// 패딩
|
||
|
|
<div className="p-6"> // 24px (카드)
|
||
|
|
<div className="p-4"> // 16px (내부 섹션)
|
||
|
|
|
||
|
|
// 갭
|
||
|
|
<div className="gap-4"> // 16px (flex/grid)
|
||
|
|
<div className="gap-2"> // 8px (버튼 그룹)
|
||
|
|
```
|
||
|
|
|
||
|
|
### 4. Border & Radius (테두리 및 둥근 모서리)
|
||
|
|
|
||
|
|
**표준 radius 사용**
|
||
|
|
```tsx
|
||
|
|
// 카드/패널
|
||
|
|
<div className="rounded-lg border bg-card">
|
||
|
|
|
||
|
|
// 입력 필드
|
||
|
|
<Input className="rounded-md">
|
||
|
|
|
||
|
|
// 버튼
|
||
|
|
<Button className="rounded-md">
|
||
|
|
```
|
||
|
|
|
||
|
|
### 5. Button Variants (버튼 스타일)
|
||
|
|
|
||
|
|
**표준 variants 사용**
|
||
|
|
```tsx
|
||
|
|
// Primary 액션
|
||
|
|
<Button variant="default" size="default" className="h-10 gap-2 text-sm font-medium">
|
||
|
|
<Plus className="h-4 w-4" />
|
||
|
|
사용자 등록
|
||
|
|
</Button>
|
||
|
|
|
||
|
|
// Secondary 액션
|
||
|
|
<Button variant="outline" size="default" className="h-10 gap-2 text-sm font-medium">
|
||
|
|
고급 검색
|
||
|
|
</Button>
|
||
|
|
|
||
|
|
// Ghost 버튼 (아이콘 전용)
|
||
|
|
<Button variant="ghost" size="icon" className="h-8 w-8">
|
||
|
|
<Key className="h-4 w-4" />
|
||
|
|
</Button>
|
||
|
|
```
|
||
|
|
|
||
|
|
**크기 표준:**
|
||
|
|
- `h-10`: 기본 버튼 (40px)
|
||
|
|
- `h-9`: 작은 버튼 (36px)
|
||
|
|
- `h-8`: 아이콘 버튼 (32px)
|
||
|
|
|
||
|
|
### 6. Input States (입력 필드 상태)
|
||
|
|
|
||
|
|
**표준 Input 스타일**
|
||
|
|
```tsx
|
||
|
|
// 기본
|
||
|
|
<Input className="h-10 text-sm" />
|
||
|
|
|
||
|
|
// 포커스 (자동 적용)
|
||
|
|
// focus:ring-2 focus:ring-ring
|
||
|
|
|
||
|
|
// 로딩/액티브
|
||
|
|
<Input className="h-10 text-sm border-primary ring-2 ring-primary/20" />
|
||
|
|
|
||
|
|
// 비활성화
|
||
|
|
<Input disabled className="cursor-not-allowed bg-muted text-muted-foreground" />
|
||
|
|
```
|
||
|
|
|
||
|
|
### 7. Form Structure (폼 구조)
|
||
|
|
|
||
|
|
**표준 필드 구조**
|
||
|
|
```tsx
|
||
|
|
<div className="space-y-2">
|
||
|
|
<label htmlFor="field-id" className="text-sm font-medium">
|
||
|
|
필드 라벨
|
||
|
|
</label>
|
||
|
|
<Input
|
||
|
|
id="field-id"
|
||
|
|
placeholder="힌트 텍스트"
|
||
|
|
className="h-10 text-sm"
|
||
|
|
/>
|
||
|
|
<p className="text-xs text-muted-foreground">
|
||
|
|
도움말 텍스트
|
||
|
|
</p>
|
||
|
|
</div>
|
||
|
|
```
|
||
|
|
|
||
|
|
### 8. Table Structure (테이블 구조)
|
||
|
|
|
||
|
|
**표준 테이블 스타일**
|
||
|
|
```tsx
|
||
|
|
<div className="rounded-lg border bg-card shadow-sm">
|
||
|
|
<Table>
|
||
|
|
<TableHeader>
|
||
|
|
<TableRow className="border-b bg-muted/50 hover:bg-muted/50">
|
||
|
|
<TableHead className="h-12 text-sm font-semibold">
|
||
|
|
컬럼명
|
||
|
|
</TableHead>
|
||
|
|
</TableRow>
|
||
|
|
</TableHeader>
|
||
|
|
<TableBody>
|
||
|
|
<TableRow className="border-b transition-colors hover:bg-muted/50">
|
||
|
|
<TableCell className="h-16 text-sm">
|
||
|
|
데이터
|
||
|
|
</TableCell>
|
||
|
|
</TableRow>
|
||
|
|
</TableBody>
|
||
|
|
</Table>
|
||
|
|
</div>
|
||
|
|
```
|
||
|
|
|
||
|
|
**높이 표준:**
|
||
|
|
- 헤더: `h-12` (48px)
|
||
|
|
- 데이터 행: `h-16` (64px)
|
||
|
|
|
||
|
|
### 9. Loading States (로딩 상태)
|
||
|
|
|
||
|
|
**Skeleton UI**
|
||
|
|
```tsx
|
||
|
|
<div className="h-4 animate-pulse rounded bg-muted"></div>
|
||
|
|
```
|
||
|
|
|
||
|
|
### 10. Empty States (빈 상태)
|
||
|
|
|
||
|
|
**표준 Empty State**
|
||
|
|
```tsx
|
||
|
|
<TableCell colSpan={columns} className="h-32 text-center">
|
||
|
|
<div className="flex flex-col items-center justify-center gap-2 text-muted-foreground">
|
||
|
|
<p className="text-sm">등록된 데이터가 없습니다.</p>
|
||
|
|
</div>
|
||
|
|
</TableCell>
|
||
|
|
```
|
||
|
|
|
||
|
|
### 11. Error States (에러 상태)
|
||
|
|
|
||
|
|
**표준 에러 메시지**
|
||
|
|
```tsx
|
||
|
|
<div className="rounded-lg border border-destructive/50 bg-destructive/10 p-4">
|
||
|
|
<div className="flex items-center justify-between">
|
||
|
|
<p className="text-sm font-semibold text-destructive">오류가 발생했습니다</p>
|
||
|
|
<button
|
||
|
|
onClick={clearError}
|
||
|
|
className="text-destructive transition-colors hover:text-destructive/80"
|
||
|
|
aria-label="에러 메시지 닫기"
|
||
|
|
>
|
||
|
|
✕
|
||
|
|
</button>
|
||
|
|
</div>
|
||
|
|
<p className="mt-1.5 text-sm text-destructive/80">{errorMessage}</p>
|
||
|
|
</div>
|
||
|
|
```
|
||
|
|
|
||
|
|
### 12. Responsive Design (반응형)
|
||
|
|
|
||
|
|
**모바일 우선 접근**
|
||
|
|
```tsx
|
||
|
|
// 레이아웃
|
||
|
|
<div className="flex flex-col gap-4 sm:flex-row sm:items-center">
|
||
|
|
|
||
|
|
// 그리드
|
||
|
|
<div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-4">
|
||
|
|
|
||
|
|
// 텍스트
|
||
|
|
<h1 className="text-2xl sm:text-3xl font-bold">
|
||
|
|
|
||
|
|
// 간격
|
||
|
|
<div className="p-4 sm:p-6">
|
||
|
|
```
|
||
|
|
|
||
|
|
### 13. Accessibility (접근성)
|
||
|
|
|
||
|
|
**필수 적용 사항**
|
||
|
|
```tsx
|
||
|
|
// Label과 Input 연결
|
||
|
|
<label htmlFor="user-id" className="text-sm font-medium">
|
||
|
|
사용자 ID
|
||
|
|
</label>
|
||
|
|
<Input id="user-id" />
|
||
|
|
|
||
|
|
// 버튼에 aria-label
|
||
|
|
<Button aria-label="에러 메시지 닫기">
|
||
|
|
✕
|
||
|
|
</Button>
|
||
|
|
|
||
|
|
// Switch에 aria-label
|
||
|
|
<Switch
|
||
|
|
checked={isActive}
|
||
|
|
onCheckedChange={handleChange}
|
||
|
|
aria-label="사용자 상태 토글"
|
||
|
|
/>
|
||
|
|
```
|
||
|
|
|
||
|
|
## 페이지 구조 템플릿
|
||
|
|
|
||
|
|
### Page Component
|
||
|
|
```tsx
|
||
|
|
export default function AdminPage() {
|
||
|
|
return (
|
||
|
|
<div className="flex min-h-screen flex-col bg-background">
|
||
|
|
<div className="container mx-auto space-y-6 p-6">
|
||
|
|
{/* 페이지 헤더 */}
|
||
|
|
<div className="space-y-2 border-b pb-4">
|
||
|
|
<h1 className="text-3xl font-bold tracking-tight">페이지 제목</h1>
|
||
|
|
<p className="text-sm text-muted-foreground">페이지 설명</p>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
{/* 메인 컨텐츠 */}
|
||
|
|
<MainComponent />
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
);
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
### Toolbar Component
|
||
|
|
```tsx
|
||
|
|
export function Toolbar() {
|
||
|
|
return (
|
||
|
|
<div className="space-y-4">
|
||
|
|
{/* 검색 영역 */}
|
||
|
|
<div className="rounded-lg border bg-card p-4">
|
||
|
|
<div className="mb-4 flex flex-col gap-4 sm:flex-row sm:items-center">
|
||
|
|
{/* 검색 입력 */}
|
||
|
|
<div className="flex-1">
|
||
|
|
<div className="relative">
|
||
|
|
<Search className="absolute left-3 top-1/2 h-4 w-4 -translate-y-1/2 text-muted-foreground" />
|
||
|
|
<Input placeholder="검색..." className="h-10 pl-10 text-sm" />
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
{/* 버튼 */}
|
||
|
|
<Button variant="outline" className="h-10 gap-2 text-sm font-medium">
|
||
|
|
고급 검색
|
||
|
|
</Button>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
{/* 액션 버튼 영역 */}
|
||
|
|
<div className="flex flex-col items-start justify-between gap-4 sm:flex-row sm:items-center">
|
||
|
|
<div className="text-sm text-muted-foreground">
|
||
|
|
총 <span className="font-semibold text-foreground">{count.toLocaleString()}</span> 건
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<Button className="h-10 gap-2 text-sm font-medium">
|
||
|
|
<Plus className="h-4 w-4" />
|
||
|
|
등록
|
||
|
|
</Button>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
);
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
## 적용해야 할 다른 관리자 페이지
|
||
|
|
|
||
|
|
### 우선순위 1 (핵심 페이지)
|
||
|
|
- [ ] 메뉴 관리 (`/admin/menu`)
|
||
|
|
- [ ] 공통코드 관리 (`/admin/commonCode`)
|
||
|
|
- [ ] 회사 관리 (`/admin/company`)
|
||
|
|
- [ ] 테이블 관리 (`/admin/tableMng`)
|
||
|
|
|
||
|
|
### 우선순위 2 (자주 사용하는 페이지)
|
||
|
|
- [ ] 외부 연결 관리 (`/admin/external-connections`)
|
||
|
|
- [ ] 외부 호출 설정 (`/admin/external-call-configs`)
|
||
|
|
- [ ] 배치 관리 (`/admin/batch-management`)
|
||
|
|
- [ ] 레이아웃 관리 (`/admin/layouts`)
|
||
|
|
|
||
|
|
### 우선순위 3 (기타 관리 페이지)
|
||
|
|
- [ ] 템플릿 관리 (`/admin/templates`)
|
||
|
|
- [ ] 표준 관리 (`/admin/standards`)
|
||
|
|
- [ ] 다국어 관리 (`/admin/i18n`)
|
||
|
|
- [ ] 수집 관리 (`/admin/collection-management`)
|
||
|
|
|
||
|
|
## 체크리스트
|
||
|
|
|
||
|
|
각 페이지 작업 시 다음을 확인하세요:
|
||
|
|
|
||
|
|
### 레이아웃
|
||
|
|
- [ ] `bg-background` 사용 (하드코딩된 색상 없음)
|
||
|
|
- [ ] `container mx-auto space-y-6 p-6` 구조
|
||
|
|
- [ ] 페이지 헤더에 `border-b pb-4`
|
||
|
|
|
||
|
|
### 색상
|
||
|
|
- [ ] CSS Variables만 사용 (`bg-card`, `text-muted-foreground` 등)
|
||
|
|
- [ ] `bg-gray-*`, `text-gray-*` 등 하드코딩 제거
|
||
|
|
|
||
|
|
### 타이포그래피
|
||
|
|
- [ ] 페이지 제목: `text-3xl font-bold tracking-tight`
|
||
|
|
- [ ] 섹션 제목: `text-sm font-semibold`
|
||
|
|
- [ ] 본문: `text-sm`
|
||
|
|
- [ ] 보조 텍스트: `text-xs text-muted-foreground`
|
||
|
|
|
||
|
|
### 간격
|
||
|
|
- [ ] 페이지 레벨: `space-y-6`
|
||
|
|
- [ ] 섹션 레벨: `space-y-4`
|
||
|
|
- [ ] 필드 레벨: `space-y-2`
|
||
|
|
- [ ] 카드 패딩: `p-4` 또는 `p-6`
|
||
|
|
|
||
|
|
### 버튼
|
||
|
|
- [ ] 표준 variants 사용 (`default`, `outline`, `ghost`)
|
||
|
|
- [ ] 표준 크기: `h-10` (기본), `h-9` (작음), `h-8` (아이콘)
|
||
|
|
- [ ] 텍스트: `text-sm font-medium`
|
||
|
|
- [ ] 아이콘 + 텍스트: `gap-2`
|
||
|
|
|
||
|
|
### 입력 필드
|
||
|
|
- [ ] 높이: `h-10`
|
||
|
|
- [ ] 텍스트: `text-sm`
|
||
|
|
- [ ] Label과 Input `htmlFor`/`id` 연결
|
||
|
|
- [ ] `space-y-2` 구조
|
||
|
|
|
||
|
|
### 테이블
|
||
|
|
- [ ] `rounded-lg border bg-card shadow-sm`
|
||
|
|
- [ ] 헤더: `h-12 text-sm font-semibold bg-muted/50`
|
||
|
|
- [ ] 데이터 행: `h-16 text-sm`
|
||
|
|
- [ ] Hover: `hover:bg-muted/50`
|
||
|
|
|
||
|
|
### 반응형
|
||
|
|
- [ ] 모바일 우선 디자인
|
||
|
|
- [ ] `sm:`, `md:`, `lg:` 브레이크포인트 사용
|
||
|
|
- [ ] `flex-col sm:flex-row` 패턴
|
||
|
|
|
||
|
|
### 접근성
|
||
|
|
- [ ] Label `htmlFor` 속성
|
||
|
|
- [ ] Input `id` 속성
|
||
|
|
- [ ] 버튼 `aria-label`
|
||
|
|
- [ ] Switch `aria-label`
|
||
|
|
|
||
|
|
## 마이그레이션 절차
|
||
|
|
|
||
|
|
1. **페이지 컴포넌트 수정** (`page.tsx`)
|
||
|
|
- 레이아웃 구조 변경
|
||
|
|
- 색상 CSS Variables로 변경
|
||
|
|
- 페이지 헤더 표준화
|
||
|
|
|
||
|
|
2. **Toolbar 컴포넌트 수정**
|
||
|
|
- 검색 영역 스타일 통일
|
||
|
|
- 버튼 스타일 표준화
|
||
|
|
- 반응형 레이아웃 적용
|
||
|
|
|
||
|
|
3. **Table 컴포넌트 수정**
|
||
|
|
- 테이블 컨테이너 스타일 통일
|
||
|
|
- 헤더/데이터 행 높이 표준화
|
||
|
|
- 로딩/Empty State 표준화
|
||
|
|
|
||
|
|
4. **Form 컴포넌트 수정** (있는 경우)
|
||
|
|
- 필드 구조 표준화
|
||
|
|
- 라벨과 입력 필드 연결
|
||
|
|
- 에러 메시지 스타일 통일
|
||
|
|
|
||
|
|
5. **Modal 컴포넌트 수정** (있는 경우)
|
||
|
|
- Dialog 표준 패턴 적용
|
||
|
|
- 반응형 크기 (`max-w-[95vw] sm:max-w-[500px]`)
|
||
|
|
- 버튼 스타일 표준화
|
||
|
|
|
||
|
|
6. **린트 에러 확인**
|
||
|
|
```bash
|
||
|
|
# 수정한 파일들 확인
|
||
|
|
npm run lint
|
||
|
|
```
|
||
|
|
|
||
|
|
7. **테스트**
|
||
|
|
- 기능 동작 확인
|
||
|
|
- 반응형 확인 (모바일/태블릿/데스크톱)
|
||
|
|
- 다크모드 확인 (있는 경우)
|
||
|
|
|
||
|
|
## 참고 파일
|
||
|
|
|
||
|
|
### 완성된 예시
|
||
|
|
- `frontend/app/(main)/admin/userMng/page.tsx`
|
||
|
|
- `frontend/components/admin/UserToolbar.tsx`
|
||
|
|
- `frontend/components/admin/UserTable.tsx`
|
||
|
|
- `frontend/components/admin/UserManagement.tsx`
|
||
|
|
|
||
|
|
### 스타일 가이드
|
||
|
|
- `.cursorrules` - 전체 스타일 규칙
|
||
|
|
- Section 1-21: 각 스타일 요소별 상세 가이드
|
||
|
|
|