Skip to content

windows-ui-ux-handoff.md

Latest commit

 

History

History
200 lines (159 loc) · 9.58 KB

windows-ui-ux-handoff.md

File metadata and controls

200 lines (159 loc) · 9.58 KB
Raw

Windows UI/UX 전달 사항

Last updated: 2026-07-31 KST

목적

이 문서는 macOS에서 정리한 VPN Router의 제품 흐름을 Windows WinUI 화면에 옮길 때 지켜야 할 작업 범위와 확인 기준입니다. Windows와 macOS는 같은 제품처럼 보여야 하지만, SwiftUI 화면의 픽셀 값이나 구성 요소를 그대로 복사하지 않습니다.

Windows 작업을 시작하기 전에 다음 문서를 함께 읽습니다.

  • AGENTS.md
  • docs/windows-next-session.md
  • docs/windows-mvp-handoff.md
  • docs/windows-mvp-progress.md
  • docs/windows-release-hardening.md
  • docs/ui-design-principles.md
  • docs/platform-parity-contract.md

네트워크, WireGuard, DNS, 경로, 권한 상승, 휴대용 실행 파일과 복구 동작은 이번 UI 작업의 변경 대상이 아닙니다. 화면 변경 때문에 기존 IPC 계약이나 안전 동작을 바꾸지 않습니다.

현재 Windows 화면에서 확인된 문제

기준 파일은 windows/VpnRouter.App/MainWindow.xaml입니다.

  • 홈의 큰 동심원과 원형 연결 버튼은 다른 VPN 제품과 비슷해 보일 수 있습니다.
  • 최상위 Grid가 RequestedTheme="Light"로 고정되어 시스템 다크 테마를 따르지 않습니다.
  • 각 화면의 본문이 Width="900"으로 고정되어 작은 창, 화면 배율, 긴 글자에서 유연하게 줄어들기 어렵습니다.
  • 홈 하단 두 카드는 2* : 3* 비율이라 선택한 VPN 프로필과 최근 상태 사이의 시각적 무게가 다릅니다.
  • VPN 프로필 화면은 가져오기, 선택, 이름 변경과 삭제가 한 카드에 모여 있어 첫 작업과 저장된 항목 관리의 구분이 약합니다.
  • 페이지별 여백이 36/28, 42/34, 28 등으로 나뉘어 공통 리듬이 일정하지 않습니다.
  • 색과 스타일 자원이 MainWindow.xaml 안에 집중되어 있어 테마별 관리와 다른 창에서의 재사용이 어렵습니다.

Windows에서 유지할 제품 구조

다섯 영역과 사용자에게 보이는 이름은 유지합니다.

  1. 홈
  2. VPN 프로필
  3. VPN 사이트
  4. 문제 해결
  5. 설정

홈에서 사용자가 가장 먼저 이해해야 할 내용은 다음 세 가지입니다.

  • 현재 연결 상태
  • 선택한 VPN 프로필과 사이트
  • 연결 또는 연결 해제 동작

문구는 사용자가 대화에서 사용한 VPN 프로필, VPN 사이트, 선택 사이트, 연결, 연결 해제, 최근 상태, 문제 해결을 우선합니다. 메인 화면에는 DNS Proxy, Named Pipe, /32, 인터페이스 번호 같은 내부 용어를 새로 노출하지 않습니다.

화면별 작업 지시

1. 공통 창과 탐색

  • NavigationView와 WinUI 기본 선택 표시, 포커스 표시, 키보드 이동을 유지합니다.
  • 고정 Light 테마를 제거하고 Windows의 Light, Dark, High Contrast 설정을 따릅니다.
  • 현재 Width="900" 대신 HorizontalAlignment="Stretch"와 적절한 MaxWidth를 사용합니다. 넓은 창에서는 본문이 지나치게 벌어지지 않고, 좁은 창에서는 가로 스크롤 없이 줄어들어야 합니다.
  • 페이지 제목, 설명, 카드 사이의 바깥 여백과 세로 간격을 공통 자원으로 정리합니다.
  • 코랄색은 현재 선택, 주 연결 동작과 중요한 상태에만 사용합니다.
  • 스타일과 테마 자원은 가능하면 App.xaml 또는 별도 ResourceDictionary로 옮깁니다.

2. 홈

  • 큰 원형 연결 버튼과 동심원 장식을 제거합니다.
  • 상태 설명 옆이나 아래에 아이콘과 글자가 함께 있는 넓은 직사각형 연결 또는 연결 해제 버튼을 둡니다. Windows 기본 Button 상태와 키보드 포커스가 분명해야 합니다.
  • 홈의 기억할 만한 요소는 이 PC → 선택 사이트 → VPN 연결 경로로 정합니다. macOS의 SF Symbols나 정확한 크기를 복사하지 말고, WinUI 아이콘과 선으로 Windows 방식으로 표현합니다.
  • 선택한 VPN 프로필과 최근 상태 카드는 넓은 창에서 같은 폭, 같은 높이, 같은 상단 기준선으로 배치합니다.
  • 두 카드의 내용이 다르더라도 카드 배경은 같은 행 높이를 채워야 합니다. 현재 2* : 3* 열은 같은 비율의 두 열로 바꿉니다.
  • 좁은 창에서는 두 카드를 전체 폭의 한 열로 쌓습니다. 세로 배치에서는 두 카드의 높이를 억지로 같게 만들지 않습니다.

3. VPN 프로필

  • 넓은 창에서는 프로필 가져오기와 저장된 프로필을 같은 폭과 높이의 두 카드로 나눕니다.
  • 프로필 가져오기에는 파일 선택, 가져올 파일 이름과 가져오기 결과를 둡니다.
  • 저장된 프로필에는 현재 선택, 이름 변경과 삭제를 둡니다.
  • WireGuard 설치 상태와 이전 실행 캐시 정리는 두 카드 아래의 전체 폭 보조 카드로 유지합니다.
  • 좁은 창에서는 프로필 가져오기 다음에 저장된 프로필이 오도록 한 열로 전환합니다.
  • 실제 프로필 원문이나 개인 키를 미리 보기로 표시하지 않습니다.

4. VPN 사이트

  • 사이트 입력과 저장된 사이트 목록을 첫 카드로 묶습니다.
  • 현재 IPC에서 안전하게 제공되는 값만 사용해 선택 프로필, 저장된 사이트 수와 연결 준비 상태를 두 번째 카드에 요약할 수 있습니다.
  • 경로 IP, DNS 응답과 원문 도메인 진단처럼 제한된 정보는 메인 카드에 새로 노출하지 않습니다.
  • 두 카드를 사용하는 경우 홈과 같은 동일 폭·높이·상단 정렬 및 좁은 창 한 열 전환 규칙을 적용합니다.

5. 문제 해결과 설정

  • 문제 해결은 연결 상태, 진단 파일, 네트워크 설정 복구의 순서를 유지합니다.
  • 네트워크 설정 복구는 위험한 동작임을 글과 아이콘으로 알리고 기존 확인 절차를 유지합니다.
  • 설정은 실제로 동작하는 필수 연결 보호만 설명합니다. 구현되지 않은 선택 기능이나 보호 모드를 다시 추가하지 않습니다.
  • 이 두 화면은 읽기 흐름이 중요한 한 열 카드 구성을 유지해도 됩니다.

WinUI 배치 구현 기준

  • 넓은 화면의 카드 쌍은 같은 Grid 행과 같은 비율의 열을 사용합니다. 두 Border가 행의 전체 높이를 채우도록 VerticalAlignment="Stretch" 상태를 확인합니다.
  • VisualStateManager 또는 동등한 WinUI 반응형 방식으로 넓은 두 열과 좁은 한 열을 전환합니다.
  • 화면 폭을 코드 뒤에서 임의 계산하기보다 WinUI 레이아웃과 시각 상태를 우선합니다.
  • 카드 제목, 본문과 동작의 정렬 기준은 왼쪽과 위쪽으로 통일합니다.
  • 고정 높이는 연결 상태 영역처럼 최소 크기가 필요한 곳에만 사용합니다. 내용 카드에 서로 다른 MinHeight를 따로 주어 눈속임으로 맞추지 않습니다.
  • 긴 한국어 문구, 빈 목록, 여러 항목, 오류 문구가 들어와도 카드가 겹치거나 잘리지 않아야 합니다.

접근성과 상태 표현

  • 모든 아이콘 전용 버튼에 AutomationProperties.Name 또는 분명한 ToolTip을 제공합니다.
  • 색만으로 연결됨, 연결 중, 실패를 구분하지 않습니다. 글자와 아이콘을 함께 사용합니다.
  • Tab과 방향키만으로 탐색, 프로필 선택, 사이트 추가, 연결과 복구 동작에 접근할 수 있어야 합니다.
  • 연결 중에는 중복 요청을 막고 진행 상태를 읽을 수 있게 합니다.
  • 실패 문구에는 실패한 단계와 사용자가 다음에 할 일을 함께 표시합니다.
  • Windows 화면 배율 100%, 150%, 200%와 High Contrast에서 확인합니다.

수정 범위 제안

우선 수정 대상:

  • windows/VpnRouter.App/MainWindow.xaml
  • windows/VpnRouter.App/App.xaml

필요한 경우에만 수정:

  • windows/VpnRouter.App/MainWindow.xaml.cs

UI에 필요한 상태가 기존 IPC 응답에 없다면 값을 지어내지 않습니다. 먼저 현재 응답으로 표현 가능한지 확인하고, 새 계약이 꼭 필요하면 네트워크 동작과 분리된 읽기 전용 요약 값으로 설계한 뒤 별도 검토합니다.

Windows에서 반드시 확인할 항목

macOS에서는 WinUI XAML 컴파일과 실제 렌더링을 증명할 수 없습니다. Windows 11 x64에서 다음을 모두 확인합니다.

  1. windows/VpnRouter.slnx와 windows/VpnRouterVs.sln 빌드
  2. 현재 focused test 전체 통과
  3. WinUI XAML 컴파일 오류 없음
  4. 기존 기준인 1120 × 780과 더 좁은 창에서 겹침·잘림·가로 스크롤 없음
  5. Light, Dark, High Contrast와 화면 배율 100%, 150%, 200%
  6. 키보드 전용 탐색과 Narrator 이름·상태 읽기
  7. 빈 프로필·빈 사이트, 긴 이름·긴 오류, 연결 중·실패·연결됨 상태
  8. 두 열 카드의 같은 폭·높이·상단 정렬과 한 열 전환
  9. 연결, 연결 해제, 창 닫기·다시 열기와 복구 동작에 회귀 없음
  10. Windows 코드와 자동 검사 결과를 docs/windows-mvp-progress.md에 기록

완료 기준

  • 다른 VPN 제품의 큰 원형 연결 화면을 따라 한 인상이 사라집니다.
  • macOS와 같은 제품 흐름과 단어를 사용하지만 WinUI 기본 동작을 유지합니다.
  • 같은 행의 카드 크기와 정렬이 안정적이며 작은 창에서도 자연스럽게 한 열로 전환됩니다.
  • 시스템 테마, 키보드, Narrator와 High Contrast가 동작합니다.
  • 네트워크와 권한 상승 동작은 변경되지 않고 Windows의 기존 빌드와 검사가 통과합니다.