ユニバーサル 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に適用)
- ヤコブの法則: 確立されたデスクトップの慣習(
Ctrl+S保存、Ctrl+F検索、Escキャンセル/クリア、F5更新、標準メニュー/ツールバー配置)に合わせることで、ユーザーは即座に操作に慣れることができます。 - フィッツの法則: プライマリアクションは十分な大きさ(
>= 36px高さ、タッチ/高頻度操作では>= 42px)に保ち、ユーザーの注意がすでにある場所の近くに固定します。繰り返しの操作でマウスを長距離移動させることを避けます。 - ヒックの法則とプログレッシブディスクロージャー: 一度に表示される選択肢を制限します。セカンダリオプションは、すべてのコントロールを1つの画面に詰め込む代わりに、ドロワー、タブ、またはオーバーフローメニューにグループ化します。
- ミラーの法則とゲシュタルト近接性: 関連するコントロールを、一貫した間隔(グループ内は
8px、グループ間は16px–24px)でクリーンなビジュアルグループ(CardFrame)にまとめ、ユーザーが構造を簡単にスキャンできるようにします。 - ドハティのしきい値(
< 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をクリーンにサポート)。 - タイプスケール: ページタイトル
20pxボールド、セクションタイトル15pxセミボールド、ボディ/セル13pxレギュラー、ラベル/キャプション12pxミディアム、ヒーローメトリック22px–26pxボールド。
- プライマリテキスト:
- セマンティックステータストークン:
- 成功: テキスト
#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ペインを使用します。 - テーブルおよびツリーデータにはモデル/ビュー: 重いネストされたウィジェットを
QTableWidgetのセルに詰め込むのを避け、QAbstractItemModel(QAbstractTableModel)、QSortFilterProxyModel、およびQStyledItemDelegateとともにQTableView/QTreeViewを使用します。 - インラインのスパゲッティコードではなくセマンティックQSS: raw な
setStyleSheet(...)文字列をばらまくのではなく、setObjectName(...)ロール(PrimaryButton、DangerButton、Card、PageTitle)および動的プロパティ([invalid="true"]とunpolish()/polish()の組み合わせ)を介してスタイルを適用します。 - レスポンシブレイアウト(固定コンテナサイズは禁止): ウィンドウ、カード、テーブルに対して
setFixedSize()を決して呼び出さないでください。レイアウト、ストレッチファクター、QSizePolicy、およびQScrollAreaに依存して、UI が解像度、HiDPI ディスプレイ、および翻訳されたテキストの長さにわたってクリーンにスケールするようにします。 - 無効状態の説明とインラインバリデーション: すべての
setEnabled(False)呼び出しには、なぜ無効になっているのかを説明するsetToolTip(...)が必須です。ヘルパーエラーレーベルを使用してインラインで入力を検証します。QMessageBoxで入力を中断しないでください。 - アクションごとに1つの正規の場所: 同じアクションをトップバーとボトムフッターの両方に重複して配置しないでください。ページのプライマリ CTA は
PageHeaderの右上に、フォーム/ダイアログのプライマリ CTA はモーダルフッターの右下に配置します。 - キーボードファーストと非ブロッキングフィードバック:
showEvent()で初期フォーカスを設定し、setTabOrder()を配線し、Enter/Escをサポートし、ルーチンの確認には非ブロッキングのオーバーレイトーストまたはステータスバーを使用します。モーダルダイアログは破壊的な確認のために予約します。 - 控えめでコンテンツにフィットしたステータスバッジ: テーブルのステータスピルを広い均一の固定幅に引き伸ばしたり、すべての健全な行を重く彩度の高いバッジで埋めたりしないでください。ピルの幅は
QFontMetrics.horizontalAdvance(text) + paddingに動的にフィットさせ、ルーチンの健全な状態は視覚的に控えめに(例:微妙な7pxステータスドット+鮮明なテキスト)保ち、警告/エラーが即座に目立つようにし、カスタムQStyledItemDelegate.paint()オーバーライド内で行選択と下部ヘアライン区切りを維持します。
5. 出荷前品質ゲート
PySide6 UI実装を最終決定する前に、以下を確認します。
- すべてのビューに明確な視覚的階層(
PageHeaderまたは構造化されたワークスペースバー)があり、孤立したフローティングコントロールがないか? - すべてのインタラクティブコントロールが均一な高さ(
>= 36px)、明確なホバー/フォーカス状態、および十分な色のコントラストを備えているか? - 数値/表形式の列は右揃えで、アプリのロケールに従ってフォーマットされているか?
- テーブルのステータスバッジはテキストに合わせてサイズ設定され、健全な行では視覚的に落ち着いており、行選択と区切り線にシームレスに揃っているか?
- 空、ゼロ一致、およびローディング状態は、空白の代わりに専用の
QStackedWidget状態を使用しているか? - 無効化されたすべてのコントロールは
setToolTip()でそれ自体を説明しているか? - 長時間実行されるタスクはUIスレッドからオフロードされ、ウィンドウがフリーズしないようになっているか?