/qt-ui-design

name: qt-ui-design
description: >-
  Design or audit UI for Qt/QML, Qt projects, web, or embedded MPU or MCU targets. Use when creating screens, layouts, navigation, or auditing UX.
license: LicenseRef-Qt-Commercial OR BSD-3-Clause
compatibility: >-
  Designed for Claude Code, GitHub Copilot, and similar agents.
disable-model-invocation: false
metadata:
  author: qt-ai-skills
  version: "1.1"
  qt-version: "6.x"
  category: conceptual
  changelog: "Initial release"

Qt UI Design

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.

0. Context check (before designing)

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).

---

1. Design principles to apply (all targets)

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.

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

Motion communicates state, relationship, and causality. Every anim