1
0
Fork 0
Everything2Everything/design.md
Yun Chan ab126a001a feat(ui): Windows 11 정통 네이티브 리디자인 + Google AdMob 광고 연동
- Mica 베이스 + 왼쪽 위 8px 라운드 콘텐츠 레이어 (탐색기·설정 앱 2계층 구조)
- 시스템 라이트/다크·강조색 자동 추종 (FsThemeService, FsPalette.Light/Dark)
- 강조색은 시스템 강조색에서 WCAG AA 대비를 보정해 파생 (FsAccentPalette)
- Segoe UI Variable 타입 램프, 최소 12px, 반경 4/8px, 카드 중첩 제거
- 네온 시안·더블 베젤·그라디언트 버튼·Inter 서체 폐기
- 전 창 적용: 메인·빠른 옵션/진행·설정·도구 설치·진단, 광고는 중립 카드로
- 결함 수정: 사이드바 체크박스 라벨 잘림, 행 체크박스 잘림, 입력란 이중 여백,
  제목 표시줄 아이콘 검게 렌더, '큐'/'대기열' 용어 혼용
- Google AdMob 광고 단위 연동 (AdHtmlBuilder, 설정 창 AdMob 카드)
- Win11NativeDesignTests 계약 테스트, VisualCaptureHarness 시각 E2E 캡처
2026-10-06 02:45:13 +09:00

148 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# design.md — Everything2Everything 디자인 결정 SSOT
> 2026-10-06 리디자인: **Windows 11 정통 네이티브**. 이전 방향("아크릴 & 네오 글래스 + 네온 시안")은 폐기했다.
> 폐기 이유는 §7, 바꿀 때 지켜야 할 계약은 `src/Everything2Everything.Tests/Win11NativeDesignTests.cs`.
---
## 1. 브리프 (0단계 · 사용자 인터뷰 2026-10-06)
```
무엇을: Everything2Everything(.NET 9 WPF + Wpf.Ui 4.3) 전 창을 Windows 11 정통 네이티브 언어로 리디자인
누구에게: 탐색기 우클릭·일괄 변환을 쓰는 사용자 — 옵션을 빨리 고르고 결과를 믿고 넘기길 원함
제약: 3분할 정보 구조 유지 · 광고 두 자리 유지 · 시스템 라이트/다크·강조색 추종 · TDD(실패 0)
기본 언어 ko-KR 한국어, 영어는 기술 용어(EXIF·CRF·kbps 등)만
```
| 인터뷰 질문 | 사용자 답 |
|---|---|
| 시각 방향 | **Windows 11 정통 네이티브** (Mica, 시스템 강조색, Segoe UI Variable, 라이트/다크 자동) |
| 레이아웃 범위 | **3분할 유지 + 정돈** |
| 대상 창 | **메인 · 우클릭 빠른 창(옵션/진행) · 설정 · 도구 설치 · 진단** 전부 |
| 광고 | **현 두 자리 유지** (목록 하단 배너 + 미리보기 하단 카드) |
### 리디자인 전 감사 (무너져 있던 것)
1. 사이드바 체크박스 라벨이 잘림 — "무손실(Lossless) 보존 (WebI…"
2. 거의 검은 바탕 + 네온 시안 하나: AI 생성 디자인의 가장 흔한 지문. "네오 글래스"라 했지만 실제 렌더는 평평한 상자
3. 카드 안 카드 4중 중첩, 10~11px 글자 남발, 3차 텍스트 대비 부족
4. Mica를 켜 놓고 85% 불투명 흑색(#D80A0C10)으로 덮어 Mica가 보이지 않음
5. "큐"와 "대기열"이 같은 대상을 두 이름으로 부름
---
## 2. 레퍼런스 (1단계 · 정본 실측)
| 슬롯 | 출처 | 가져온 것 (실측값) |
|---|---|---|
| R1 구조 | learn.microsoft.com/windows/apps/design/signature-experiences/**layering** | 2계층: 베이스(Mica, 내비·명령) + 콘텐츠 레이어(앱의 중심 경험). 카드 elevation 8, 컨트롤 2, stroke 1 |
| R2 톤 | …/signature-experiences/**typography** | Segoe UI Variable 12/16 캡션 · 14/20 본문 · 20/28 부제 · 28/36 제목. **최소 14 Semibold / 12 Regular**. 문장형 대소문자. Bold·Italic 대신 Semibold |
| R3 디테일 | …/signature-experiences/**geometry** | 컨트롤·리스트 4px, 창·플라이아웃·대화상자 8px, 맞닿는 직선 모서리 0px |
탐색기·설정 앱의 서명인 **"사이드 영역은 Mica 위, 본문은 왼쪽 위 모서리만 둥근 콘텐츠 레이어"**를 그대로 차용했다.
---
## 3. 방향 (2단계)
- **한 문장 컨셉**: 탐색기에서 이어지는 작업창. 우클릭에서 태어난 도구라 메인 창도 탐색기·설정 앱과 같은 재질과 위계를 쓴다.
- **과감한 한 가지(표현 리스크)**: 85% 불투명 흑색 덮개를 걷고 **Mica를 실제로 비치게** 했다. 사이드바·제목 표시줄은 Mica 위(베이스), 대기열과 미리보기는 `CornerRadius="8,0,0,0"`인 하나의 콘텐츠 레이어(`ContentLayer`)에 올렸다.
- 검증: 라이트/다크 실앱 캡처에서 두 층이 구분되는지, 텍스트가 4.5:1을 넘는지(자동 테스트)
- **반사실 점검**: 이 선택은 "Windows 셸 확장 도구"라는 이 앱의 정체성에서만 나온다. 다른 업종의 랜딩 페이지라면 나오지 않는다.
- **표면 다이얼**: 표현성 1 · 정보 밀도 2 · 모션 1(호버·눌림 상태만) · 텔레메트리 1(엔진 상태 점 하나)
---
## 4. 토큰 (3단계)
### 4.1 색 — `Views/Themes/FsPalette.{Dark|Light}.xaml`
값은 WinUI 공용 테마 리소스에서 가져왔다. 두 파일의 키 집합은 같아야 한다(테스트로 강제). 모든 Fs 색은 **DynamicResource**로 참조하며(테스트로 강제), `FsThemeService`가 시스템 테마에 맞춰 사전을 갈아 끼운다.
| 역할 | 다크 | 라이트 | WinUI 원천 |
|---|---|---|---|
| FsBgBase | 투명 | 투명 | Mica가 비친다 |
| FsBgLayer | #4C3A3A3A | #80FFFFFF | LayerFillColorDefault |
| FsBgCard | #0DFFFFFF | #B3FFFFFF | CardBackgroundFillColorDefault |
| FsBgControl | #0FFFFFFF | #B3FFFFFF | ControlFillColorDefault |
| FsBorderSubtle | #19000000 | #0F000000 | CardStrokeColorDefault |
| FsTextPrimary/Secondary | #FFFFFF / #C5FFFFFF | #E4000000 / #9E000000 | TextFillColor* |
| FsTextTertiary | #87FFFFFF | **#8B000000** | WinUI 라이트 기본 #72는 3.3:1이라 4.5:1로 보정 |
| 상태(성공/경고/위험/정보) | #6CCB5F · #FCE100 · #FF99A4 · #60CDFF | #0F7B0F · #9D5D00 · #C42B1C · #005FB8 | SystemFillColor* |
**강조색**은 고정값이 없다. `FsAccentPalette.From(시스템 강조색, 테마)`가 색상·채도는 유지하고 명도만 밀어, 다음을 보장한다(9가지 극단 강조색으로 테스트).
- 다크: 밝은 채움 + 검정 글자 / 라이트: 어두운 채움 + 흰 글자 — 버튼 글자 ≥ 4.5:1(호버 포함)
- 강조 텍스트(FsAccentText)는 가장 불리한 면에서도 ≥ 4.5:1
형식 색(FsFmt*)은 두 테마가 같다. 채움으로 쓰지 않고 **외곽선·점으로만** 써서, 형식 색이 무엇이든 글자는 본문색으로 대비를 유지한다.
### 4.2 타이포 — `FormatShiftTheme.xaml`
- FsFontSans `Segoe UI Variable Text, Segoe UI, Malgun Gothic`(한글은 Malgun Gothic 폴백) · FsFontDisplay(Variable Display) · FsFontMono `Cascadia Mono, Consolas`(경로·키 입력에만)
- 스타일: FsCaptionStyle 12/16 Secondary · FsBodyStyle·FsLabelStyle 14/20 · FsSectionHeaderStyle 14 Semibold · FsSubtitleStyle 20/28 Semibold · FsNumStyle(캡션 + tabular 숫자)
- **최소 12px**(테스트로 강제). 숫자는 모노 서체 대신 Segoe의 고정폭 숫자를 쓴다.
### 4.3 기하 · 간격
- CornerRadius ∈ {0, 2, 4, 8}(테스트로 강제). 컨트롤 4 · 카드·창·오버레이 8 · 탭 표시줄 2
- 간격 4의 배수. 카드 패딩 16, 카드 간격 8, 창 가장자리 16/24
- 컨트롤 높이 32, 사이드바 주 버튼 40, 제목 표시줄 48(메인, WinUI Tall) / 42(대화상자)
### 4.4 컴포넌트 문법
- 버튼 위계: **FsAccentButtonStyle은 창마다 하나**(메인=변환 시작 / 빈 대기열=파일 찾기 / 설정=저장 / 도구 설치=설치 시작) · 나머지는 FsSecondaryButtonStyle · 아이콘만 있으면 FsIconButtonStyle
- 카드: FsCardStyle 한 단계만. **카드 안에 카드 금지**(테스트로 강제)
- 탭: 텍스트 + 강조색 밑줄 3×16px(WinUI SelectorBar)
- 입력: 채움 + 1px 외곽, 포커스 시 강조색 하단선 2px
- 슬라이더: 4px 트랙, 18px 썸(외곽 + 강조색 점, 호버 시 커지고 끌 때 작아짐)
### 4.5 성능 예산
WPF 데스크톱이라 웹 예산은 적용하지 않는다. 추가 이펙트(블러·그림자·애니메이션)는 0개. 렌더 비용은 Mica(OS 합성)뿐이다.
---
## 5. 화면별 결정 (4단계)
| 창 | 결정 |
|---|---|
| 메인 | 사이드바 = Mica 위 설정 카드 3장(변환 설정 · 저장 위치 · AI 작업). 통계 카드는 없애고 하단 한 줄 "오늘 변환 · 줄인 용량"으로. 콘텐츠 레이어 안에 검색 툴바 · 대기열/기록 · 미리보기. 빈 대기열은 **목록 영역 전체를 점선 드롭 대상**으로 보여 주고, 미선택 시 파일 정보 블록은 숨긴다 |
| 우클릭 빠른 옵션 | Mica 적용(이전 None). 제목 20px, 값은 tabular 숫자 |
| 빠른 진행 | 여백 24, 진행 막대 4px |
| 설정 | 카드 3장(AI · 외부 도구 · 광고), 긴 체크박스 라벨은 줄바꿈, 하단 바는 레이어 면 |
| 도구 설치 | 도구마다 카드 한 장, 카드 간격 4 |
| 진단 | Mica 적용. 코드로 만드는 카드도 FsCardStyle과 팔레트 토큰을 쓰고 `SetResourceReference`로 테마를 따른다 |
| 광고 | 자리 유지. **강조색을 쓰지 않는 중립 카드**로 낮춰 작업 도구보다 먼저 시선을 끌지 않게 했다(배지 "광고", CTA는 표준 버튼) |
### 카피
- 같은 대상은 한 이름: "큐" → **"대기열"**(코드 문자열까지 테스트로 강제)
- 사이드바 체크 라벨은 카드 안쪽 폭에서 한 줄(16자 이내). 한글이 낱자로 끊기지 않게 한다
---
## 6. 검증 결과 (5단계)
- 자동: 전체 **429개 통과 · 실패 0 · 빌드 경고 0**. 새 계약 테스트는 `Win11NativeDesignTests`(강조색 대비 9종 × 테마, 팔레트 키 대칭·대비, 동적 참조, 하드코딩 색 금지, 최소 12px, 반경 단계, 카드 중첩 금지, Mica, 콘텐츠 레이어, 카피 어휘, 회귀 3종)
- 시각: 실앱(E2E_THEME=dark/light) 캡처와 `VisualCaptureHarness`(창 6개 × 2테마, 채워진 대기열 포함)를 직접 열어 판정했다
- 렌더 감사에서 잡아 게이트에 추가한 실측 결함 4건:
1. 제목 표시줄(DWM 확장 영역) 안에서 **SymbolIcon이 Button의 직접 콘텐츠면 Foreground가 흰색이어도 검게 합성**됨 → 패널로 감쌈 (`TitleBarButtons_MustNotHostSymbolIconDirectly`)
2. Wpf.Ui CheckBox 기본 MinWidth 때문에 32px 열의 행 체크박스가 반쯤 잘림 → `MinWidth="0"`
3. TextBoxBase가 Padding을 콘텐츠 호스트에 넘기는데 바깥 Border에도 Padding을 줘서 글자가 22px 들여 씌어짐 → Border Padding 제거
4. 이미 표시된 FluentWindow에 `ApplicationThemeManager.Apply(element)`를 걸면 AllowsTransparency 예외로 크래시 → 창을 만들기 전에만 테마 적용
- 미검증: 실제 OS 테마를 실행 중에 바꿨을 때의 전환(코드 경로는 `SystemEvents.UserPreferenceChanged` → `ApplySystemTheme` → 팔레트 교체). 고대비 모드. 125%/150% 배율 실기기.
### 시각 검증 방법
```powershell
# 실앱 테마 강제 (QA 전용)
$env:E2E_THEME="light"; .\Everything2Everything.exe
# 오프스크린 캡처 (창 6개 × 라이트/다크)
$env:E2E_CAPTURE_DIR="C:\temp\e2e"; dotnet test src/Everything2Everything.Tests --filter FullyQualifiedName~VisualCaptureHarness
```
---
## 7. 의도적으로 하지 않은 것과 그 이유
1. **네온 시안 · 고정 강조색 폐기** — 사용자가 OS에서 고른 강조색이 곧 이 앱의 강조색이다. 고정색은 "Windows의 일부" 컨셉과 충돌한다.
2. **더블 베젤(카드 안 카드) · 그라디언트 섬 버튼 · 림라이트 폐기** — Windows 11에 없는 문법이고, 중첩은 위계를 흐린다.
3. **Inter · JetBrains Mono 폐기** — 시스템에 없는 서체라 실제로는 Segoe/Consolas로 폴백되고 있었다. 시스템 서체를 명시했다.
4. **10~11px 글자 폐기** — MS 최소 기준(12 Regular) 미만은 한글에서 특히 안 읽힌다.
5. **광고에 강조색을 쓰지 않음** — 창마다 강조 버튼은 하나("변환 시작")라는 위계를 광고가 깨지 않게 했다.
6. **진입 애니메이션 · 호버 글로우 없음** — 일괄 작업 도구는 즉시 반응이 미덕이다. 상태 변화(호버·눌림·포커스)만 표시한다.
7. **레이아웃 3분할은 바꾸지 않음** — 사용자 결정. 비율과 위계, 빈 상태만 정돈했다.
8. **배너 광고 HTML(`AdHtmlBuilder`)은 손대지 않음** — 커밋되지 않은 AdMob 작업이고, 실제 광고의 모양은 앱이 통제할 수 없다. 라이트 테마에서는 테스트 배너만 어둡게 보인다(후속 과제).
9. **테스트 시간 10초 예산은 이번에 다루지 않음** — 리디자인 전부터 28초였다(현재 21초). 별도 과제.