Communitygithub.com

pyside6-ui

PySide6 / Qt for Python によるデスクトップアプリケーション向けユニバーサルUI/UXアーキテクチャ&デザインシステムスキル。PySide6のウィンドウ、ナビゲーションシェル、QSSテーマ、ダッシュボード、データテーブル、検索/フィルターバー、CRUDフォーム、モーダルダイアログ、非同期応答性、RTL/i18n、キーボード操作の設計、構築、リファクタリング、スタイリング、レビューの際は常に使用してください。

pyside6-ui とは?

このスキルは、**PySide6(Qt for Python)** を使用したデスクトップアプリケーションのUI/UX設計と実装において、統一性と高品質を保証するための総合的なガイドです。あらゆるアプリケーションドメインに対応し、既存のプロジェクトテーマやウィジェットを自然に拡張する形で統合します。スキルは、テーマ設定(QSSスタイルシート、ライト/ダークモード)、ナビゲーションシェル(メインウィンドウ、サイドバー、タブ)、データテーブルとフィルター、フォームとダイアログ、アクセシビリティとi18n/RTL、非同期処理(QThreadPool)などのトピックごとに分割された参照ファイルをオンデマンドで読み込む進行性開示ルーティングを採用しています。さらに、Jakobの法則やFittsの法則などのUX原則をデスクトップUIに適用し、キーボードファースト、エラー防止、モデル/ビューアーキテクチャ、レスポンシブレイアウト、状態バッジの適切なサイジングなど、PySide6固有のエンジニアリングルールを定義しています。Claude Code、Cursor、CodexなどのAIエージェントがPySide6プロジェクトで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. ヤコブの法則: 確立されたデスクトップの慣習(Ctrl+S 保存、Ctrl+F 検索、Esc キャンセル/クリア、F5 更新、標準メニュー/ツールバー配置)に合わせることで、ユーザーは即座に操作に慣れることができます。
  2. フィッツの法則: プライマリアクションは十分な大きさ(>= 36px 高さ、タッチ/高頻度操作では >= 42px)に保ち、ユーザーの注意がすでにある場所の近くに固定します。繰り返しの操作でマウスを長距離移動させることを避けます。
  3. ヒックの法則とプログレッシブディスクロージャー: 一度に表示される選択肢を制限します。セカンダリオプションは、すべてのコントロールを1つの画面に詰め込む代わりに、ドロワー、タブ、またはオーバーフローメニューにグループ化します。
  4. ミラーの法則とゲシュタルト近接性: 関連するコントロールを、一貫した間隔(グループ内は 8px、グループ間は 16px–24px)でクリーンなビジュアルグループ(CardFrame)にまとめ、ユーザーが構造を簡単にスキャンできるようにします。
  5. ドハティのしきい値(< 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 ボールド、セクションタイトル 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エンジニアリングルール

  1. 既存のコードベースに適応することを最優先: 新しい抽象化を導入する前に、既存のテーマ定数、ベースウィジェット、およびヘルパーを再利用します。
  2. クリーンな空間グルーピング: 重いネストされた QGroupBox 境界線の代わりに、QFrame カード(1px ヘアラインボーダー、微妙なサーフェスコントラスト)または QSplitter ペインを使用します。
  3. テーブルおよびツリーデータにはモデル/ビュー: 重いネストされたウィジェットを QTableWidget のセルに詰め込むのを避け、QAbstractItemModel(QAbstractTableModel)、QSortFilterProxyModel、および QStyledItemDelegate とともに QTableView / QTreeView を使用します。
  4. インラインのスパゲッティコードではなくセマンティックQSS: raw な setStyleSheet(...) 文字列をばらまくのではなく、setObjectName(...) ロール(PrimaryButton、DangerButton、Card、PageTitle)および動的プロパティ([invalid="true"] と unpolish()/polish() の組み合わせ)を介してスタイルを適用します。
  5. レスポンシブレイアウト(固定コンテナサイズは禁止): ウィンドウ、カード、テーブルに対して setFixedSize() を決して呼び出さないでください。レイアウト、ストレッチファクター、QSizePolicy、および QScrollArea に依存して、UI が解像度、HiDPI ディスプレイ、および翻訳されたテキストの長さにわたってクリーンにスケールするようにします。
  6. 無効状態の説明とインラインバリデーション: すべての setEnabled(False) 呼び出しには、なぜ無効になっているのかを説明する setToolTip(...) が必須です。ヘルパーエラーレーベルを使用してインラインで入力を検証します。QMessageBox で入力を中断しないでください。
  7. アクションごとに1つの正規の場所: 同じアクションをトップバーとボトムフッターの両方に重複して配置しないでください。ページのプライマリ CTA は PageHeader の右上に、フォーム/ダイアログのプライマリ CTA はモーダルフッターの右下に配置します。
  8. キーボードファーストと非ブロッキングフィードバック: showEvent() で初期フォーカスを設定し、setTabOrder() を配線し、Enter/Esc をサポートし、ルーチンの確認には非ブロッキングのオーバーレイトーストまたはステータスバーを使用します。モーダルダイアログは破壊的な確認のために予約します。
  9. 控えめでコンテンツにフィットしたステータスバッジ: テーブルのステータスピルを広い均一の固定幅に引き伸ばしたり、すべての健全な行を重く彩度の高いバッジで埋めたりしないでください。ピルの幅は QFontMetrics.horizontalAdvance(text) + padding に動的にフィットさせ、ルーチンの健全な状態は視覚的に控えめに(例:微妙な 7px ステータスドット+鮮明なテキスト)保ち、警告/エラーが即座に目立つようにし、カスタム QStyledItemDelegate.paint() オーバーライド内で行選択と下部ヘアライン区切りを維持します。

5. 出荷前品質ゲート

PySide6 UI実装を最終決定する前に、以下を確認します。

  • すべてのビューに明確な視覚的階層(PageHeader または構造化されたワークスペースバー)があり、孤立したフローティングコントロールがないか?
  • すべてのインタラクティブコントロールが均一な高さ(>= 36px)、明確なホバー/フォーカス状態、および十分な色のコントラストを備えているか?
  • 数値/表形式の列は右揃えで、アプリのロケールに従ってフォーマットされているか?
  • テーブルのステータスバッジはテキストに合わせてサイズ設定され、健全な行では視覚的に落ち着いており、行選択と区切り線にシームレスに揃っているか?
  • 空、ゼロ一致、およびローディング状態は、空白の代わりに専用の QStackedWidget 状態を使用しているか?
  • 無効化されたすべてのコントロールは setToolTip() でそれ自体を説明しているか?
  • 長時間実行されるタスクはUIスレッドからオフロードされ、ウィンドウがフリーズしないようになっているか?

関連スキル