# 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

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

## SmartAdmin 5.5 Design Reference (2026-07-03, 신규 화면부터 적용)

이 섹션은 어드민의 **시각적 스킨**(색상, 카드 크롬, 로그인 화면 스타일, 셸 레이아웃) 기준이다. 위 UX Principles(고밀도, 표준 동선, 더존 정신)는 그대로 유지하고, SmartAdmin 5.5는 그 위에 입히는 룩앤필만 담당한다.

- 소스: `legacy/smartadmin/`(로컬에 이미 포함된 v5.5 HTML/CSS 데모 패키지, Bootstrap 5 기반). 정확한 색상/여백 값이 필요하면 이 디렉터리를 직접 참조한다(추측 금지).
- 적용 범위: **향후 신규 어드민 화면부터**. 기존 20개+ 화면(Dashboard, Blog, Inquiry, Client 등)은 이번엔 재단장하지 않는다. 기존 화면을 다른 이유로 수정할 때 자연스럽게 이 기준으로 수렴시킨다.

### 매핑 표

| SmartAdmin 5.5 참조 | 파일 | TaxBaik MudBlazor 대응 |
| --- | --- | --- |
| 상단 `<header>` 툴바 | `dashboard-control-center.html` | `AdminShell`의 `MudAppBar` |
| `<aside class="app-sidebar">` (로고 + 필터 입력 + 메뉴) | `dashboard-control-center.html` | `AdminShell`의 `MudDrawer` (검색/필터 입력 포함) |
| 로그인 카드 (`rounded-4`, 반투명 다크 글래스, `bg-dark bg-opacity-50`) | `auth-login.html` | `AdminLoginForm.razor`의 `MudPaper` 카드 — 반투명/블러 배경 톤 참고 |
| 색상 팔레트 | `colorpalette.html`, `css/smartapp.min.css` | `App.razor`의 `MudTheme.Palette` (Primary/Secondary/Tertiary 등) |
| 카드형 위젯 | `dashboard-*.html` | `AdminMetricCard`, `MudPaper` 기반 카드 |

### 적용 규칙

- 새 어드민 화면을 만들 때: 레이아웃/동선/밀도는 `DOUZONE_UX_GUIDE.md` 상단 원칙을 따르고, 색상·카드 모서리·그림자·로그인류 화면의 톤은 `legacy/smartadmin/`을 참조해 `MudTheme`/CSS 변수로 반영한다.
- SmartAdmin 원본은 jQuery/Bootstrap 5 기반이므로 JS/DOM 구조를 그대로 이식하지 않는다. **시각적 토큰(색, 반경, 여백, 타이포그래피)만** 가져오고, 동작은 MudBlazor 컴포넌트로 구현한다.
- 기존 화면을 SmartAdmin 스타일로 일괄 재단장하는 작업은 별도 WBS로 `docs/ADMIN_PATTERN_CRITIQUE_WBS.md`에 등록한 뒤 진행한다(이번 범위 아님).

## 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` 패턴 중 하나 이상을 재사용한다.
