범용 PySide6 UI/UX 아키텍처 스킬
PySide6로 모든 애플리케이션 도메인을 위한 깔끔하고 반응형이며 인간 중심적인 데스크톱 인터페이스를 설계하고 구축합니다. 항상 대상 프로젝트의 기존 테마, 위젯 및 규칙을 먼저 검사하여 기존 추상화를 덮어쓰지 않고 자연스럽게 통합하십시오. 현재 작업에 필요한 특정 참조 파일만 로드하십시오.
1. 프로그레시브 디스클로저 라우팅 (요청 시 읽기)
- 테마, QSS 스타일시트, 라이트/다크 모드, HiDPI 또는 레이아웃 기본 요소 →
./references/design-system-and-qss.md읽기 - 메인 윈도우 아키텍처, 사이드바, 탭, 도크, 스플리터 또는 대시보드 →
./references/navigation-and-shell.md읽기 - 데이터 테이블, 목록, 트리, 검색 막대, 필터 또는 빈/로딩 상태 →
./references/data-tables-and-filters.md읽기 - 모달 다이얼로그 (
QDialog), 폼, 세부 정보 서랍, 검증 또는 토스트/진행률 피드백 →./references/forms-dialogs-and-feedback.md읽기 - 키보드 단축키, 접근성, i18n/RTL 레이아웃 또는 백그라운드 스레딩 →
./references/accessibility-i18n-and-async.md읽기 - 기존 테마가 없는 완전히 새로운 PySide6 앱 부트스트래핑 → 선택적으로
./assets/base-theme.qss참조
2. 보편적인 UX 법칙 (데스크톱 UI에 적용)
- Jakob의 법칙: 확립된 데스크톱 규칙 (
Ctrl+S저장,Ctrl+F검색,Esc취소/지우기,F5새로고침, 표준 메뉴/툴바 배치)을 따르므로 사용자가 즉시 익숙함을 느낍니다. - Fitts의 법칙: 기본 작업은 충분히 크게 (
>= 36px높이, 터치/고빈도 워크플로우의 경우>= 42px) 유지하고 사용자의 주의가 이미 있는 곳 근처에 고정합니다. 반복 작업을 위해 마우스를 멀리 이동해야 하는 상황을 피하십시오. - Hick의 법칙 및 프로그레시브 디스클로저: 한 번에 표시되는 선택 항목을 제한하십시오. 보조 옵션은 모든 컨트롤을 한 화면에 집어넣는 대신 서랍, 탭 또는 오버플로 메뉴로 그룹화하십시오.
- Miller의 법칙 및 게슈탈트 근접성: 관련 컨트롤을 깔끔한 시각적 그룹(
CardFrame)으로 청크화하고 그룹 내에서는8px, 그룹 간에는16px–24px의 일관된 간격을 사용하여 사용자가 구조를 쉽게 스캔할 수 있도록 하십시오. - Doherty 임계값 (
< 400ms인지 응답 시간): Qt 이벤트 루프를 절대 중단시키지 마십시오. I/O, 네트워크 및 무거운 계산은 메인 스레드에서 오프로드(QThreadPool/QRunnable)하고 즉각적인 로딩 또는 진행률 피드백을 표시하십시오. - 오류 방지 및 안전한 복구: 제출 전에 인라인으로 검증하고, 불가능한 작업은 비활성화한 후 그 이유를 명확한 툴팁으로 설명하며, 파괴적이거나 되돌릴 수 없는 작업에 대해서만 명시적 확인을 요구하십시오.
3. 기본 디자인 시스템 토큰 (적응 가능)
프로젝트가 이미 팔레트, 타이포그래피 또는 간격 시스템을 정의하고 있다면 프로젝트의 토큰을 따르십시오. 그렇지 않으면 다음과 같은 깔끔하고 고대비 기본값을 사용하십시오:
- 강조 및 포커스:
- 기본 강조색:
#0F766E(호버:#0D5F59, 누름:#0A4A45, 소프트 틴트:#CCFBF1/#F0FDFA) — 또는 앱의 브랜드 색조에 맞게 조정하십시오. - 포커스 링: 모든 대화형 입력 및 버튼에
2px solid기본 강조색.
- 기본 강조색:
- 중립 표면 계층 구조 (라이트 / 다크):
- 앱 캔버스:
#F8FAFC(라이트) /#0F172A(다크) - 상승 표면 / 카드:
#FFFFFF(라이트) /#1E293B(다크) - 미묘한 보조 표면 (헤더, 푸터, 얼룩말 무늬):
#F1F5F9(라이트) /#334155(다크) - 가는 테두리 / 구분선:
#E2E8F0(라이트) /#334155(다크) - 기본 입력 테두리:
#CBD5E1(라이트) /#475569(다크)
- 앱 캔버스:
- 타이포그래피 및 잉크 계층 구조:
- 기본 텍스트:
#0F172A(라이트) /#F8FAFC(다크) - 보조 / 레이블 텍스트:
#475569(라이트) /#CBD5E1(다크) - 음소거 / 비활성화 텍스트:
#94A3B8(라이트) /#64748B(다크) - 글꼴 스택:
"Segoe UI", "Inter", "Cairo", system-ui, sans-serif(라틴어, 아랍어 및 다국어 UI를 깔끔하게 지원합니다). - 타입 스케일: 페이지 제목
20pxBold, 섹션 제목15pxSemiBold, 본문/셀13pxRegular, 레이블/캡션12pxMedium, 히어로 메트릭22px–26pxBold.
- 기본 텍스트:
- 의미론적 상태 토큰:
- 성공: 텍스트
#15803D, 채움#DCFCE7(다크:#4ADE80/#14532D) - 경고: 텍스트
#B45309, 채움#FEF3C7(다크:#FBBF24/#451A03) - 위험: 텍스트
#B91C1C, 채움#FEE2E2(다크:#F87171/#450A0A) - 정보: 텍스트
#0369A1, 채움#E0F2FE(다크:#38BDF8/#0C4A6E)
- 성공: 텍스트
- 간격 및 기하학:
- 간격 척도:
4px(좁음),8px(관련 요소),12px(툴바/폼 간격),16px(카드 패딩),20px–24px(페이지 여백). - 컨트롤 높이: 표준 입력/버튼
36px, 고빈도/터치 컨트롤42px+, 테이블 헤더38px, 테이블 행>= 42px. - 테두리 반경: 컨트롤
6px, 카드/패널10px, 모달12px, 상태 알약11px.
- 간격 척도:
4. 절대 불가침 PySide6 엔지니어링 규칙
- 먼저 기존 코드베이스에 적응하십시오: 새 추상화를 도입하기 전에 기존 테마 상수, 기본 위젯 및 헬퍼를 재사용하십시오.
- 깔끔한 공간 그룹화: 무거운 중첩
QGroupBox테두리 대신QFrame카드 (1px가는 테두리, 미묘한 표면 대비) 또는QSplitter창을 사용하십시오. - 테이블 및 트리 데이터를 위한 모델/뷰:
QAbstractItemModel(QAbstractTableModel),QSortFilterProxyModel및QStyledItemDelegate와 함께QTableView/QTreeView를 사용하십시오.QTableWidget셀에 무거운 중첩 위젯을 채우지 마십시오. - 인라인 스파게티 대신 의미론적 QSS: 원시
setStyleSheet(...)문자열을 흩뿌리지 말고setObjectName(...)역할 (PrimaryButton,DangerButton,Card,PageTitle)과 동적 속성([invalid="true"]와 함께unpolish()/polish())을 통해 스타일을 지정하십시오. - 반응형 레이아웃 (고정 컨테이너 크기 없음): 윈도우, 카드 또는 테이블에
setFixedSize()를 절대 호출하지 마십시오. 레이아웃, 스트레치 팩터,QSizePolicy및QScrollArea에 의존하여 UI가 다양한 해상도, HiDPI 디스플레이 및 번역된 텍스트 길이에 걸쳐 깔끔하게 확장되도록 하십시오. - 비활성화 상태 설명 및 인라인 검증: 모든
setEnabled(False)호출에는 비활성화된 이유를 설명하는setToolTip(...)이 반드시 포함되어야 합니다. 입력은 도우미 오류 레이블로 인라인 검증하십시오.QMessageBox로 타이핑을 절대 중단시키지 마십시오. - 작업당 하나의 정식 위치: 동일한 작업을 상단 막대와 하단 바닥글에 절대 중복 배치하지 마십시오. 페이지 수준 CTA는
PageHeader의 오른쪽 상단에, 기본 폼/다이얼로그 CTA는 모달 바닥글의 오른쪽 하단에 배치하십시오. - 키보드 우선 및 비블로킹 피드백:
showEvent()에서 초기 포커스를 설정하고,setTabOrder()를 연결하고,Enter/Esc를 지원하며, 일상적인 확인에는 비블로킹 오버레이 토스트 또는 상태 표시줄을 사용하고 모달 다이얼로그는 파괴적 확인을 위해 남겨두십시오. - 절제되고 내용에 맞는 상태 배지: 테이블 상태 알약을 넓은 균일 고정 너비로 늘리거나 모든 정상 행을 무거운 채도 배지로 채우지 마십시오. 알약 너비를
QFontMetrics.horizontalAdvance(text) + padding으로 동적으로 맞추고, 일상적인 정상 상태는 시각적으로 조용하게 유지(예: 미묘한7px상태 점 + 선명한 텍스트)하여 경고/오류가 즉시 눈에 띄게 하고, 사용자 정의QStyledItemDelegate.paint()재정의 내에서 행 선택과 하단 가는 구분선을 유지하십시오.
5. 사전 점검 품질 관문
PySide6 UI 구현을 마무리하기 전에 다음을 확인하십시오:
- 모든 보기에 명확한 시각적 계층 구조(
PageHeader또는 구조화된 작업 공간 막대)가 있고 떠다니는 분리된 컨트롤이 없습니까? - 모든 대화형 컨트롤이 균일한 높이(
>= 36px), 명확한 호버/포커스 상태 및 충분한 색상 대비를 공유합니까? - 숫자/테이블 열이 오른쪽 정렬되고 앱의 로케일에 따라 형식이 지정되었습니까?
- 테이블 상태 배지가 텍스트에 맞게 크기가 조정되고, 정상 행에서 시각적으로 차분하며, 행 선택 및 구분선과 매끄럽게 정렬되었습니까?
- 빈 상태, 일치 항목 없음 및 로딩 상태가 빈 공백 대신 전용
QStackedWidget상태를 사용합니까? - 비활성화된 모든 컨트롤이
setToolTip()을 통해 스스로를 설명합니까? - 장기 실행 작업이 UI 스레드에서 오프로드되어 창이 절대 멈추지 않습니까?