$npx -y skills add TheQtCompanyRnD/agent-skills --skill qt-ui-designDesign or audit UI for Qt/QML, Qt projects, web, or embedded MPU or MCU targets. Use when creating screens, layouts, navigation, or auditing UX.
| 1 | # Qt UI Design |
| 2 | 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. |
| 3 | |
| 4 | 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. |
| 5 | |
| 6 | ## 0. Context check (before designing) |
| 7 | |
| 8 | 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. |
| 9 | |
| 10 | 1. **Target platform** — Desktop, web browser, mobile, or specific hardware (MCU, Raspberry Pi, other embedded board)? |
| 11 | - If a specific board: ask whether a board-specific skill exists for it and load it if so. |
| 12 | 2. **Screen shape** — Rectangle (default), Square, or Circle? |
| 13 | 3. **Resolution and DPI** — Do you know the screen resolution and DPI? (Approximate is fine.) |
| 14 | 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. |
| 15 | 5. **Content priority** — What information is most important (primary), secondary, and tertiary on this screen? |
| 16 | 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) |
| 17 | 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)? |
| 18 | If the target is an embedded or MCU device, also read **section 4** in full before any design decisions — it overrides several desktop defaults. |
| 19 | |
| 20 | If the user is requesting an **audit of an existing design**, skip to section 5 (Audit). |
| 21 | |
| 22 | --- |
| 23 | |
| 24 | ## 1. Design principles to apply (all targets) |
| 25 | |
| 26 | Apply these while designing. Do not ask about each one — use them to inform decisions silently. |
| 27 | |
| 28 | **Content and layout:** |
| 29 | - **Golden Ratio + Rule of Thirds:** Place primary elements at visual intersections. |
| 30 | - **Progressive Disclosure:** Show only what is needed at the current step. |
| 31 | - **Inverted Pyramid:** Critical information first, elaboration after. |
| 32 | - **Modularity:** Divide complex flows into smaller, self-contained screens. |
| 33 | - **Ockham's Razor:** When two designs are equivalent, choose the simpler one. |
| 34 | - **Performance Load:** Fewer steps = higher task completion. |
| 35 | - **Five Hat Racks:** Organise by category, time, location, alphabet, or continuum. |
| 36 | **Perception and interaction:** |
| 37 | - **Jakob's Law:** Match patterns users already know. |
| 38 | - **Affordance:** Controls should look like what they do. |
| 39 | - **Hick's Law:** More choices = slower decisions. Limit options per screen. |
| 40 | - **Miller's Law:** Working memory holds ~7 items. Chunk accordingly. |
| 41 | - **Recognition Over Recall:** Show options; don't require memorisation. |
| 42 | - **Proximity + Similarity:** Group related elements visually. |
| 43 | - **Uniform Connectedness:** Shared border or color = same group. |
| 44 | - **von Restorff Effect:** One visually distinct element draws attention — use sparingly. |
| 45 | - **Peak-End Rule:** Users remember the peak moment and the ending. Design completion states (e.g. installer finish screens) to feel rewarding, not abrupt. |
| 46 | - **Doherty Threshold:** System feedback within 400 ms, or show a progress indicator. |
| 47 | - **Aesthetic-Usability Effect:** Polished design is perceived as more usable. |
| 48 | - **Wayfinding:** Users must always know where they are, where they've been, where they can go. |
| 49 | **Reading patterns (use to guide information placement):** |
| 50 | - **F-shaped:** Text-heavy content — top bar, shorter secondary bar, left-edge scan. |
| 51 | - **Z-shaped:** Sparse content — top-left → top-right → diagonal → bottom-right. |
| 52 | - **Layer-cake:** Users scan headings and skip body text. |
| 53 | - **Spotted:** Users jump to landmarks — links, capitals, |