PDFToMD/docs/UI_GUIDE.md

UI 디자인 가이드

UI는 2차 목표입니다. 1차 MVP에서는 CLI/라이브러리 변환 엔진을 먼저 안정화합니다.

디자인 원칙

1. 표준 Windows 환경에 맞는 미니멀한 UI를 따른다.
2. 변환 엔진 로직을 UI에 중복 구현하지 않는다.
3. PyQt UI는 core Python API 또는 CLI를 호출하는 thin client로 둔다.
4. 긴 문서 변환 중 사용자가 현재 상태를 파악할 수 있어야 한다.
5. 오류와 경고는 읽기 쉬운 방식으로 보여주되, 생성 Markdown을 오염시키지 않는다.

주요 화면

• PDF 선택
• 출력 폴더 선택
• runtime 선택: cuda, auto, cpu
• formula parser 선택: nougat, marker
• chunk size 표시 및 기본값 유지
• 진행률과 chunk별 상태 표시
• 실패 chunk 요약
• resume 실행 버튼
• local log 열기

Interaction Rules

• 기본값은 CLI 기본값과 동일해야 한다.
• cuda 명시 실행에서 CUDA 초기화 실패 시 CPU fallback을 자동으로 하지 않고 명확히 실패를 표시한다.
• auto 실행에서 CUDA 실패 시 경고 후 CPU fallback 상태를 표시한다.
• 변환 중 취소가 가능해야 한다.
• 성공한 chunk와 실패한 chunk가 구분되어야 한다.

Visual Style

• Windows native에 어울리는 절제된 색상과 간격을 사용한다.
• 작업 도구 UI이므로 marketing hero나 장식적 layout은 사용하지 않는다.
• 긴 파일명과 한글 경로가 잘리지 않도록 middle ellipsis 또는 tooltip을 제공한다.
• 로그와 결과 경로는 복사 가능한 텍스트로 제공한다.

Boundary

• UI는 src/ core package의 public API 또는 CLI만 호출한다.
• UI에서 Marker/Nougat/PyMuPDF를 직접 조합하지 않는다.
• UI 테스트는 core conversion quality test와 분리한다.