Back to Details

qt-ui-design

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Qt UI Design

Qt UI 设计

Before producing UI output, confirm you know: target platform, screen geometry, design system, content priority, viewing distance, locale, and input methods. Run the seven items below as a check against the conversation and the project state; ask only the items that are genuinely missing. When the user cannot answer an item, choose a sensible Qt default and name it in your response so the user can correct it.
Small edits to an existing design — for example "move the OK button to the right", "change this label", "make this red" — do not trigger the checklist. Apply section 1 silently and verify section 2 (contrast, hit-target) where relevant.
在产出UI成果前，请确认你已了解：目标平台、屏幕几何参数、设计系统、内容优先级、观看距离、区域设置以及输入方式。对照对话内容和项目状态，逐一检查以下7项内容；仅询问确实缺失的信息。若用户无法回答某一项，请选择合理的Qt默认值并在回复中说明，以便用户更正。
对现有设计的小幅修改——例如“将确认按钮移至右侧”、“修改此标签”、“将此设为红色”——无需触发检查清单。直接应用第1部分内容，并在相关情况下验证第2部分（对比度、点击目标）。

0. Context check (before designing)

0. 设计前的上下文检查

Use the seven items below to decide what is already known and what to ask. If the conversation or repository has already answered an item, do not re-ask.
  1. Target platform — Desktop, web browser, mobile, or specific hardware (MCU, Raspberry Pi, other embedded board)?
    • If a specific board: ask whether a board-specific skill exists for it and load it if so.
  2. Screen shape — Rectangle (default), Square, or Circle?
  3. Resolution and DPI — Do you know the screen resolution and DPI? (Approximate is fine.)
  4. Design system — Check whether the project already uses a design system or Qt Quick Controls style. If so, follow it and reuse its tokens. If not, recommend a Qt Quick Controls style: Basic, Fusion, Imagine, Material, Universal, iOS, or FluentWinUI3 (the iOS and FluentWinUI3 styles require Qt 6.7 or later). Where the project follows a third-party design language (Material Design 3, Apple Human Interface Guidelines, Fluent 2), map its tokens to the corresponding Qt Quick Controls style rather than introducing a parallel token vocabulary.
  5. Content priority — What information is most important (primary), secondary, and tertiary on this screen?
  6. Viewing distance — How far will users be from the screen? (e.g. handheld ~30 cm, desk ~60 cm, panel ~1.5 m, wall ~3 m)
  7. Locale and input — What is the primary locale/language? Is RTL (Arabic, Hebrew, Farsi, Urdu) support required? What input methods must be supported (touch, keyboard, mouse/pointer, hardware buttons, voice)? If the target is an embedded or MCU device, also read section 4 in full before any design decisions — it overrides several desktop defaults.
If the user is requesting an audit of an existing design, skip to section 5 (Audit).
使用以下7项内容判断已知信息和需询问的信息。若对话或代码库已回答某一项，请勿重复询问。
  1. 目标平台——桌面端、网页浏览器、移动端，还是特定硬件（MCU、树莓派、其他嵌入式开发板）？
    • 若为特定开发板：询问是否存在针对该开发板的专属技能，若有则加载该技能。
  2. 屏幕形状——矩形（默认）、正方形还是圆形？
  3. 分辨率与DPI——你是否了解屏幕分辨率和DPI？（近似值即可。）
  4. 设计系统——检查项目是否已使用设计系统或Qt Quick Controls样式。若已使用，请遵循该系统并复用其令牌。若未使用，推荐一款Qt Quick Controls样式：Basic、Fusion、Imagine、Material、Universal、iOS或FluentWinUI3（iOS和FluentWinUI3样式要求Qt 6.7或更高版本）。若项目遵循第三方设计语言（Material Design 3、Apple人机界面指南、Fluent 2），请将其令牌映射到对应的Qt Quick Controls样式，而非引入并行的令牌词汇。
  5. 内容优先级——此界面上哪些信息是最重要的（一级）、次要的（二级）和三级的？
  6. 观看距离——用户与屏幕的距离是多少？（例如：手持设备约30厘米、桌面设备约60厘米、面板约1.5米、墙面显示屏约3米）
  7. 区域设置与输入方式——主要区域设置/语言是什么？是否需要支持RTL（阿拉伯语、希伯来语、波斯语、乌尔都语）？必须支持哪些输入方式（触摸、键盘、鼠标/指针、硬件按钮、语音）？ 若目标为嵌入式或MCU设备，在做出任何设计决策前，请完整阅读第4部分——该部分会覆盖多项桌面端默认设置。
若用户要求审核现有设计，请直接跳至第5部分（审核）。

1. Design principles to apply (all targets)

1. 需遵循的设计原则（所有目标平台）

Apply these while designing. Do not ask about each one — use them to inform decisions silently.
Content and layout:
  • Golden Ratio + Rule of Thirds: Place primary elements at visual intersections.
  • Progressive Disclosure: Show only what is needed at the current step.
  • Inverted Pyramid: Critical information first, elaboration after.
  • Modularity: Divide complex flows into smaller, self-contained screens.
  • Ockham's Razor: When two designs are equivalent, choose the simpler one.
  • Performance Load: Fewer steps = higher task completion.
  • Five Hat Racks: Organise by category, time, location, alphabet, or continuum. Perception and interaction:
  • Jakob's Law: Match patterns users already know.
  • Affordance: Controls should look like what they do.
  • Hick's Law: More choices = slower decisions. Limit options per screen.
  • Miller's Law: Working memory holds ~7 items. Chunk accordingly.
  • Recognition Over Recall: Show options; don't require memorisation.
  • Proximity + Similarity: Group related elements visually.
  • Uniform Connectedness: Shared border or color = same group.
  • von Restorff Effect: One visually distinct element draws attention — use sparingly.
  • Peak-End Rule: Users remember the peak moment and the ending. Design completion states (e.g. installer finish screens) to feel rewarding, not abrupt.
  • Doherty Threshold: System feedback within 400 ms, or show a progress indicator.
  • Aesthetic-Usability Effect: Polished design is perceived as more usable.
  • Wayfinding: Users must always know where they are, where they've been, where they can go. Reading patterns (use to guide information placement):
  • F-shaped: Text-heavy content — top bar, shorter secondary bar, left-edge scan.
  • Z-shaped: Sparse content — top-left → top-right → diagonal → bottom-right.
  • Layer-cake: Users scan headings and skip body text.
  • Spotted: Users jump to landmarks — links, capitals, list items. Buttons and CTAs:
  • Limit CTA buttons per group. OK + Cancel = one group; additional actions must be visually secondary.
  • Use Proximity and Similarity to distinguish primary, secondary, and tertiary controls. Error prevention:
  • Design affordances that guide correct use.
  • Allow undo wherever technically possible.
  • Confirm before destructive or irreversible actions.
  • Add alarms or prompts for danger states. Responsiveness (desktop/web only — embedded: see section 4):
  • Design to your primary target's resolution first — desktop with chrome, embedded fixed-resolution, or a window-resize range typical for the application. Stack, collapse, or hide secondary content for narrower widths.
  • Minimum layout width: 240 px. Stack or collapse elements below this.
  • Hide secondary features behind menus or dropdowns when space is tight.
设计时需应用这些原则。无需逐一询问，直接将其作为决策依据即可。
内容与布局：
  • 黄金比例+三分法： 将核心元素放置在视觉交叉点。
  • 渐进式展示： 仅展示当前步骤所需的内容。
  • 倒金字塔原则： 关键信息优先，补充信息后置。
  • 模块化： 将复杂流程拆分为更小的独立界面。
  • 奥卡姆剃刀原则： 若两种设计效果相当，选择更简洁的一种。
  • 性能负载： 步骤越少，任务完成率越高。
  • 五种分类方式： 按类别、时间、位置、字母顺序或连续体组织内容。 感知与交互：
  • 雅各布定律： 匹配用户已熟悉的交互模式。
  • 功能可见性： 控件外观应与其功能相符。
  • 希克定律： 选项越多，决策速度越慢。限制每个界面的选项数量。
  • 米勒定律： 工作记忆约可容纳7项内容。据此分组信息。
  • 识别优于回忆： 展示选项，无需用户记忆。
  • 接近性+相似性： 将相关元素在视觉上分组。
  • 统一连接性： 共享边框或颜色的元素属于同一组。
  • 冯·雷斯托夫效应： 视觉上独特的元素会吸引注意力——谨慎使用。
  • 峰终定律： 用户会记住体验的峰值时刻和结尾。设计完成状态（如安装程序完成界面）时，应让用户感到愉悦，而非突兀。
  • 多尔蒂阈值： 系统反馈需在400毫秒内给出，否则显示进度指示器。
  • 美学可用性效应： 精致的设计会被认为更易用。
  • 寻路性： 用户必须始终清楚自己所在位置、去过哪里以及可以前往哪里。 阅读模式（用于指导信息布局）：
  • F型： 文本密集型内容——顶部栏、较短的二级栏、左边缘扫描。
  • Z型： 内容稀疏型——左上→右上→对角线→右下。
  • 分层蛋糕型： 用户扫描标题，跳过正文。
  • 斑点型： 用户跳转到标志性内容——链接、大写字母、列表项。 按钮与CTA：
  • 每组限制CTA按钮数量。确认+取消为一组；额外操作必须在视觉上作为次要元素。
  • 使用接近性和相似性区分一级、二级和三级控件。 错误预防：
  • 设计引导正确操作的功能可见性。
  • 只要技术可行，允许撤销操作。
  • 在执行破坏性或不可逆操作前进行确认。
  • 为危险状态添加警报或提示。 响应式设计（仅桌面端/网页端——嵌入式端：见第4部分）：
  • 首先针对主目标分辨率进行设计——带界面框架的桌面端、固定分辨率的嵌入式端，或应用典型的窗口调整范围。在宽度较窄时，堆叠、折叠或隐藏次要内容。
  • 最小布局宽度：240像素。低于此宽度时，堆叠或折叠元素。
  • 空间紧张时，将次要功能隐藏在菜单或下拉列表后。

1.1 Motion and animation (desktop/web — embedded: see section 4)

1.1 动效与动画（桌面端/网页端——嵌入式端：见第4部分）

Motion communicates state, relationship, and causality. Every animation must be functional, not decorative.
  • Enter animations: Use deceleration easing (fast start, slow end). Elements should appear to arrive, not just pop.
  • Exit animations: Use acceleration easing (slow start, fast end). Elements should appear to leave, not vanish.
  • Direct manipulation feedback: Respond within 100 ms. Operations taking > 1 s must show a progress indicator; > 10 s must show estimated time.
  • Duration budgets: Small elements (icons, badges): 100–150 ms. Medium elements (cards, panels): 200–300 ms. Full-screen transitions: 300–400 ms. Never exceed 500 ms for any UI animation — slower feels broken.
  • Limit simultaneous animations to one or two elements. Animating the whole screen at once disorients.
  • Animate only 
    transform
    and 
    opacity
     in QML/CSS — these are GPU-composited. Animating geometry (width, height, anchors) triggers layout recalculation and causes jank.
  • Honour user preference for reduced motion. On the web, gate non-essential animation behind the 
    prefers-reduced-motion
    CSS media query. Qt 6.x has no built-in equivalent: expose a project-level setting (for example a singleton property bound to 
    QSettings
    or to a runtime accessibility option) and gate animations on it. When the user opts out, replace animation with instant transitions — do not simply slow them down.
  • Spatial consistency: Elements that move between screens should animate in the direction that matches their destination (forward = slide left, back = slide right for LTR layouts).
动效用于传达状态、关系和因果性。每个动画都必须具备功能性，而非装饰性。
  • 入场动画： 使用减速缓动（快启动，慢结束）。元素应呈现“到达”效果，而非突然出现。
  • 退场动画： 使用加速缓动（慢启动，快结束）。元素应呈现“离开”效果，而非突然消失。
  • 直接操作反馈： 100毫秒内做出响应。耗时超过1秒的操作必须显示进度指示器；超过10秒的操作必须显示预计时间。
  • 时长预算： 小元素（图标、徽章）：100–150毫秒。中等元素（卡片、面板）：200–300毫秒。全屏过渡：300–400毫秒。任何UI动画时长不得超过500毫秒——过慢会让用户觉得界面卡顿。
  • 限制同时动画的元素数量为1-2个。同时动画整个屏幕会让用户迷失方向。
  • 仅对
    transform
    和
    opacity
    属性设置动画    （QML/CSS中）——这些属性由GPU合成。对几何属性（宽度、高度、锚点）设置动画会触发布局重新计算，导致卡顿。
  • 尊重用户的减少动效偏好。 在网页端，将非必要动画置于
    prefers-reduced-motion
    CSS媒体查询之后。Qt 6.x没有内置等效功能：需公开项目级设置（例如绑定到
    QSettings
    或运行时辅助功能选项的单例属性），并据此控制动画。当用户选择关闭动效时，用即时过渡替代动画——不要只是减慢动画速度。
  • 空间一致性： 在界面间移动的元素，其动画方向应与目标位置匹配（LTR布局中，前进=向左滑动，后退=向右滑动）。

1.2 Typography scale (desktop/web)

1.2 排版比例（桌面端/网页端）

For embedded typography, see section 4.4. This subsection governs desktop and web targets only.
Use a modular scale to derive all type sizes. A modular scale is a sequence of numbers related by a fixed ratio — every size is mathematically proportional to every other, producing a scale that feels harmonious rather than arbitrary. The ratios are listed below; see also https://www.modularscale.com/ for an interactive generator.
嵌入式端排版请见第4.4部分。本小节仅适用于桌面端和网页端目标。
使用模块化比例推导所有字体大小。 模块化比例是一组由固定比例关联的数字序列——每个大小在数学上与其他大小成比例，从而产生和谐而非随意的比例。以下列出可用比例；也可访问https://www.modularscale.com/ 使用交互式生成器。

How to build the scale

如何构建比例

  1. Choose a base — the size at which your body text looks best at the target viewing distance. For desktop at ~60 cm, 16 px is a reliable starting point. The base is your 
    ms(0)
    .
  2. Choose a ratio — multiply the base by this ratio to get the next step up, divide to get the next step down. Pick based on the character of the product: | Ratio | Name | Factor | Character | |---|---|---|---| | 8:9 | Major second | 1.125 | Compact, dense — good for data-heavy UIs, installer flows | | 5:6 | Minor third | 1.200 | Moderate — good for general desktop apps | | 4:5 | Major third | 1.250 | Open, comfortable — good for marketing, onboarding | | 3:4 | Perfect fourth | 1.333 | Strong contrast — good for dashboards, bold hierarchy | | 1:1.618 | Golden section | 1.618 | High contrast — use sparingly; large gaps between steps |
  3. Map scale steps to roles — assign a step number to each typographic role. Never add roles not on the scale; if a size is needed, pick the nearest step.
  1. 选择基准值——在目标观看距离下，正文文本显示效果最佳的大小。对于观看距离约60厘米的桌面端，16像素是可靠的起始值。基准值即为
    ms(0)
    。
  2. 选择比例——将基准值乘以该比例得到上一步的大小，除以该比例得到下一步的大小。根据产品特性选择： | 比例 | 名称 | 系数 | 特性 | |---|---|---|---| | 8:9 | 大二度 | 1.125 | 紧凑、密集——适用于数据密集型UI、安装流程 | | 5:6 | 小三度 | 1.200 | 适中——适用于通用桌面应用 | | 4:5 | 大三度 | 1.250 | 开阔、舒适——适用于营销、引导界面 | | 3:4 | 纯四度 | 1.333 | 强烈对比——适用于仪表盘、醒目层级结构 | | 1:1.618 | 黄金分割 | 1.618 | 高对比度——谨慎使用；步骤间差距较大 |
  3. 将比例步骤映射到角色——为每个排版角色分配一个步骤编号。切勿添加比例中没有的角色；若需要某个大小，选择最接近的步骤。

Worked example (base 16 px, Perfect Fourth 1.333)

示例（基准值16像素，纯四度1.333）

ms()Value (px, rounded)Role
ms(3)37.9 → 38 pxDisplay / hero text
ms(2)28.4 → 28 pxPage title / H1
ms(1)21.3 → 21 pxSection heading / H2
ms(0)16 pxBody — base
ms(-1)12.0 → 12 pxCaption / label / metadata
Use a maximum of three to four of these steps per screen. More than four active sizes creates visual noise.
ms()值（像素，取整）角色
ms(3)37.9 → 38像素展示/英雄文本
ms(2)28.4 → 28像素页面标题 / H1
ms(1)21.3 → 21像素章节标题 / H2
ms(0)16像素正文 —— 基准值
ms(-1)12.0 → 12像素说明文字/标签/元数据
每个界面最多使用3-4个此类步骤。超过4个活跃大小会造成视觉干扰。

Rules that apply to all modular scales

适用于所有模块化比例的规则

  • Body (ms(0)) minimum is 16 px at desktop viewing distance (~60 cm). Never use ms(-1) or smaller for primary reading content.
  • Line height: 1.4–1.6× for body. 1.1–1.2× for headings (they need less leading).
  • Line length: 45–75 characters per line for comfortable reading. Use 
    max-width
    on text containers — do not let prose span the full viewport.
  • Weight pairs: Use Regular (400) for body and captions; Medium (500) for headings. Never use Bold (700) inside body text.
  • System font first. Use the OS/platform system font by default (Segoe UI Variable on Windows, SF Pro on macOS, Roboto on Android/Linux). Only introduce a custom font when there is a brand requirement and a Figma token exists for it.
  • Verify at Large system font size. Do not hardcode pixel values that ignore the OS font scale. In Qt, prefer 
    font.pointSize
    (which respects the platform DPI scale) over 
    font.pixelSize
    for body text, or derive sizes from a singleton driven by 
    Screen.pixelDensity
    . On the web, use relative units (
    rem
    ).
  • 正文（ms(0)）在桌面端观看距离（约60厘米）下最小为16像素。切勿将ms(-1)或更小的大小用于主要阅读内容。
  • 行高： 正文为1.4–1.6倍。标题为1.1–1.2倍（标题需要更少的行距）。
  • 行长度： 每行45–75个字符，便于舒适阅读。为文本容器设置
    max-width
    ——不要让文本横跨整个视口。
  • 字重搭配： 正文和说明文字使用常规字重（400）；标题使用中等字重（500）。切勿在正文中使用粗体（700）。
  • 优先使用系统字体。 默认使用操作系统/平台的系统字体（Windows上为Segoe UI Variable，macOS上为SF Pro，Android/Linux上为Roboto）。仅当有品牌要求且存在Figma令牌时，才引入自定义字体。
  • 在系统大字体大小下验证。 不要硬编码忽略操作系统字体缩放的像素值。在Qt中，对于正文文本，优先使用
    font.pointSize
    （会尊重平台DPI缩放）而非
    font.pixelSize
    ，或从由
    Screen.pixelDensity
    驱动的单例中派生大小。在网页端，使用相对单位（
    rem
    ）。

Qt/QML implementation

Qt/QML实现

In QML, define the scale as a singleton (e.g. 
TypeScale.qml
) so sizes are referenced by role name, not hardcoded values:
qml
// TypeScale.qml — generated from modular scale, base 16, ratio 1.333
pragma Singleton
import QtQuick

QtObject {
    readonly property real base:    16   // ms(0)
    readonly property real h2:      21   // ms(1)
    readonly property real h1:      28   // ms(2)
    readonly property real display: 38   // ms(3)
    readonly property real caption: 12   // ms(-1)
}
Reference via 
TypeScale.h1
in components. Recalculate the whole singleton when the base or ratio changes — never patch individual values.
Register the singleton in your QML module so it can be imported. In a 
qmldir
file:
module MyApp.Theme
singleton TypeScale 1.0 TypeScale.qml
In CMake with 
qt_add_qml_module
:
cmake
qt_add_qml_module(myapp_theme
    URI MyApp.Theme
    VERSION 1.0
    QML_FILES TypeScale.qml
)
set_source_files_properties(TypeScale.qml PROPERTIES QT_QML_SINGLETON_TYPE TRUE)
在QML中，将比例定义为单例（例如
TypeScale.qml
），以便通过角色名称引用大小，而非硬编码值：
qml
// TypeScale.qml — generated from modular scale, base 16, ratio 1.333
pragma Singleton
import QtQuick

QtObject {
    readonly property real base:    16   // ms(0)
    readonly property real h2:      21   // ms(1)
    readonly property real h1:      28   // ms(2)
    readonly property real display: 38   // ms(3)
    readonly property real caption: 12   // ms(-1)
}
在组件中通过
TypeScale.h1
引用。当基准值或比例改变时，重新计算整个单例——切勿单独修改个别值。
在QML模块中注册该单例，以便导入。在
qmldir
文件中：
module MyApp.Theme
singleton TypeScale 1.0 TypeScale.qml
在CMake中使用
qt_add_qml_module
：
cmake
qt_add_qml_module(myapp_theme
    URI MyApp.Theme
    VERSION 1.0
    QML_FILES TypeScale.qml
)
set_source_files_properties(TypeScale.qml PROPERTIES QT_QML_SINGLETON_TYPE TRUE)

1.3 Multi-input and keyboard navigation (desktop/web)

1.3 多输入与键盘导航（桌面端/网页端）

Every desktop and web interface must support multiple input methods. Do not design for pointer alone.
  • Full keyboard navigability is required. Tab order must follow the visual reading order (top-left to bottom-right for LTR). Always render a visible focus indicator — in QML, drive it from 
    activeFocus
    (for example a 
    Rectangle
    border or scale bound to 
    activeFocus
    ) or use the style-specific focus visuals on 
    Control
    . On the web, do not remove the focus ring without a styled replacement.
  • No keyboard traps. Users navigating by keyboard must always be able to exit any modal, popover, or overlay using Escape or a keyboard-accessible close control.
  • Every interactive element must be reachable by pointer, keyboard, and — where Qt's accessibility APIs expose it — screen reader. This is a requirement, not a recommendation.
  • Hover states are an enhancement, not the primary disclosure mechanism. Any information shown on hover must also be accessible without a pointer (e.g. a visible label, a dedicated info button, or keyboard-triggered tooltip).
  • Touch and pointer coexist. On touch devices that also support a stylus or pointer, do not remove touch targets when a pointer is detected.
每个桌面端和网页端界面都必须支持多种输入方式。切勿仅针对指针设计。
  • 必须支持全键盘导航。 Tab顺序必须遵循视觉阅读顺序（LTR布局中为左上至右下）。始终渲染可见的焦点指示器——在QML中，从
    activeFocus
    驱动（例如绑定到
    activeFocus
    的
    Rectangle
    边框或缩放效果），或使用
    Control
    上的样式特定焦点视觉效果。在网页端，若未设置样式化替代方案，请勿移除焦点环。
  • 无键盘陷阱。 使用键盘导航的用户必须始终能够使用Esc键或键盘可访问的关闭控件退出任何模态框、弹出框或覆盖层。
  • 每个交互元素都必须可通过指针、键盘以及（当Qt辅助功能API暴露时）屏幕阅读器访问。这是强制要求，而非建议。
  • 悬停状态是增强功能，而非主要展示机制。 悬停时显示的任何信息也必须无需指针即可访问（例如可见标签、专门的信息按钮或键盘触发的提示框）。
  • 触摸与指针共存。 在同时支持手写笔或指针的触摸设备上，检测到指针时请勿移除触摸目标。

1.4 Semantic colour

1.4 语义化色彩

Colour should communicate meaning consistently across the entire interface. Avoid arbitrary colour choices.
  • Use role-based tokens, not raw hex values. Token names should describe the role a colour plays (interactive, surface, on-surface, error, outline), not its appearance (blue, dark-blue, grey-2). The role vocabulary above mirrors Material Design 3; when the project's design language is Fluent 2 or Apple Human Interface Guidelines, map to the equivalent role names from those systems rather than mixing vocabularies. If the project ships with a Figma token set, copy the tokens manually into a singleton until tooling is available to extract them.
  • Distinguish interactive colour from decorative colour. A colour used on a button to signal "this is tappable" must not also be used as a background accent that doesn't invite interaction. Reusing interactive colour decoratively trains users to tap things that aren't tappable.
  • Colour is never the sole carrier of state. Already covered in section 2 (WCAG), but applies equally to non-disabled states: success, warning, and error must always pair colour with an icon or text label.
  • Dark mode: Design for both light and dark themes from the start. Token-based colour systems handle this automatically — if hardcoded colours are used, a dark variant must be explicitly defined.
  • Culturally variable colour meanings (see also §1.5): Red = danger in Western contexts but good fortune in some East Asian contexts. White = purity in Western contexts but mourning in some East Asian contexts. For safety-critical or internationally shipped products, do not rely on colour alone to convey critical meaning — always pair with text or universal iconography.
色彩应在整个界面中一致地传达含义。避免随意选择色彩。
  • 使用基于角色的令牌，而非原始十六进制值。 令牌名称应描述色彩的角色（交互色、表面色、表面文字色、错误色、轮廓色），而非其外观（蓝色、深蓝色、灰色2）。上述角色词汇与Material Design 3一致；若项目设计语言为Fluent 2或Apple人机界面指南，请映射到这些系统中的等效角色名称，而非混合词汇。若项目附带Figma令牌集，请手动将令牌复制到单例中，直到有工具可提取它们。
  • 区分交互色与装饰色。 用于按钮以表示“可点击”的色彩，不得同时用作不触发交互的背景强调色。重复使用交互色作为装饰色会使用户养成点击不可交互元素的习惯。
  • 色彩绝非状态的唯一载体。 第2部分（WCAG）已涵盖此点，但同样适用于非禁用状态：成功、警告和错误状态必须始终搭配图标或文本标签。
  • 深色模式： 从一开始就同时设计浅色和深色主题。基于令牌的色彩系统会自动处理此问题——若使用硬编码色彩，则必须明确定义深色变体。
  • 文化差异导致的色彩含义变化（另见§1.5）：红色在西方语境中表示危险，但在部分东亚语境中表示好运。白色在西方语境中表示纯洁，但在部分东亚语境中表示哀悼。对于安全关键型或面向国际市场的产品，切勿仅依赖色彩传达关键含义——始终搭配文本或通用图标。

1.5 Localisation and RTL layout

1.5 本地化与RTL布局

Ask question 7 in the intake. Act on the answer here.
  • Date, time, and number formats must be locale-aware. Never hardcode format strings like 
    DD/MM/YYYY
    . Use Qt's 
    QLocale
    or the platform locale API.
  • RTL layout mirroring: For Arabic, Hebrew, Farsi, and Urdu, the entire layout mirrors horizontally. Navigation moves from right to left. Back buttons point right. Icons that imply direction (arrows, chevrons, playback controls) must flip. Enable 
    LayoutMirroring.enabled
    with 
    LayoutMirroring.childrenInherit: true
    near the root of your scene; it handles anchors and Qt Quick Layouts. The following items still need explicit attention even when 
    LayoutMirroring
    is enabled: 
    Text.horizontalAlignment
    defaults, 
    Image
    content (use 
    mirror: true
    on directional icons), custom 
    Canvas
    painting, and any manual 
    x
    positions.
  • Text expansion: Translated strings are typically 30–40% longer than English source. Design containers and buttons to accommodate expansion — avoid fixed-width containers for any user-visible string.
  • Icons: Avoid icons that are culturally specific or that carry variable meaning across regions (e.g. a thumbs-up, certain hand gestures). Prefer universal symbols (checkmark for success, X for close, magnifying glass for search).
  • Avoid embedding text in images or icons. Localisation requires all text to be in string resources — text baked into assets cannot be translated.
在需求收集阶段询问第7项问题。在此根据答案采取行动。
  • 日期、时间和数字格式必须支持区域设置。切勿硬编码格式字符串，如
    DD/MM/YYYY
    。使用Qt的
    QLocale
    或平台区域设置API。
  • RTL布局镜像： 对于阿拉伯语、希伯来语、波斯语和乌尔都语，整个布局需水平镜像。导航从右到左。返回按钮指向右侧。暗示方向的图标（箭头、V形、播放控件）必须翻转。在场景根节点附近启用
    LayoutMirroring.enabled
    并设置
    LayoutMirroring.childrenInherit: true
    ；它会处理锚点和Qt Quick布局。即使启用了
    LayoutMirroring
    ，以下内容仍需显式处理：
    Text.horizontalAlignment
    默认值、
    Image
    内容（对方向图标使用
    mirror: true
    ）、自定义
    Canvas
    绘制以及任何手动设置的
    x
    位置。
  • 文本扩展： 翻译后的字符串通常比英文原文长30–40%。设计容器和按钮时需考虑扩展需求——避免为任何用户可见的字符串使用固定宽度容器。
  • 图标： 避免使用具有文化特异性或在不同地区含义不同的图标（如竖起大拇指、某些手势）。优先使用通用符号（对勾表示成功，叉号表示关闭，放大镜表示搜索）。
  • 避免在图像或图标中嵌入文本。 本地化要求所有文本都在字符串资源中——嵌入到资源中的文本无法翻译。

2. Accessibility (WCAG 2.2)

2. 无障碍设计（WCAG 2.2）

Check every design against these before delivering:
  • Perceivable: All information has a non-visual equivalent (alt text, labels). Contrast ≥ 4.5:1 for text, ≥ 3:1 for large text and UI components.
  • Operable: Full keyboard navigation, no focus traps. All interactive targets reachable without a pointer.
  • Understandable: Labels, instructions, and error messages are plain language.
  • Robust: Markup and structure work with screen readers and assistive tools.
  • Never rely on color alone to communicate state — always pair with shape, icon, or text.
  • Test with OS font size set to Large — verify that layout tolerates text scaling without truncation or overflow.
  • Test with a colour-blindness simulation (Deuteranopia is the most common) — confirm that all state changes are distinguishable without colour.
  • Validate focus order — tab through every interactive element and confirm the sequence is logical. Focus must be visible at all times — see §1.3 for the Qt-side focus indicator pattern.
交付前，请对照以下内容检查每个设计：
  • 可感知性： 所有信息都有非视觉等效形式（替代文本、标签）。文本对比度≥4.5:1，大文本和UI组件对比度≥3:1。
  • 可操作性： 全键盘导航，无焦点陷阱。所有交互目标无需指针即可访问。
  • 可理解性： 标签、说明和错误消息使用简洁语言。
  • 健壮性： 标记和结构可与屏幕阅读器及辅助工具配合使用。
  • 切勿仅依赖色彩传达状态——始终搭配形状、图标或文本。
  • 在系统大字体大小下测试——验证布局在文本缩放时不会出现截断或溢出。
  • 使用色盲模拟测试（红绿色盲最常见）——确认所有状态变化无需依赖色彩即可区分。
  • 验证焦点顺序——通过Tab键遍历每个交互元素，确认顺序符合逻辑。焦点必须始终可见——有关Qt端焦点指示器模式，请见§1.3。

3. AI-specific UX

3. AI专属UX设计

When designing screens that involve AI features:
  • User Control: Users must be able to start, stop, and modify AI actions. Always include Undo or Regenerate.
  • Transparency: Show why the AI made a decision when it affects the user.
  • Graceful Failure: When AI fails, provide a clear manual fallback path.
  • Value over Novelty: AI features must solve a real problem — not exist for demonstration.
  • Uncertainty Communication: AI output is probabilistic. When confidence is low or the result may be incorrect, surface that — use hedging language ("suggested", "approximately", "review before using"), visual confidence indicators, or explicit labelling. Never present probabilistic output as authoritative fact. For Qt AI Assistant and similar features, provide a "show source" or "why this?" affordance wherever the answer affects consequential decisions.
  • Latency patterns: AI operations typically take 1–15 seconds. Do not show a generic spinner — users cannot estimate duration from a spinner and become anxious after ~3 s.
    • Streaming output (text generation): begin rendering partial results immediately. Show a blinking cursor or pulsing indicator at the insertion point while generation continues.
    • Long operations (code generation, image processing): show a skeleton screen or placeholder that matches the shape of the expected result. This anchors attention and sets expectations.
    • Background operations (indexing, analysis): surface as a subtle persistent status indicator (progress bar in a status bar, animated icon in a toolbar), not a blocking modal.
    • Never blank the entire screen while waiting for an AI response.
  • Consent before action: If an AI feature will read, send, or modify user data (files, code, settings), make this explicit before the action executes. A one-line confirmation ("This will read your project files to generate a suggestion") is sufficient — it does not need to be a modal dialog.
设计涉及AI功能的界面时：
  • 用户控制权： 用户必须能够启动、停止和修改AI操作。始终包含撤销或重新生成功能。
  • 透明度： 当AI决策影响用户时，说明决策原因。
  • 优雅降级： AI失效时，提供清晰的手动回退路径。
  • 价值优先于新颖性： AI功能必须解决实际问题——而非仅为展示而存在。
  • 不确定性传达： AI输出具有概率性。当置信度较低或结果可能不正确时，需明确告知——使用模糊语言（“建议”、“大约”、“使用前请审核”）、视觉置信度指示器或明确标签。切勿将概率性输出作为权威事实呈现。对于Qt AI助手及类似功能，每当答案影响重要决策时，需提供“显示来源”或“为何如此？”的功能入口。
  • 延迟处理模式： AI操作通常耗时1–15秒。请勿显示通用加载动画——用户无法通过加载动画估计时长，约3秒后会变得焦虑。
    • 流式输出（文本生成）：立即开始渲染部分结果。生成过程中，在插入点显示闪烁光标或脉动指示器。
    • 长时操作（代码生成、图像处理）：显示骨架屏或与预期结果形状匹配的占位符。这会吸引用户注意力并设置预期。
    • 后台操作（索引、分析）：以微妙的持久状态指示器呈现（状态栏中的进度条、工具栏中的动画图标），而非阻塞式模态框。
    • 等待AI响应时，切勿清空整个屏幕。
  • 操作前征得同意： 若AI功能将读取、发送或修改用户数据（文件、代码、设置），需在操作执行前明确告知。一行确认信息（“此操作将读取你的项目文件以生成建议”）即可——无需使用模态对话框。

4. Embedded and MCU targets

4. 嵌入式与MCU目标平台

This section overrides desktop defaults. Read it fully before designing for any embedded, MCU, or hardware-constrained target.
Hardware facts that drive every decision (collect these during the intake step above if not already answered):
  • Physical pixel dimensions and DPI
  • GPU present? If unknown, assume none.
  • Available RAM and flash for UI assets
  • Input method: touchscreen, hardware buttons, rotary encoder, pointer
  • Whether a board-specific skill exists
本部分覆盖桌面端默认设置。为任何嵌入式、MCU或硬件受限目标平台设计前，请完整阅读本部分。
驱动所有决策的硬件事实（若未回答，在需求收集阶段收集这些信息）：
  • 物理像素尺寸和DPI
  • 是否存在GPU？若未知，假设不存在。
  • UI资源可用的RAM和闪存
  • 输入方式：触摸屏、硬件按钮、旋转编码器、指针
  • 是否存在针对该开发板的专属技能

4.1 Rendering without a GPU

4.1 无GPU情况下的渲染

Software rasterisation means every visual effect costs CPU time.
AllowedNot allowed
Flat solid fillsGradients
1 px solid strokesDrop shadows
Bitmap (PNG) icons and fontsBlur or transparency layers
Opacity-only transitionsSimultaneous move + fade animations
Fixed pixel layoutFlexbox or fluid layout
Prefer bitmap icons over vector paths — raster cost is paid at compile time, not runtime. Relax these constraints only when a GPU is confirmed. Exceptions. The constraints above apply to runtime software rasterisation. Qt Quick Ultralite supports compile-time-baked gradients via its static rendering pipeline. Some MCUs ship with a 2D blitter or a small GPU that relaxes the no-blur and no-transparency constraints. Verify the hardware data sheet and the Qt toolchain in use before treating the table as a hard prohibition.
软件光栅化意味着每个视觉效果都会消耗CPU时间。
允许不允许
纯色填充渐变
1像素实线描边投影
位图（PNG）图标和字体模糊或透明层
仅透明度过渡同时移动+淡入淡出动画
固定像素布局Flexbox或流式布局
优先使用位图图标而非矢量路径——光栅化成本在编译时支付，而非运行时。仅当确认存在GPU时，才可放宽这些限制。 例外情况。 上述约束适用于运行时软件光栅化。Qt Quick Ultralite通过其静态渲染管道支持编译时预先生成的渐变。部分MCU配备2D位块传输器或小型GPU，可放宽无模糊和无透明的约束。在将上表视为硬性禁止规则前，请验证硬件数据表和所使用的Qt工具链。

4.2 Layout

4.2 布局

  • Fixed pixel layout. No fluid grids, no breakpoints. Design to the exact screen dimensions.
  • One task per screen. No overlapping panels.
  • Flat navigation: move between screens, not within them. Max 2 levels deep.
  • System state (connected, error, active mode) must be permanently visible — no tooltips or hover states.
  • 固定像素布局。无流式网格，无断点。针对精确的屏幕尺寸设计。
  • 每个界面完成一项任务。无重叠面板。
  • 扁平化导航：在界面间切换，而非在界面内导航。最多2层深度。
  • 系统状态（已连接、错误、活跃模式）必须永久可见——无提示框或悬停状态。

4.3 Interaction

4.3 交互

  • No hover states. Replace hover-triggered disclosure with explicit buttons or dedicated screens.
  • Touch minimum: 48 px is the default. Some controlled environments (fixed-grip medical instruments, secured industrial panels) may justify smaller targets after explicit safety review. Gloved-hand environments (industrial, outdoor): 60–72 px.
  • Every action must have a hardware button fallback. No touch-only actions.
  • No drag, scroll inertia, or multi-touch unless hardware confirms support.
  • Confirm before any action that controls a physical actuator.
  • 无悬停状态。将悬停触发的展示替换为显式按钮或专门界面。
  • 触摸目标最小尺寸：默认48像素。部分受控环境（固定握持的医疗设备、安全工业面板）在经过明确安全审查后，可使用更小的目标。戴手套操作的环境（工业、户外）：60–72像素。
  • 每个操作都必须有硬件按钮回退方案。无仅触摸操作。
  • 除非硬件确认支持，否则无拖拽、滚动惯性或多点触摸。
  • 在执行任何控制物理执行器的操作前进行确认。

4.4 Typography

4.4 排版

Embedded fonts are bitmaps — size is fixed at build time. Get it right from the start.
Viewing distanceMinimum size
~50 cm (handheld, appliance)14 px min, 16 px preferred
~1.0–1.5 m (HMI, instrument cluster)20 px min
~2–3 m (wall panel, public display)28 px min
Contrast ≥ 4.5:1 for all text. Embedded screens often have poor viewing angles and bright ambient light — higher contrast is always better.
嵌入式字体为位图——大小在构建时固定。从一开始就确保设置正确。
观看距离最小尺寸
~50厘米（手持设备、家电）最小14像素，推荐16像素
~1.0–1.5米（HMI、仪表盘）最小20像素
~2–3米（墙面面板、公共显示屏）最小28像素
所有文本对比度≥4.5:1。嵌入式屏幕通常视角较差且环境光线明亮——对比度越高越好。

4.5 Error and safety

4.5 错误与安全

  • Confirm before irreversible physical actuator commands — this is a safety requirement.
  • Error state indicators must be persistent: driven by application state, not transient UI state. They must survive a screen repaint.
  • Alarms require three independent cues: color + shape + text.
  • Define a safe default screen the UI returns to if the application crashes or loses communication.
  • No silent failures — unacknowledged hardware commands must be surfaced visibly.
  • 在执行不可逆的物理执行器命令前进行确认——这是安全要求。
  • 错误状态指示器必须持久：由应用状态驱动，而非临时UI状态。它们必须在屏幕重绘后仍保持可见。
  • 警报需要三个独立提示：色彩+形状+文本。
  • 定义一个安全默认界面，当应用崩溃或失去通信时，UI会返回该界面。
  • 无静默失败——未确认的硬件命令必须以可见方式呈现。

4.6 Desktop → MCU quick reference

4.6 桌面端→MCU快速参考

RuleDesktop / webMCU / embedded
ResponsivenessFlexbox, fluidFixed pixel layout
AnimationEasing curves, ≤ 400 msOpacity-only, < 200 ms
Progressive disclosureTooltips, hoverExplicit button only
Touch targets44 px recommended48 px default (relax only with explicit safety review)
Font renderingVector, OS-scalableBitmap, fixed at build time
Status communicationColor + token-basedColor + shape + text
Error recoveryUndoConfirm before action
State visibilityStatus bar / tooltipAlways on screen
Navigation depthUnlimitedMax 2 levels
LocalisationQLocale, RTL mirroringQLocale only (RTL rarely applicable)
规则桌面端/网页端MCU/嵌入式端
响应式Flexbox、流式固定像素布局
动画缓动曲线，≤400毫秒仅透明度，<200毫秒
渐进式展示提示框、悬停仅显式按钮
触摸目标推荐44像素默认48像素（仅在明确安全审查后放宽）
字体渲染矢量、系统可缩放位图、构建时固定
状态传达色彩+基于令牌色彩+形状+文本
错误恢复撤销操作前确认
状态可见性状态栏/提示框始终在屏幕上
导航深度无限制最多2层
本地化QLocale、RTL镜像仅QLocale（RTL很少适用）

5. Audit instructions

5. 审核说明

When auditing an existing design, categorize every finding:
  1. Critical — Violates a core UX law or WCAG accessibility rule. Must fix.
  2. Warning — Potential friction or elevated cognitive load. Should fix.
  3. Opportunity — Enhancement or AI-driven improvement. Consider. Apply section 4 constraints first if the target is embedded.
Extended audit checklist for desktop/web targets:
  • Motion: are animations ≤ 400 ms, functional, and does a reduced-motion path exist?
  • Typography: are body text ≥ 16 px and no more than three type sizes used per screen?
  • Keyboard: is every interactive element reachable and operable by keyboard alone?
  • Colour: are all colours token-based or semantically named? Is colour paired with a second cue for all state changes?
  • Localisation: do all user-visible strings use locale-aware formatting? Are containers able to expand 30–40% for translated text?
  • AI features: are latency patterns, uncertainty, and consent handled per section 3?
审核现有设计时，将每个发现分类：
  1. 严重问题——违反核心UX原则或WCAG无障碍规则。必须修复。
  2. 警告——存在潜在摩擦或认知负荷过高。应该修复。
  3. 优化机会——增强功能或AI驱动的改进。可考虑修复。 若目标为嵌入式平台，优先应用第4部分的约束。
桌面端/网页端扩展审核清单：
  • 动效：动画时长是否≤400毫秒、具备功能性，且存在减少动效的路径？
  • 排版：正文文本是否≥16像素，且每个界面使用的字体大小不超过3种？
  • 键盘：每个交互元素是否可通过键盘单独访问和操作？
  • 色彩：所有色彩是否基于令牌或语义化命名？所有状态变化是否搭配第二种提示？
  • 本地化：所有用户可见字符串是否使用支持区域设置的格式？容器是否可扩展30–40%以容纳翻译后的文本？
  • AI功能：延迟处理模式、不确定性和同意机制是否符合第3部分要求？

6. References

6. 参考资料