用途
Qt UI Design 是一个面向 Qt/QML、Qt 项目、Web 以及嵌入式 MPU 或 MCU 目标的 UI 设计与审计技能。当任务涉及创建屏幕、布局、导航，或对界面进行 UX 审计时启用。
主要能力
上下文检查（设计前）
技能要求在设计前确认七项信息，并只询问对话或仓库中确实缺失的项目：
- 目标平台：桌面、浏览器、移动端，或特定硬件（MCU、Raspberry Pi 或其他嵌入式板卡）。若为特定板卡，询问是否存在该板卡的专用技能并加载。
- 屏幕形状：矩形（默认）、方形或圆形。
- 分辨率与 DPI：是否已知屏幕分辨率和 DPI（近似即可）。
- 设计系统：项目是否已使用设计系统或 Qt Quick Controls 样式。若有则遵循并复用其 token；若无则推荐一种 Qt Quick Controls 样式：Basic、Fusion、Imagine、Material、Universal、iOS 或 FluentWinUI3（iOS 与 FluentWinUI3 需要 Qt 6.7 或更高版本）。若项目遵循第三方设计语言（Material Design 3、Apple Human Interface Guidelines、Fluent 2），应将其 token 映射到对应的 Qt Quick Controls 样式，而非引入并行的 token 词汇表。
- 内容优先级：屏幕上最重要的信息（主要）、次要信息和第三级信息分别是什么。
- 观看距离：用户距屏幕多远（如手持约 30 cm、桌面约 60 cm、面板约 1.5 m、墙面约 3 m）。
- 语言区域与输入：主要语言区域/语言是什么；是否需要 RTL（阿拉伯语、希伯来语、波斯语、乌尔都语）支持；必须支持哪些输入方式（触摸、键盘、鼠标/指针、硬件按钮、语音）。
若目标是嵌入式或 MCU 设备，在做任何设计决策前需完整阅读关于嵌入式的章节，它会覆盖若干桌面端默认设置。
对已有设计的微小改动（例如“把确定按钮移到右边”“改这个标签”“把它变红”）不触发检查清单，只需静默应用设计原则，并在相关处验证对比度与点击目标。
设计原则（适用于所有目标）
内容包括：内容与布局（黄金比例与三分法、渐进式披露、倒金字塔、模块化、奥卡姆剃刀、性能负载、Five Hat Racks 组织法）；感知与交互（雅各布定律、可供性、希克定律、米勒定律、识别优于回忆、邻近性与相似性、统一连接性、von Restorff 效应、峰终定律、Doherty 阈值、美学-可用性效应、寻路）；阅读模式（F 型、Z 型、层叠式、点状）；按钮与 CTA（限制每组的 CTA 数量，用邻近性和相似性区分主次控件）；错误预防（引导正确使用的可供性、尽可能支持撤销、破坏性操作前确认、危险状态提示）。
响应式设计（桌面/Web）
优先针对主要目标分辨率设计；最小布局宽度 240 px，低于此宽度需堆叠或折叠；空间紧张时将次要功能隐藏在菜单或下拉菜单中。
动效与动画
进入动画使用减速缓动，退出动画使用加速缓动；直接操作反馈需在 100 ms 内响应；超过 1 秒的操作须显示进度指示器，超过 10 秒须显示预计时间。时长预算：小元素 100–150 ms，中等元素 200–300 ms，全屏过渡 300–400 ms，任何 UI 动画不得超过 500 ms。同时动画限制在一到两个元素；在 QML/CSS 中仅对 transform 和 opacity 做动画；尊重用户的减少动效偏好（Web 用 prefers-reduced-motion，Qt 6.x 无内置等价物，需暴露项目级设置）；移动元素的方向需与其目的地一致。
排版比例（桌面/Web）
使用模块化比例派生所有字号：先选基准（桌面约 60 cm 观看距离下 16 px 是可靠起点），再选比例（8:9 大二度 1.125；5:6 小三度 1.200；4:5 大三度 1.250；3:4 纯四度 1.333；1:1.618 黄金分割 1.618），然后将比例步阶映射到排版角色。给出以基准 16 px、纯四度 1.333 为例的完整示例表（display 38 px、H1 28 px、H2 21 px、body 16 px、caption 12 px）。规则包括：正文最小 16 px、正文行高 1.4–1.6 倍、标题 1.1–1.2 倍、每行 45–75 字符、字重搭配（正文 400，标题 500，正文内不用 700）、优先系统字体、在大号系统字体下验证、Qt 中优先使用 font.pointSize 而非 font.pixelSize。
QML 实现：将比例定义为单例（如 TypeScale.qml），通过角色名引用而非硬编码值；提供 TypeScale.qml 示例代码及 qmldir 与 CMake 的 qt_add_qml_module 注册示例。
多输入与键盘导航（桌面/Web）
要求完整键盘可达性，Tab 顺序遵循视觉阅读顺序；始终渲染可见焦点指示器；无键盘陷阱（可用 Escape 或键盘可访问的关闭控件退出模态）；每个交互元素都须可通过指针、键盘以及 Qt 无障碍 API 暴露时通过屏幕阅读器访问；悬停状态是增强而非主要披露机制；触摸与指针共存。
语义化色彩
使用基于角色的 token 而非原始十六进制值；token 名称应描述角色（interactive、surface、on-surface、error、outline）而非外观；若项目使用 Fluent 2 或 Apple HIG，映射到对应角色名。QML 命名注意事项：以 on + 大写字母开头的属性名（onSurface、onPrimary）会与 QML 的信号处理器语法冲突，导致加载失败（“Cannot assign a value to a signal”），需重命名（如 textOnSurface、surfaceForeground）。区分交互色与装饰色；颜色不可作为状态的唯一载体（成功、警告、错误必须同时搭配图标或文本标签）；从一开始就设计明暗两种主题；注意文化差异的色彩含义。
本地化与 RTL 布局
日期、时间和数字格式须适配语言区域，不可硬编码 DD/MM/YYYY 之类的格式字符串，应使用 Qt 的 QLocale 或平台区域 API。RTL（阿拉伯语、希伯来语、波斯语、乌尔都语）整体布局水平镜像，启用 LayoutMirroring.enabled 与 LayoutMirroring.childrenInherit: true，但仍需显式处理 Text.horizontalAlignment 默认值、Image 内容（方向性图标使用 mirror: true）、自定义 Canvas 绘制和手动 x 位置。翻译字符串通常比英文源长 30–40%，避免固定宽度容器。避免文化特定图标，避免将文本嵌入图片或图标。
无障碍（WCAG 2.2）
交付前对照检查：可感知（所有信息有非视觉等价物，文本对比度 ≥ 4.5:1，大文本和 UI 组件 ≥ 3:1）；可操作（完整键盘导航，无焦点陷阱，所有交互目标无需指针即可到达）；可理解（标签、说明和错误信息使用平实语言）；健壮（标记和结构可配合屏幕阅读器与辅助工具）。
使用方式
该技能以智能体技能（agent skill）形式提供，通过 skills.sh 页面分发，来源为 theqtcompanyrnd/agent-skills。技能在相关任务中被触发后，按照上述检查清单与设计原则执行；对已有设计的微小改动不触发完整清单。