| name | qt-qss-styling |
| description | Author, refactor, review, or explain Qt style sheets for QWidget-based apps. Use when Codex is writing or editing `.qss` files, adding `setStyleSheet(...)` code, styling PyQt/PySide/Qt Widgets controls, porting a visual theme into QSS, or debugging selector/state/resource issues in Qt widget styling. Also use when the user asks in Chinese to write or modify "Qt样式", "QSS样式", "暗黑主题", "深色主题", "控件皮肤", "Qt界面美化", or "Qt控件主题". |
Qt QSS Styling
Use this skill for Qt Widgets styling work. Treat the bundled QtQss examples as reference material for theme direction and widget-state patterns, not as files to paste wholesale unless the user explicitly wants a full imported theme.
Quick Start
- Identify the target stack: Qt Widgets, PyQt5/PyQt6, PySide2/PySide6, or C++ Qt.
- Identify the styling scope:
- single widget or state fix
- one component family such as buttons, tabs, or scrollbars
- full application theme
- If the request implies a theme direction, read references/theme-catalog.md.
- If the request needs selector/state help, read references/widget-patterns.md.
- If the request is in Chinese or the user wants Chinese guidance, read references/zh-guide.md.
- If the request needs project integration code, read references/integration-examples.md.
- If the request needs a new palette-derived theme, render assets/templates/dark-tokenized-template.qss with scripts/render_qss_template.py.
- Edit the smallest relevant
.qss file or the code that loads the stylesheet.
Working Rules
- Prefer existing project conventions over the bundled examples when the repository already has a theme.
- Keep selectors scoped when possible. Avoid broad
QWidget rules unless the user wants an application-wide theme.
- Reuse a small palette of colors across normal, hover, pressed, selected, and disabled states.
- When a theme uses images, keep
url(...) paths consistent with the final runtime layout. The bundled MacOS.qss and QSS_IMG/ assets are the reference example.
- Preserve readability. If a visual effect needs too many gradients or border overrides, simplify before expanding coverage.
- When the user asks for a new theme, start by choosing one bundled theme family and adapt it instead of inventing dozens of unrelated rules.
Authoring Convention
- Write skill rules, headings, workflow steps, and machine-facing instructions in English.
- Write explanatory comments in
SKILL.md in Chinese.
- Write supplementary notes, caveats, and human-facing hints in
SKILL.md in Chinese.
- Keep code identifiers, file names, selectors, palette tokens, and command examples in their original technical language.
- Do not mix bilingual wording inside the same rule sentence unless the Chinese phrase is itself a user trigger or a literal example.
Theme Selection
Use these defaults unless the user specifies a visual direction:
- dark developer UI:
MaterialDark.qss or ElegantDark.qss
- pure black / OLED look:
AMOLED.qss
- Linux desktop / warm light theme:
Ubuntu.qss
- macOS-like controls with asset-backed arrows:
MacOS.qss
- accent-heavy or playful buttons:
NeonButtons.qss
- terminal / utility styling:
ConsoleStyle.qss
Read references/theme-catalog.md before adapting a bundled theme.
Authoring Flow
Small edits
- Find the exact selector and pseudo-state involved.
- Modify only the affected widget family.
- Add hover, pressed, selected, and disabled states only when the widget actually uses them.
New component styling
- Start from the base selector.
- Add interactive states in this order:
:hover, :pressed, :checked or :selected, :disabled.
- For compound widgets such as
QComboBox, QScrollBar, and QTabWidget, mirror the subcontrols used in the bundled examples rather than guessing names.
Full theme work
- Choose a base theme family from the bundled assets.
- Extract a palette first: background, surface, border, text, muted text, accent, accent-hover.
- Apply the palette consistently to
QMainWindow, dialogs, text inputs, buttons, menus, tabs, progress controls, and scrollbars.
- If the user wants a direct derivative of a bundled theme, copy the closest file and then rename/rework colors and spacing.
Bundled Resources
Use the samples selectively:
- Read one or two relevant
.qss files instead of loading every sample.
- Copy only the widget sections you need.
- Keep image-backed styles together with their referenced assets.
- Prefer the tokenized template plus render script when the user wants a fast custom theme from a small palette.
