Communitygithub.com

pyside6-ui (通用 PySide6 UI/UX 架构技能)

适用于任何桌面应用程序的通用PySide6 / Qt for Python UI/UX架构与设计系统技能。在设计、构建、重构、样式化或审查PySide6窗口、导航外壳、QSS主题、仪表板、数据表格、搜索/过滤栏、CRUD表单、模态对话框、异步响应、RTL国际化或键盘工作流时,始终使用此技能。

UX 架构技能) 是什么?

这是一个为任何桌面应用程序域提供通用PySide6 UI/UX架构的技能。它强制要求渐进式文档加载:先检查目标项目现有主题、控件和约定,然后仅读取当前任务所需的特定参考文件(如`design-system-and-qss.md`、`navigation-and-shell.md`、`data-tables-and-filters.md`、`forms-dialogs-and-feedback.md`等)。该技能植根于一系列通用UX定律(如Jakob定律、Fitts定律、Hick定律),并提供了默认的设计系统令牌(包括调色板、排版、间距和语义状态标记),但在项目已有自己的令牌时会主动适应项目。关键工程规则包括:始终优先适配现有代码库、使用Model/View处理表格和树形数据、使用语义QSS而非内联样式、布局响应式(禁止固定容器大小)、解释禁用状态、确保键盘可操作,以及使用非阻塞反馈(如Toast和状态栏)而非模态对话框。该技能支持Claude Code、Cursor、Codex等所有主要AI代理平台,其文档以SKILL.md形式提供,指导AI代理在设计、构建或审查PySide6桌面应用界面时遵循一致、可访问且性能良好的架构。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/MohammedBoure/skills/tree/main/pyside6-ui

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

通用 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)、表单、详情抽屉、验证或 Toast/进度反馈 → 读取 ./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 粗体、章节标题 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. 清晰的空间分组:使用 QFrame 卡片(1px 细线边框、微妙的表面对比)或 QSplitter 窗格,而不是厚重的嵌套 QGroupBox 边框。
  3. 表格与树数据的 Model/View:使用 QTableView / QTreeView 配合 QAbstractItemModel(QAbstractTableModel)、QSortFilterProxyModel 和 QStyledItemDelegate。避免用沉重的嵌套控件填充 QTableWidget 单元格。
  4. 语义 QSS 优于内联意大利面条:通过 setObjectName(...) 角色(PrimaryButton、DangerButton、Card、PageTitle)和动态属性([invalid="true"] 配合 unpolish()/polish())进行样式设置,而不是散布原始的 setStyleSheet(...) 字符串。
  5. 响应式布局(零固定容器尺寸):永远不要在窗口、卡片或表格上调用 setFixedSize()。依赖布局、拉伸因子、QSizePolicy 和 QScrollArea,使 UI 在分辨率、HiDPI 显示和翻译文本长度下都能干净缩放。
  6. 解释禁用状态并内联验证:每个 setEnabled(False) 调用必须包含 setToolTip(...) 解释为什么禁用。使用辅助错误标签进行内联验证输入——永远不要用 QMessageBox 打断打字。
  7. 每个操作一个规范位置:永远不要将相同操作同时放在顶部栏和底部页脚。将主要页面 CTA 放在 PageHeader 的右上角,主要表单/对话框 CTA 放在模态框页脚的右下角。
  8. 键盘优先与非阻塞反馈:在 showEvent() 中设置初始焦点、绑定 setTabOrder()、支持 Enter/Esc,并使用非阻塞覆盖式 Toast 或状态栏进行常规确认——保留模态对话框用于破坏性确认。
  9. 克制、内容适配的状态徽章:永远不要将表格状态药丸拉伸到宽的均匀固定宽度,也不要让每个健康行都充斥着沉重的饱和徽章。动态适应药丸宽度 QFontMetrics.horizontalAdvance(text) + padding,保持常规健康状态视觉安静(例如,微妙的 7px 状态点 + 清晰文本),使警告/错误立即突出,并在自定义 QStyledItemDelegate.paint() 覆盖中保留行选择和底部细线分隔符。

5. 预发布质量门控

在任何 PySide6 UI 实现最终确定之前,请验证:

  • 每个视图是否都有清晰的视觉层级(PageHeader 或结构化工作区栏),没有零散的浮动控件?
  • 所有交互控件是否共享统一的高度(>= 36px)、清晰的悬停/焦点状态以及足够的色彩对比度?
  • 数字/表格列是否右对齐并根据应用的语言环境格式化?
  • 表格状态徽章是否根据其文本调整大小,在健康行上视觉平静,并与行选择和分隔线无缝对齐?
  • 空、零匹配和加载状态是否使用专用的 QStackedWidget 状态而不是空白区域?
  • 每个禁用的控件是否通过 setToolTip() 自我解释?
  • 长时间运行的任务是否从 UI 线程卸出,以便窗口永不冻结?

相关技能