# 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) 처리

---

## 설정 패널 디자인 패턴

### 카드 선택 패턴 (타입/소스 선택)
드롭다운 대신 시각적 카드로 선택하게 한다. 사용자가 뭘 선택하는지 한눈에 보인다.

```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>
      <ChevronDown className="h-4 w-4 text-muted-foreground" />
    </button>
  </CollapsibleTrigger>
  <CollapsibleContent>
    <div className="rounded-b-lg border border-t-0 p-4 space-y-3">
      {/* 고급 옵션들 */}
    </div>
  </CollapsibleContent>
</Collapsible>
```

### 토글 옵션 패턴 (Switch + 설명)
각 토글 옵션에 제목과 설명을 함께 보여준다. 사용자가 뭘 켜는 건지 이해할 수 있다.

```tsx
<div className="flex items-center justify-between py-2">
  <div>
    <p className="text-sm">여러 개 선택</p>
    <p className="text-[11px] text-muted-foreground">한 번에 여러 값을 선택할 수 있어요</p>
  </div>
  <Switch checked={value} onCheckedChange={onChange} />
</div>
```

**규칙:**
- Checkbox가 아닌 **Switch** 사용 (토스 스타일)
- 제목: `text-sm`
- 설명: `text-[11px] text-muted-foreground`
- 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>
```

---

## 컨트롤 사이즈 표준

| 컨텍스트 | 높이 | 텍스트 |
|---------|------|--------|
| 설정 패널 내부 | `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에 설명 텍스트가 있는가?
- [ ] 빈 상태에 안내 메시지가 있는가?
- [ ] 전문 용어 대신 쉬운 한국어를 사용했는가?
- [ ] 다크 모드에서 정상적으로 보이는가?