# DOUZONE UX Guide

이 문서는 TaxBaik 어드민 UX의 기준선이다. 목표는 더존 세무회계프로그램류의 고밀도 운영 화면을 구현하되, TaxBaik의 도메인과 검증 규칙을 유지하는 것이다.

## UX Principles

- 고밀도 우선: 한 화면에서 상태, 입력, 결과, 작업을 함께 본다.
- 표준 동선 우선: 목록 -> 상세 -> 수정 -> 저장 흐름을 기본으로 둔다.
- 빠른 입력 우선: 마우스 최소, 키보드/단축 동선 최대, 기본값 명확화.
- 상태 가시성 우선: 진행중/성공/실패/비활성/삭제됨을 즉시 구분 가능하게 한다.
- 회귀 최소화 우선: 같은 화면 패턴은 같은 컴포넌트와 같은 구조를 사용한다.
- 추측 금지: 의미가 불명확한 텍스트, 상태, 버튼, 색상은 새로 만들지 않는다.

## Layout Template

어드민 화면은 기본적으로 아래 구조를 따른다.

```text
PageHeader
FilterBar or ActionBar
ContentSurface
  -> DenseGrid or DetailPanel
  -> EmptyState when empty
  -> Paging/Footer when needed
```

권장 규칙:

- 페이지 제목은 1개만 둔다.
- 보조 설명은 1줄만 둔다.
- 주요 액션은 우측 상단 또는 헤더 우측에 둔다.
- 목록은 `Dense`를 기본으로 한다.
- 상세/수정은 좌우 2열 또는 상단 요약 + 하단 폼 패턴을 우선한다.

## Component Template

### Page Header

- 구성: `Eyebrow`, `Title`, `Subtitle`, `Primary Action`
- 역할: 화면 맥락 고정, 다음 행동 제시
- 금지: 동일 화면에 헤더가 2개 이상 존재

### Dense Grid

- 행 간격은 좁게 유지한다.
- 컬럼은 우선순위 순으로 배치한다.
- 상태는 텍스트 대신 칩/색상/아이콘으로 함께 보여준다.
- 작업 버튼은 `보기`, `수정`, `삭제`처럼 짧고 일관되게 둔다.

### Form

- 기본값은 채워진 상태로 시작한다.
- 저장 전 필수 검증은 화면에서 즉시 보인다.
- 저장되지 않는 필드는 read-only로 바꾼다.
- 입력이 많은 폼은 섹션으로 나누되, 섹션 수는 최소화한다.

### Empty State

- 데이터 없음, 필터 결과 없음, 로드 실패를 구분한다.
- 단순 문구보다 다음 행동 버튼을 함께 둔다.

### Status Chip

- 상태는 문자열 그대로 노출하지 말고 칩으로 시각화한다.
- 색상은 의미를 유지한다.
- 동일 상태는 동일 색을 사용한다.

## Text And Labels

- 라벨은 짧게 쓴다.
- 같은 개념은 같은 단어를 쓴다.
- 약어는 화면 전체에서 통일한다.
- 운영자가 오해할 수 있는 추상적인 표현은 금지한다.

## Serving Rules

- 공개 사이트는 SSR, 어드민은 Blazor WebAssembly 기준으로 본다.
- 어드민 화면은 API-first 경유를 기본으로 한다.
- JS는 불가피할 때만 사용하고, 모듈로 격리한다.
- 상태/메뉴/라우트/버튼은 문자열 흩뿌리기를 금지하고 공통 상수 또는 템플릿으로 묶는다.

## Reference Rules

- 이 문서를 어드민 UX의 1차 기준으로 사용한다.
- 세부 코드 규칙은 [ENGINEERING_HARNESS.md](./ENGINEERING_HARNESS.md)를 따른다.
- 콤보/선택/검색 규칙은 [COMBO_POLICY.md](./COMBO_POLICY.md)를 따른다.
- 공통코드/저장값 규칙은 [COMMON_CODE_POLICY.md](./COMMON_CODE_POLICY.md)를 따른다.
- 패턴 비판과 WBS는 [ADMIN_PATTERN_CRITIQUE_WBS.md](./ADMIN_PATTERN_CRITIQUE_WBS.md)를 따른다.
- 문서 인덱스는 [INDEX.md](./INDEX.md)를 따른다.

## Prohibited Patterns

- 목록마다 서로 다른 헤더 구조
- 버튼 색과 의미의 중복/충돌
- 저장 안 되는 필드를 편집 가능한 척 보여주기
- 전역 JS 상태에 의존하는 편집기
- 같은 CRUD 화면의 개별 구현체마다 다른 DOM/행 높이/행동 패턴
- 불필요한 중첩 컴포넌트와 과한 추상화

## Acceptance Criteria

- 신규 어드민 화면은 이 문서의 레이아웃/컴포넌트 규칙 중 최소 80%를 따른다.
- 기존 화면은 새로 건드릴 때 이 문서로 수렴한다.
- 화면 추가 시 `PageHeader`, `EmptyState`, `DenseGrid`, `Form` 패턴 중 하나 이상을 재사용한다.