Communitygithub.com

pyside6-ui

모든 데스크톱 애플리케이션을 위한 범용 PySide6 / Qt for Python UI/UX 아키텍처 및 디자인 시스템 스킬입니다. PySide6 윈도우, 내비게이션 셸, QSS 테마, 대시보드, 데이터 테이블, 검색/필터 막대, CRUD 폼, 모달 다이얼로그, 비동기 응답성, RTL/i18n 또는 키보드 워크플로우를 설계, 구축, 리팩터링, 스타일링 또는 검토할 때 항상 사용하세요.

pyside6-ui란 무엇인가요?

이 스킬은 PySide6 (Qt for Python) 기반 데스크톱 애플리케이션 개발을 위한 포괄적인 UI/UX 아키텍처 및 디자인 시스템 가이드입니다. 개발자는 이 스킬을 사용하여 일관된 디자인 원칙과 엔지니어링 규칙에 따라 깔끔하고, 반응형이며, 인간 중심의 인터페이스를 구축할 수 있습니다. 주요 기능으로는 요청 시 필요한 참조 파일만 로드하는 프로그레시브 디스클로저 라우팅, UI 디자인에 직접 적용 가능한 보편적인 UX 법칙 (Jakob의 법칙, Fitts의 법칙 등), 적응 가능한 디자인 시스템 토큰 (색상, 타이포그래피, 간격), 그리고 코드베이스 적응, 모델/뷰 아키텍처, 키보드 우선 접근성 등을 보장하는 9가지의 엄격한 PySide6 엔지니어링 규칙이 포함되어 있습니다. 이 스킬은 Cursor, Claude Code, Codex와 같은 AI 코드 에이전트와 함께 사용하도록 설계되었으며, 개발자가 기존 프로젝트 컨텍스트에 자연스럽게 통합되면서도 일관된 고품질 UI를 신속하게 구축할 수 있도록 돕습니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/MohammedBoure/skills/tree/main/pyside6-ui

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

범용 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에 적용)

  1. Jakob의 법칙: 확립된 데스크톱 규칙 (Ctrl+S 저장, Ctrl+F 검색, Esc 취소/지우기, F5 새로고침, 표준 메뉴/툴바 배치)을 따르므로 사용자가 즉시 익숙함을 느낍니다.
  2. Fitts의 법칙: 기본 작업은 충분히 크게 (>= 36px 높이, 터치/고빈도 워크플로우의 경우 >= 42px) 유지하고 사용자의 주의가 이미 있는 곳 근처에 고정합니다. 반복 작업을 위해 마우스를 멀리 이동해야 하는 상황을 피하십시오.
  3. Hick의 법칙 및 프로그레시브 디스클로저: 한 번에 표시되는 선택 항목을 제한하십시오. 보조 옵션은 모든 컨트롤을 한 화면에 집어넣는 대신 서랍, 탭 또는 오버플로 메뉴로 그룹화하십시오.
  4. Miller의 법칙 및 게슈탈트 근접성: 관련 컨트롤을 깔끔한 시각적 그룹(CardFrame)으로 청크화하고 그룹 내에서는 8px, 그룹 간에는 16px–24px의 일관된 간격을 사용하여 사용자가 구조를 쉽게 스캔할 수 있도록 하십시오.
  5. Doherty 임계값 (< 400ms 인지 응답 시간): Qt 이벤트 루프를 절대 중단시키지 마십시오. I/O, 네트워크 및 무거운 계산은 메인 스레드에서 오프로드(QThreadPool / QRunnable)하고 즉각적인 로딩 또는 진행률 피드백을 표시하십시오.
  6. 오류 방지 및 안전한 복구: 제출 전에 인라인으로 검증하고, 불가능한 작업은 비활성화한 후 그 이유를 명확한 툴팁으로 설명하며, 파괴적이거나 되돌릴 수 없는 작업에 대해서만 명시적 확인을 요구하십시오.

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를 깔끔하게 지원합니다).
    • 타입 스케일: 페이지 제목 20px Bold, 섹션 제목 15px SemiBold, 본문/셀 13px Regular, 레이블/캡션 12px Medium, 히어로 메트릭 22px–26px Bold.
  • 의미론적 상태 토큰:
    • 성공: 텍스트 #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 엔지니어링 규칙

  1. 먼저 기존 코드베이스에 적응하십시오: 새 추상화를 도입하기 전에 기존 테마 상수, 기본 위젯 및 헬퍼를 재사용하십시오.
  2. 깔끔한 공간 그룹화: 무거운 중첩 QGroupBox 테두리 대신 QFrame 카드 (1px 가는 테두리, 미묘한 표면 대비) 또는 QSplitter 창을 사용하십시오.
  3. 테이블 및 트리 데이터를 위한 모델/뷰: QAbstractItemModel (QAbstractTableModel), QSortFilterProxyModel 및 QStyledItemDelegate와 함께 QTableView / QTreeView를 사용하십시오. QTableWidget 셀에 무거운 중첩 위젯을 채우지 마십시오.
  4. 인라인 스파게티 대신 의미론적 QSS: 원시 setStyleSheet(...) 문자열을 흩뿌리지 말고 setObjectName(...) 역할 (PrimaryButton, DangerButton, Card, PageTitle)과 동적 속성([invalid="true"]와 함께 unpolish()/polish())을 통해 스타일을 지정하십시오.
  5. 반응형 레이아웃 (고정 컨테이너 크기 없음): 윈도우, 카드 또는 테이블에 setFixedSize()를 절대 호출하지 마십시오. 레이아웃, 스트레치 팩터, QSizePolicy 및 QScrollArea에 의존하여 UI가 다양한 해상도, HiDPI 디스플레이 및 번역된 텍스트 길이에 걸쳐 깔끔하게 확장되도록 하십시오.
  6. 비활성화 상태 설명 및 인라인 검증: 모든 setEnabled(False) 호출에는 비활성화된 이유를 설명하는 setToolTip(...)이 반드시 포함되어야 합니다. 입력은 도우미 오류 레이블로 인라인 검증하십시오. QMessageBox로 타이핑을 절대 중단시키지 마십시오.
  7. 작업당 하나의 정식 위치: 동일한 작업을 상단 막대와 하단 바닥글에 절대 중복 배치하지 마십시오. 페이지 수준 CTA는 PageHeader의 오른쪽 상단에, 기본 폼/다이얼로그 CTA는 모달 바닥글의 오른쪽 하단에 배치하십시오.
  8. 키보드 우선 및 비블로킹 피드백: showEvent()에서 초기 포커스를 설정하고, setTabOrder()를 연결하고, Enter/Esc를 지원하며, 일상적인 확인에는 비블로킹 오버레이 토스트 또는 상태 표시줄을 사용하고 모달 다이얼로그는 파괴적 확인을 위해 남겨두십시오.
  9. 절제되고 내용에 맞는 상태 배지: 테이블 상태 알약을 넓은 균일 고정 너비로 늘리거나 모든 정상 행을 무거운 채도 배지로 채우지 마십시오. 알약 너비를 QFontMetrics.horizontalAdvance(text) + padding으로 동적으로 맞추고, 일상적인 정상 상태는 시각적으로 조용하게 유지(예: 미묘한 7px 상태 점 + 선명한 텍스트)하여 경고/오류가 즉시 눈에 띄게 하고, 사용자 정의 QStyledItemDelegate.paint() 재정의 내에서 행 선택과 하단 가는 구분선을 유지하십시오.

5. 사전 점검 품질 관문

PySide6 UI 구현을 마무리하기 전에 다음을 확인하십시오:

  • 모든 보기에 명확한 시각적 계층 구조(PageHeader 또는 구조화된 작업 공간 막대)가 있고 떠다니는 분리된 컨트롤이 없습니까?
  • 모든 대화형 컨트롤이 균일한 높이(>= 36px), 명확한 호버/포커스 상태 및 충분한 색상 대비를 공유합니까?
  • 숫자/테이블 열이 오른쪽 정렬되고 앱의 로케일에 따라 형식이 지정되었습니까?
  • 테이블 상태 배지가 텍스트에 맞게 크기가 조정되고, 정상 행에서 시각적으로 차분하며, 행 선택 및 구분선과 매끄럽게 정렬되었습니까?
  • 빈 상태, 일치 항목 없음 및 로딩 상태가 빈 공백 대신 전용 QStackedWidget 상태를 사용합니까?
  • 비활성화된 모든 컨트롤이 setToolTip()을 통해 스스로를 설명합니까?
  • 장기 실행 작업이 UI 스레드에서 오프로드되어 창이 절대 멈추지 않습니까?

관련 스킬