412 lines
15 KiB
Plaintext
412 lines
15 KiB
Plaintext
# UI/UX 디자인 절대 철학 (Palantir + Toss)
|
|
|
|
## 핵심 철학
|
|
|
|
이 프로젝트의 UI는 **팔란티어의 정보 밀도**와 **토스의 사용자 중심 철학**을 결합한다.
|
|
|
|
### 토스 철학 (사용성)
|
|
- **쉬운 게 맞다**: 사용자가 고민하지 않아도 되게 만들어라
|
|
- **한 화면에 하나의 질문**: 설정을 나열하지 말고 단계별로 안내해라
|
|
- **선택지 최소화**: 10개 옵션 대신 가장 많이 쓰는 2-3개만 보여주고 나머지는 숨겨라
|
|
- **몰라도 되는 건 숨기기**: 고급 설정은 기본적으로 접혀있어야 한다
|
|
- **말하듯이 설명**: 전문 용어 대신 자연스러운 한국어로 안내해라 ("Z-Index" -> "앞/뒤 순서")
|
|
- **기본값이 최선**: 대부분의 사용자가 설정을 안 바꿔도 잘 동작해야 한다
|
|
|
|
### 팔란티어 철학 (정보 밀도)
|
|
- **Dense but organized**: 정보를 빽빽하게 넣되, 시각적 계층으로 정리해라
|
|
- **F-shaped hierarchy**: 왼쪽에서 오른쪽으로 읽는 자연스러운 흐름
|
|
- **Composition**: 작은 원자적 조각을 조합하여 복잡한 UI를 구성해라
|
|
- **뷰당 최대 10개 항목**: 한 섹션에 10개 이상 보이지 않게 분리해라
|
|
|
|
---
|
|
|
|
## 절대 금지 사항 (위반 시 즉시 수정)
|
|
|
|
### 1. 텍스트/요소 밀림 금지
|
|
카드, 버튼, 라벨 등에서 텍스트가 의도한 위치에서 밀리거나 어긋나면 안 된다.
|
|
- 카드 그리드에서 텍스트가 세로로 정렬되지 않는 경우 -> flex + 고정폭 또는 text-center로 해결
|
|
- 아이콘과 텍스트가 같은 줄에 있어야 하는데 밀리는 경우 -> items-center + gap으로 해결
|
|
|
|
```tsx
|
|
// 금지: 텍스트가 밀리는 카드
|
|
<button className="flex flex-col items-start p-3">
|
|
<Icon /><span>직접 입력</span> // 아이콘과 텍스트가 밀림
|
|
</button>
|
|
|
|
// 필수: 정렬된 카드
|
|
<button className="flex flex-col items-center justify-center p-3 text-center min-h-[80px]">
|
|
<Icon className="h-5 w-5 mb-1.5" />
|
|
<span className="text-xs font-medium leading-tight">직접 입력</span>
|
|
<span className="text-[10px] text-muted-foreground leading-tight mt-0.5">옵션을 직접 추가해요</span>
|
|
</button>
|
|
```
|
|
|
|
### 2. 입력 폭 불일치 금지
|
|
같은 영역에 있는 Input, Select 등 폼 컨트롤은 반드시 동일한 폭을 가져야 한다.
|
|
- 같은 섹션의 Input이 서로 다른 너비를 가지면 안 된다
|
|
- 나란히 배치된 필드(너비/높이 등)는 정확히 같은 폭이어야 한다
|
|
|
|
```tsx
|
|
// 금지: 폭이 다른 입력 필드
|
|
<Input className="w-[120px]" /> // Z-Index
|
|
<Input className="w-[180px]" /> // 높이 <- 폭이 다름!
|
|
|
|
// 필수: 폭 일관성
|
|
<div className="flex gap-2">
|
|
<div className="flex-1"><Label>너비</Label><Input className="h-7 w-full" /></div>
|
|
<div className="flex-1"><Label>높이</Label><Input className="h-7 w-full" /></div>
|
|
</div>
|
|
<div>
|
|
<Label>Z-Index</Label>
|
|
<Input className="h-7 w-full" /> // 같은 w-full
|
|
</div>
|
|
```
|
|
|
|
### 3. 미작동 옵션 표시 금지
|
|
실제로 동작하지 않는 설정 옵션을 사용자에게 보여주면 안 된다.
|
|
- 기능이 구현되지 않은 옵션은 숨기거나 "준비 중" 표시
|
|
- 특정 조건에서만 동작하는 옵션은 해당 조건이 아닐 때 비활성화(disabled) 처리
|
|
|
|
---
|
|
|
|
## 설정 패널 디자인 패턴
|
|
|
|
### 참조 모델 (Gold Standard)
|
|
`V2SelectConfigPanel.tsx`가 모든 설정 패널의 기준이다.
|
|
새 패널을 만들거나 기존 패널을 수정할 때 이 파일의 구조를 따라라.
|
|
|
|
```
|
|
구조: 카드 선택 (1단계) -> 소스별 상세 (2단계) -> 고급 설정 (Collapsible)
|
|
간격: space-y-4
|
|
카드: grid grid-cols-2 gap-2, rounded-lg border p-3
|
|
선택됨: border-primary bg-primary/5 ring-1 ring-primary/20
|
|
Collapsible: 접었을 때 Badge로 상태 요약
|
|
설명: text-[10px] text-muted-foreground
|
|
```
|
|
|
|
### 섹션 헤더 패턴 (Icon + Label + Badge)
|
|
모든 설정 섹션의 헤더는 아이콘, 제목, Badge 카운트를 포함한다.
|
|
|
|
```tsx
|
|
<div className="space-y-1">
|
|
<div className="flex items-center gap-2">
|
|
<Database className="h-4 w-4 text-primary" />
|
|
<p className="text-sm font-medium">필드 매핑</p>
|
|
<Badge variant="secondary" className="ml-auto text-[10px] px-1.5 py-0">
|
|
{mappedCount}/{totalCount}
|
|
</Badge>
|
|
</div>
|
|
<p className="text-[11px] text-muted-foreground pl-6">
|
|
상위 폼의 필드 중 렉 생성에 사용할 필드를 선택해요
|
|
</p>
|
|
</div>
|
|
```
|
|
|
|
**규칙:**
|
|
- 아이콘: `h-4 w-4 text-primary` (lucide-react)
|
|
- 제목: `text-sm font-medium`
|
|
- Badge: `variant="secondary" text-[10px]`, `ml-auto`로 오른쪽 정렬
|
|
- 설명: `text-[11px] text-muted-foreground pl-6` (아이콘 너비만큼 들여쓰기)
|
|
|
|
### 상태 표시 카드 리스트 패턴 (CheckCircle / Circle)
|
|
필드 매핑처럼 "설정됨/안됨"을 시각적으로 구분하는 리스트.
|
|
|
|
```tsx
|
|
<div className="space-y-1.5">
|
|
{items.map((item) => {
|
|
const isActive = !!item.value;
|
|
return (
|
|
<div
|
|
key={item.key}
|
|
className={cn(
|
|
"flex items-center gap-3 rounded-lg border px-3 py-2 transition-colors",
|
|
isActive ? "border-primary/30 bg-primary/5" : "bg-muted/30"
|
|
)}
|
|
>
|
|
{isActive
|
|
? <CheckCircle2 className="h-3.5 w-3.5 shrink-0 text-primary" />
|
|
: <Circle className="h-3.5 w-3.5 shrink-0 text-muted-foreground/40" />}
|
|
<div className="min-w-0 flex-1">
|
|
<p className="text-xs font-medium truncate">{item.label}</p>
|
|
<p className="text-[10px] text-muted-foreground truncate">{item.description}</p>
|
|
</div>
|
|
<Select className="h-7 w-[120px] shrink-0 text-xs">...</Select>
|
|
</div>
|
|
);
|
|
})}
|
|
</div>
|
|
```
|
|
|
|
**규칙:**
|
|
- 활성 상태: `border-primary/30 bg-primary/5` + `CheckCircle2` (primary)
|
|
- 비활성 상태: `bg-muted/30` + `Circle` (muted-foreground/40)
|
|
- 아이콘: `shrink-0`으로 줄지 않게
|
|
- 텍스트 블록: `min-w-0 flex-1`로 overflow 대비 + `truncate`
|
|
- 우측 컨트롤: `shrink-0`으로 고정 폭
|
|
|
|
### 컴팩트 숫자 입력 그리드 패턴
|
|
관련 숫자 입력(2~3개)은 가로 그리드로 배치한다. 세로 나열보다 공간 효율이 좋다.
|
|
|
|
```tsx
|
|
<div className="grid grid-cols-3 gap-2">
|
|
<div className="rounded-lg border bg-muted/30 p-3 text-center space-y-1.5">
|
|
<p className="text-[10px] text-muted-foreground">최대 조건</p>
|
|
<Input type="number" className="h-7 text-xs text-center" value={10} />
|
|
</div>
|
|
<div className="rounded-lg border bg-muted/30 p-3 text-center space-y-1.5">
|
|
<p className="text-[10px] text-muted-foreground">최대 열</p>
|
|
<Input type="number" className="h-7 text-xs text-center" value={99} />
|
|
</div>
|
|
<div className="rounded-lg border bg-muted/30 p-3 text-center space-y-1.5">
|
|
<p className="text-[10px] text-muted-foreground">최대 단</p>
|
|
<Input type="number" className="h-7 text-xs text-center" value={20} />
|
|
</div>
|
|
</div>
|
|
```
|
|
|
|
**규칙:**
|
|
- 입력 2개: `grid-cols-2`, 입력 3개: `grid-cols-3`
|
|
- 4개 이상은 세로 나열 또는 2행 그리드 사용
|
|
- 각 셀: `rounded-lg border bg-muted/30 p-3 text-center`
|
|
- 라벨: `text-[10px] text-muted-foreground`
|
|
- Input: `text-center`로 숫자 중앙 정렬
|
|
|
|
### 카드 선택 패턴 (타입/소스 선택)
|
|
드롭다운 대신 시각적 카드로 선택하게 한다. 사용자가 뭘 선택하는지 한눈에 보인다.
|
|
|
|
```tsx
|
|
<div>
|
|
<p className="text-sm font-medium mb-3">이 필드는 어떤 데이터를 선택하나요?</p>
|
|
<div className="grid grid-cols-3 gap-2">
|
|
{cards.map(card => (
|
|
<button
|
|
key={card.value}
|
|
onClick={() => updateConfig("source", card.value)}
|
|
className={cn(
|
|
"flex flex-col items-center justify-center rounded-lg border p-3 text-center transition-all min-h-[80px]",
|
|
isSelected
|
|
? "border-primary bg-primary/5 ring-1 ring-primary/20"
|
|
: "border-border hover:border-primary/50 hover:bg-muted/50"
|
|
)}
|
|
>
|
|
<card.icon className="h-5 w-5 mb-1.5 text-primary" />
|
|
<span className="text-xs font-medium leading-tight">{card.title}</span>
|
|
<span className="text-[10px] text-muted-foreground leading-tight mt-0.5">{card.description}</span>
|
|
</button>
|
|
))}
|
|
</div>
|
|
</div>
|
|
```
|
|
|
|
**카드 필수 규칙:**
|
|
- 모든 카드는 동일한 높이 (`min-h-[80px]`)
|
|
- 텍스트는 center 정렬
|
|
- 아이콘은 텍스트 위에
|
|
- 설명은 `text-[10px] text-muted-foreground`
|
|
- 선택된 카드: `border-primary bg-primary/5 ring-1 ring-primary/20`
|
|
|
|
### 고급 설정 패턴 (Progressive Disclosure)
|
|
자주 안 쓰는 설정은 Collapsible로 숨긴다. 기본은 접혀있다.
|
|
|
|
```tsx
|
|
<Collapsible>
|
|
<CollapsibleTrigger asChild>
|
|
<button className="flex w-full items-center justify-between rounded-lg border bg-muted/30 px-4 py-2.5 text-left hover:bg-muted/50 transition-colors">
|
|
<div className="flex items-center gap-2">
|
|
<Settings className="h-4 w-4 text-muted-foreground" />
|
|
<span className="text-sm font-medium">고급 설정</span>
|
|
</div>
|
|
<div className="flex items-center gap-2">
|
|
{count > 0 && <Badge variant="secondary" className="text-[10px]">{count}개</Badge>}
|
|
<ChevronDown className="h-4 w-4 text-muted-foreground transition-transform [[data-state=open]>&]:rotate-180" />
|
|
</div>
|
|
</button>
|
|
</CollapsibleTrigger>
|
|
<CollapsibleContent>
|
|
<div className="rounded-b-lg border border-t-0 p-4 space-y-3">
|
|
{/* 고급 옵션들 */}
|
|
</div>
|
|
</CollapsibleContent>
|
|
</Collapsible>
|
|
```
|
|
|
|
**Collapsible 규칙:**
|
|
- 펼쳐진 콘텐츠에 `max-h`나 `overflow-y-auto` 절대 금지 (펼치면 전부 보여야 함)
|
|
- 접혀있을 때 Badge로 현재 상태 요약 (예: "3개 설정됨")
|
|
- ChevronDown에 `[[data-state=open]>&]:rotate-180` 트랜지션
|
|
|
|
### 토글 옵션 패턴 (Switch + 설명)
|
|
각 토글 옵션에 제목과 설명을 함께 보여준다. 사용자가 뭘 켜는 건지 이해할 수 있다.
|
|
|
|
```tsx
|
|
<div className="flex items-center justify-between py-2">
|
|
<div className="min-w-0 flex-1 mr-3">
|
|
<p className="text-xs font-medium">여러 개 선택</p>
|
|
<p className="text-[10px] text-muted-foreground">한 번에 여러 값을 선택할 수 있어요</p>
|
|
</div>
|
|
<Switch checked={value} onCheckedChange={onChange} />
|
|
</div>
|
|
```
|
|
|
|
**규칙:**
|
|
- Checkbox가 아닌 **Switch** 사용 (토스 스타일)
|
|
- 제목: `text-xs font-medium` (Collapsible 내부) 또는 `text-sm` (독립 영역)
|
|
- 설명: `text-[10px] text-muted-foreground` 또는 `text-[11px]`
|
|
- 텍스트 블록: `min-w-0 flex-1 mr-3` (Switch와 겹치지 않게)
|
|
- Switch는 오른쪽 정렬
|
|
|
|
### 소스별 설정 영역 패턴
|
|
선택한 소스에 맞는 설정만 보여준다. 배경으로 구분한다.
|
|
|
|
```tsx
|
|
<div className="rounded-lg border bg-muted/30 p-4 space-y-3">
|
|
<div className="flex items-center gap-2">
|
|
<Icon className="h-4 w-4 text-primary" />
|
|
<span className="text-sm font-medium">{title}</span>
|
|
</div>
|
|
{/* 소스별 설정 내용 */}
|
|
</div>
|
|
```
|
|
|
|
### 빈 상태 패턴
|
|
데이터가 없을 때 친절하게 안내한다.
|
|
|
|
```tsx
|
|
<div className="text-center py-6 text-muted-foreground">
|
|
<Icon className="h-8 w-8 mx-auto mb-2 opacity-30" />
|
|
<p className="text-sm">아직 옵션이 없어요</p>
|
|
<p className="text-xs mt-0.5">위의 추가 버튼으로 옵션을 만들어보세요</p>
|
|
</div>
|
|
```
|
|
|
|
### Property Row 패턴 (라벨 + 컨트롤)
|
|
간단한 설정은 수평 배치한다.
|
|
|
|
```tsx
|
|
<div className="flex items-center justify-between py-1.5">
|
|
<span className="text-xs text-muted-foreground">기본 선택값</span>
|
|
<Select className="h-8 w-[160px]">...</Select>
|
|
</div>
|
|
```
|
|
|
|
---
|
|
|
|
## 스크롤 제한 정책 (max-h / overflow)
|
|
|
|
### 인라인 콘텐츠에 max-h 금지 (절대 규칙!)
|
|
|
|
Collapsible이 펼쳐졌을 때 콘텐츠가 스크롤에 잘려서 보이지 않으면 안 된다.
|
|
"펼치기"의 의미는 전부 보여주는 것이다. 스크롤을 걸면 눈가리기일 뿐이다.
|
|
|
|
```tsx
|
|
// 금지: 펼친 콘텐츠에 스크롤 제한
|
|
<CollapsibleContent className="max-h-[250px] overflow-y-auto">
|
|
<div className="max-h-[300px] overflow-y-auto space-y-1">
|
|
|
|
// 허용: 드롭다운/팝업 오버레이에만 max-h 사용
|
|
<CommandGroup className="max-h-[200px] overflow-auto">
|
|
<PopoverContent><CommandList className="max-h-[200px]">
|
|
```
|
|
|
|
**허용 대상** (팝업 오버레이):
|
|
- `CommandGroup`, `CommandList` (Combobox 드롭다운)
|
|
- `SelectContent` (Select 드롭다운)
|
|
- `PopoverContent` 내부 리스트
|
|
|
|
**금지 대상** (인라인 콘텐츠):
|
|
- `CollapsibleContent` 내부
|
|
- 일반 `div` 안의 리스트
|
|
- 설정 패널 본문의 아이템 목록
|
|
|
|
**대안**: Collapsible 접기/펴기로 영역을 줄이되, 펼쳤을 때는 전체를 보여준다.
|
|
|
|
---
|
|
|
|
## 텍스트 오버플로우 처리 (필수!)
|
|
|
|
모든 동적 텍스트(필드명, 테이블명, 컬럼명 등)에 overflow 방지 처리가 필수.
|
|
|
|
```tsx
|
|
// 필수: 모든 동적 텍스트에 truncate
|
|
<p className="text-xs font-medium truncate">{fieldName}</p>
|
|
|
|
// 필수: flex 안의 텍스트 블록에 min-w-0
|
|
<div className="flex items-center gap-2">
|
|
<div className="min-w-0 flex-1">
|
|
<p className="truncate">{longText}</p>
|
|
</div>
|
|
<Switch /> {/* 고정 폭 컨트롤 */}
|
|
</div>
|
|
|
|
// 필수: Switch/Select 옆의 설명 블록
|
|
<div className="min-w-0 flex-1 mr-3">
|
|
<p className="text-xs font-medium">라벨</p>
|
|
<p className="text-[10px] text-muted-foreground">설명</p>
|
|
</div>
|
|
```
|
|
|
|
**핵심 규칙:**
|
|
- `truncate` 단독 사용은 부모에 `min-w-0`이 없으면 무의미
|
|
- flex 컨테이너의 자식 중 텍스트 영역: `min-w-0 flex-1`
|
|
- 고정 크기 컨트롤 (Switch, Button, Select): `shrink-0`
|
|
|
|
---
|
|
|
|
## 컨트롤 사이즈 표준
|
|
|
|
| 컨텍스트 | 높이 | 텍스트 |
|
|
|---------|------|--------|
|
|
| 설정 패널 내부 | `h-7` (28px) 또는 `h-8` (32px) | `text-xs` 또는 `text-sm` |
|
|
| 모달/폼 | `h-8` (32px) 또는 `h-10` (40px) | `text-sm` |
|
|
| 메인 화면 | `h-10` (40px) | `text-sm` |
|
|
|
|
설정 패널은 공간이 좁으므로 `h-7` ~ `h-8` 사용.
|
|
|
|
---
|
|
|
|
## 설명 텍스트 톤앤매너
|
|
|
|
- **~해요** 체 사용 (토스 스타일)
|
|
- 짧고 명확하게
|
|
- 전문 용어 피하기
|
|
|
|
```
|
|
// 좋은 예
|
|
"옵션이 많을 때 검색으로 찾을 수 있어요"
|
|
"한 번에 여러 값을 선택할 수 있어요"
|
|
"선택한 값을 지울 수 있는 X 버튼이 표시돼요"
|
|
|
|
// 나쁜 예
|
|
"Searchable 모드를 활성화합니다"
|
|
"Multiple selection을 허용합니다"
|
|
"allowClear 옵션을 설정합니다"
|
|
```
|
|
|
|
---
|
|
|
|
## 색상 규칙
|
|
|
|
- 선택/활성 강조: `border-primary bg-primary/5 ring-1 ring-primary/20`
|
|
- 비활성 배경: `bg-muted/30`
|
|
- 정보 텍스트: `text-muted-foreground`
|
|
- 경고: `text-amber-600`
|
|
- 성공: `text-emerald-600`
|
|
- CSS 변수 필수, 하드코딩 색상 금지
|
|
|
|
---
|
|
|
|
## 체크리스트 (UI 작업 완료 시 확인)
|
|
|
|
- [ ] 같은 영역의 Input/Select 폭이 일치하는가?
|
|
- [ ] 카드/버튼의 텍스트가 밀리지 않고 정렬되어 있는가?
|
|
- [ ] 미작동 옵션이 표시되고 있지는 않은가?
|
|
- [ ] 고급 설정이 기본으로 접혀있는가?
|
|
- [ ] Switch에 설명 텍스트가 있는가?
|
|
- [ ] 빈 상태에 안내 메시지가 있는가?
|
|
- [ ] 전문 용어 대신 쉬운 한국어를 사용했는가?
|
|
- [ ] 다크 모드에서 정상적으로 보이는가?
|
|
- [ ] 섹션 헤더에 아이콘 + Badge 카운트가 있는가?
|
|
- [ ] 동적 텍스트에 `truncate` + 부모에 `min-w-0`이 있는가?
|
|
- [ ] 인라인 콘텐츠에 `max-h overflow-y-auto`를 사용하지 않았는가?
|
|
- [ ] Switch/Select 옆 텍스트 블록에 `min-w-0 flex-1 mr-3`이 있는가?
|