# 01. UI Guidelines

---

## 목적 우선(Why-first)

- UI를 추가/변경하기 전에 “이 변경이 해결하는 사용자 문제”를 1문장으로 고정한다.
- 목적이 불명확하면 구현하지 않는다.
- 한 UI 요소는 목적을 1개만 가진다(복수 목적이면 분리).

---

## 단일 정답 위치(Single canonical place)

- 같은 일을 하는 진입점/버튼/칩을 여러 곳에 두지 않는다.
- 불가피하게 2곳 이상이면 역할을 분리한다(예: Quick vs Browse).
- 사용자가 “어디서 해야 하는지” 고민하게 만들면 실패다.

---

## 인지 부하 최소(Decision budget)

- 한 화면에서 사용자가 “지금 결정해야 하는 것”은 최소로 제한한다.
- 기본값을 제공하고, 추가 옵션은 접힘/팝오버/시트로 점진적으로 노출한다.
- ‘변경’ 같은 버튼이 반복 노출되면 과밀/혼란 신호다(구조 재설계).

---

## 일관된 위계(Quiet hierarchy)

- Primary CTA는 1개만 강하게.
- Secondary/Tertiary는 가볍게(ghost/outline/link).
- 강조는 “조용한 위계”로, 과한 대비/과한 시각효과 금지.

---

## 피드백 단일화(One feedback channel)

- 같은 행동의 피드백은 한 채널에서만 보여준다.
- 자주 발생하는 변경은 토스트 대신 “상태 변화”로 끝내는 것을 우선한다.
- 피드백이 여러 곳에서 동시에 뜨면 어색함/저가 인상을 만든다.

---

## 겹침/충돌 방지(Overlap discipline)

- 패널/시트/팝오버/토스트가 서로 겹치지 않게 우선순위를 정의한다.
- 어떤 UI가 떠 있을 때 다른 UI는 이동/억제/병합 중 하나로 처리한다.
- 전역 블러/전역 딤으로 문제를 덮지 않는다(필요 시 최소치).

---

## 무대 유지(Stage-first)

- 배경/핵심 화면을 가리는 요소는 최소화한다.
- 상시 UI는 “앵커(작고 확실한 표시)” 위주로 유지한다.
- 큰 카드/대시보드형 UI가 상시 떠 있으면 감성이 깨진다.

---

## 모션은 이유가 있을 때만(Motion with meaning)

- 애니메이션은 상태 변화를 이해시키는 목적이 있을 때만 사용한다.
- 짧고 조용하게(과한 이징/번쩍임/바운스 금지).
- Reduce Motion을 고려한다.

---

## 카피는 오해를 만들지 않게(Copy safety)

- 초기 데이터가 비어도 어색하지 않은 카피를 기본값으로 둔다.
- 실시간/확정처럼 보이는 표현은 신중히 사용한다.
- 더미 동작은 (더미)로 명시한다.

---

## 접근성/상호작용 기본값(A11y baseline)

- 아이콘 버튼은 sr-only 라벨 제공.
- 포커스 링 유지.
- 터치/클릭 타겟 충분히 확보.

---

## 품질 게이트(커밋 전 1분 체크)

아래 중 하나라도 “No”면 커밋하지 않는다.

- 중복 진입점이 생겼는가?
- 한 화면에 결정/선택이 과도하게 보이는가?
- 피드백이 두 군데 이상에서 나오나?
- 겹침/가림/우선순위 문제가 있나?
- 배경(무대)을 과도하게 가리나?
- 톤/위계/카피가 01 가이드라인과 충돌하나?

---

## 디자인 톤

- 기본 톤: 감성, 저자극, 차분함
- 금지 톤: 과한 대비, 과한 번쩍임, 과도한 채도, 공격적인 카피
- CTA는 명확하되 조용한 위계로 구성한다.

## 컬러/표현 원칙

- 다크 + 글래스 분위기를 유지한다.
- 포인트 색상은 1차 액션에만 제한적으로 사용한다.
- 2차/3차 액션은 outline/ghost/텍스트 링크로 무게를 낮춘다.

## CTA 위계 규칙

- Primary: 사용자 목표를 즉시 달성하는 액션 1개만 강조
- Secondary: 대안 액션, 가시성은 유지하되 무게는 낮춤
- Tertiary: 텍스트 링크 또는 작은 아이콘 액션
- 데스크탑에서는 불필요한 풀폭 CTA를 지양한다.

## 반응형 규칙

- 모바일: 터치 우선, 충분한 높이/패딩, 필요 시 풀폭 CTA 허용
- 데스크탑: 내용폭 기반 컴팩트 CTA 그룹 권장
- 텍스트 길이에 따라 버튼 폭이 과도하게 늘어나지 않게 `min-w + px`를 사용

## 마이크로카피 규칙

- 실시간/확정처럼 보이는 문구를 신중히 사용한다.
- 초기 데이터가 비어도 어색하지 않은 카피를 기본값으로 사용한다.
- 숫자 기반 과장 표현보다 분위기/큐레이션 중심 문구를 우선한다.

## 접근성/상호작용

- 아이콘 버튼은 `sr-only` 텍스트를 제공한다.
- 포커스 링을 유지한다.
- 실제 미구현 기능은 토스트로 피드백하되, 실제 동작처럼 오해되지 않게 `(더미)`를 명시한다.