# 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`이 있는가?