PySide6 の見た目調整で毎回つまずいてしまう初心者向けに、テーマやスタイル済みウィジェットをまとめた小さな UI キットを自作したので紹介します。スタイルを整える手間を減らし、すぐに統一感のある UI を作れるようにすることを目的にしています。

作成したUIのイメージ

作った背景

PySide6 は便利だけど、デザイン周りでつまずきやすいポイントが多いです。

QSS が難しい
色や余白を毎回設定するのが面倒
入力欄のバリデーションが地味に大変
ライト／ダークテーマを切り替えると崩れやすい

「初心者でも統一感のある UI をすぐ作れる仕組みがほしい」と思い、自分用に作り始めたのが PySide6StyleKit です。

PySide6StyleKit でできること

統一テーマ（ライト／ダーク）
StyledLabel / StyledLineEdit / StyledButton などのデザイン済みウィジェット
int / float / range のバリデーション
エラー時の赤枠・メッセージ表示
QSS なしで UI が整う

初心者でも「とりあえず見た目が整う」状態を目指しています。

インストール（最も簡単な方法）

PySide6StyleKit は PyPI に公開しているので、次の 1 行でインストールできます。

pip install pyside6stylekit

これだけでテーマやスタイル済みウィジェットがすぐに使えるようになります。

GitHub から ZIP を使いたい場合（任意）

PyPI ではなく GitHub のソースコードを直接使いたい場合は、以下から ZIP をダウンロードできます。

緑の Code ボタンをクリック
Download ZIP を選択
解凍して任意のフォルダに展開

ただし、通常の利用では pip install を推奨します。

デモサンプルの実行方法（ZIP / Git 共通）

リポジトリのルートフォルダで次を実行します。

python -m examples.demo

-m を使うことで examples をパッケージとして扱い、環境に依存せず確実に実行できます。

これは何をしているのか？

python -m examples.demo は

examples をパッケージとして扱い
demo.py をモジュールとして実行する

という Python 標準の実行方法です。

この方法なら ZIP ユーザーでも確実に動作し、
VS Code・PyCharm・ターミナルなど環境に依存しません。

StyleKit デモサンプルの解説

ここからはリポジトリの example フォルダに入っている demo.py について解説します。

このサンプルは PySide6StyleKit の主要コンポーネントをまとめて確認できるデモウィンドウで、テーマ設定、スタイル付きラベル、入力制限付きテキストボックス、バリデーション処理などを一度に試せる構成になっています。

実行すると以下のUIが起動します。

1. テーマ設定とタイトル表示

theme = Theme(
    primary="blue",
    mode="light",
    size="mid"
)

title = StyledLabel(
    "StyleKit デモ",
    Theme(primary="blue", mode="dark", size="large"),
    bold=True
)

Theme により 色・明暗・サイズを統一できます
タイトルだけ別テーマ（ダーク＋大きめ）を使い、強調表示しています
各設定（small, mid, large）のサイズを変更したい場合は ./pyside6stylekit/presets.py を編集してください

2. StyledLineEdit の入力モード

input_free = StyledLineEdit("自由入力", theme, mode="free")
input_numeric = StyledLineEdit("数値のみ", theme, mode="numeric")
input_alnum = StyledLineEdit("英数字のみ", theme, mode="alnum")
input_filename = StyledLineEdit("ファイル名OK", theme, mode="filename")
input_numeric_range = StyledLineEdit("入力制限（0〜120）", theme,
                           mode="numeric_range", min_val=0, max_val=120)

StyleKit の StyledLineEdit は、モードによって入力制限が自動で適用されます。

free：制限なし
numeric：数字のみ
alnum：英数字のみ
filename：ファイル名として妥当な文字のみ
numeric_range：数値範囲（min_val〜max_val）を指定可能

3. ボタンとバリデーション処理

button = StyledButton("送信", theme)
button.clicked.connect(lambda: self.validate(input_numeric_range))

StyledButton はテーマに合わせて色・ホバー・クリック時のスタイルが自動調整されるため、QSS を書かなくても統一感のあるボタンが使えます。

バリデーションの中身

def validate(self, widget: StyledLineEdit):
    if widget.is_valid():
        widget.show_error("")
        print("OK:", widget.value())
    else:
        widget.show_error("範囲外の値です")
        print("NG")

is_valid() が 入力モードに応じたチェックを自動で実行
OK → エラー非表示、値を取得
NG → エラーメッセージ表示

4. レイアウト構成

layout = QVBoxLayout()
layout.addWidget(title)
layout.addSpacing(10)

layout.addWidget(input_free)
layout.addWidget(input_numeric)
layout.addWidget(input_alnum)
layout.addWidget(input_filename)
layout.addWidget(input_numeric_range)

layout.addSpacing(10)
layout.addWidget(button)

縦に並べるだけのシンプルな構造で、StyleKit のコンポーネントが自然に並びます。

5. 実行部分

if __name__ == "__main__":
    app = QApplication(sys.argv)
    w = SampleWindow()
    w.resize(420, 380)
    w.show()
    sys.exit(app.exec())

標準的な PySide6 アプリの起動コードです。

まとめ

PySide6StyleKit は、PySide6 の見た目づくりで毎回つまずきがちな部分をまとめて扱えるようにした、自作の小さな UI キットです。テーマ設定、スタイル済みウィジェット、入力制限、バリデーションなど、アプリを作るうえで「毎回書くのが面倒だったところ」をひとまとめにしたことで、試作や小さなツールづくりがかなり楽になります。

PyPI から pip install で簡単に導入できるので、PySide6 の UI を手軽に整えたい人にちょうどいい入り口になると思います。

今後産業用途で使えるボタン（モメンタリ/オルタネイト）や、その他のpyside6のwidgetも順次追加していく予定です。使い方についてはGitHubリポジトリ内の README をご覧ください。

リポジトリ

GitHub: https://github.com/noritama-lab/pyside6-stylekit