# Desktop shell UX digest ## Historical record Recorded names, source locations and external scratch evidence describe the review's original tree, not current runtime APIs. Research input to the Zen of Nugu, fetched 2026-11-14; citation keys are listed at the end. ## 1. Principles ### Purpose and restraint 1. Pick one situation and one kind of experience; don't try to suit everyone. [G-pr] [K-ia] 2. Put frequent actions close at hand and less important ones further away, using progressive disclosure. [G-pr] [K-sd] 3. Cut every extra piece of information, because each one competes with what matters. [NN] 4. If something can be done automatically, do it, and minimise the steps a task needs. [G-pr] [K-sd] 5. Keep the primary function visible; anything reachable only by hover, shortcut or gesture must be low-importance. [K-sd] [K-pw] ### Layout and hierarchy 6. Place items in reading order, and remember that the leading item gets the most attention. [K-ln] 7. Show grouping through spacing: tighter inside a group, wider between groups, and only group things that really belong together. [K-ln] 8. Bars hold few controls, aligned to start, centre and end, and their content changes with context. [G-hb] 9. Popovers stay small (GNOME: no more than ⅓ of the parent), low in complexity, and group similar controls together. [G-pop] [A-pop] 10. Position a popover so it points at its trigger without covering the trigger or essential content. [A-pop] ### Text and labels 11. Keep text short but unambiguous: a clear three-word label beats a vague one-word label. [G-ws] [K-tl] 12. Use the user's words, not system jargon, and avoid acronyms (memory, not RAM). [NN] [G-ws] [K-tl] 13. Use imperative verbs for buttons and menu commands, nouns for switches, and positive phrasing. [G-btn] [G-sw] [K-tl] 14. Leave out terminal periods, put the distinctive words first, and avoid "you". [G-ws] [K-tl] [K-a11y] - *Disagreement:* GNOME uses header capitalisation for labels, KDE uses title or sentence case, and Apple uses title case for notification titles; your lowercase-only rule departs from all three. ### Icons 15. Prefer simple, universal symbolic icons at small sizes, and never use the same icon for two visible actions. [K-ic] [MS-tray] 16. Every icon-only control still needs an accessible name and a tooltip. [K-tl] [G-tt] [G-a11y] - *Disagreement:* GNOME says buttons outside header bars carry an icon or a label, not both. KDE says most buttons should include text and puts an icon on every button. [G-btn] [K-ic] ### Feedback and state 17. Always show system status, and give feedback quickly. [NN] 18. Show success by changing the affected UI, not with a "done" message. [K-st] 19. Show a progress indicator for anything longer than about 1 s. [K-sd] 20. A switch's colour can show that a feature is "on but not yet online"; an unavailable feature gets an insensitive switch. [G-sw] 21. Make invalid actions insensitive instead of letting them fail with an error. [G-btn] [K-gi] - *Disagreement:* KDE disables irrelevant menu items rather than hiding them. Microsoft removes tray context-menu items that don't apply. [K-ln] [MS-tray] ### Motion 22. Use motion only with a purpose, keep it brief, and avoid animating frequent interactions. [A-mo] 23. Let motion be cancelled and never make people wait for an animation to finish. [A-mo] 24. Motion must be optional: with animations off, transitions happen instantly or show a static image. [W-anim] [K-a11y] [A-a11y] ### Keyboard and focus 25. Every pointer action must also be possible from the keyboard, with a logical Tab order and arrow keys for directional movement. [G-kb] [K-a11y] 26. Esc closes a popover and cancels any pointer operation in progress. [G-pop] [G-pt] [MS-fly] 27. A focus indicator must always be visible and never fully hidden by other content. [W-fv] [W-fno] 28. Avoid Super/Meta for anything except global shortcuts, and avoid shortcuts that need a lone function key or an awkward stretch. [G-kb] [K-pw] [K-ln] ### Pointer and targets 29. Never rely on hover to reveal actions or essential information. [G-pt] [K-a11y] 30. Avoid double-click, chording and middle-click; right-click opens a context menu only when there is a real set of items. [G-pt] [G-btn] - *Disagreement:* the Microsoft Win7 tray guide does assign double-click to the default command. [MS-tray] 31. Spacing between targets matters as much as their size. [A-a11y] [MS-tgt] ### Errors and recovery 32. Prevent errors first; every remaining error message must say in plain words what happened and how to fix it or move on. [NN] [K-st] 33. Never fail silently. [K-st] 34. Offer undo for destructive actions. [G-pr] [MS-dlg] - *Disagreement:* GNOME prefers undo over confirmation, while NN/g allows a confirmation step before committing. [G-pr] [NN] ### Notifications and interruption 35. Notify only about asynchronous events that are useful and relevant, never for expected or ignorable ones. [MS-notif] [K-st] [G-notif] 36. Use an OSD (on-screen display), not a notification, for system changes the user started, such as volume or brightness, and never show an OSD for an automatic change. [K-st] 37. Remove notifications that are no longer valid, rate-limit them or send summaries, and don't repeat the same one. [G-notif] [MS-un] [A-notif] 38. Set urgency honestly: critical notifications stay until dismissed, and normal ones are optionally persistent. [K-st] [A-mn] 39. Keep private details out of notifications. [A-notif] ### Accessibility 40. Colour is never the only signal: pair it with shape, text or an icon, and use colour sparingly to draw attention. [G-sty] [K-st] 41. Test with keyboard only, large text, high contrast, a screen reader and animations off. [G-a11y] [K-a11y] ### Consistency 42. Follow platform conventions and keep custom styling minimal. [NN] [K-sd] [G-sty] 43. Allow only one suggested or destructive button per view. [G-btn] (43 items: 3 over the 25–40 range; 41–43 can be merged into earlier groups if you want to stay within it.) ## 2. Numbers | Topic | Value | Source | |---|---|---| | Text contrast | ≥4.5:1, or ≥3:1 for large text | [W-cm] [A-a11y] | | Contrast of controls, states and focus indicators | ≥3:1 against adjacent colours | [W-ntc] | | Focus indicator (AAA) | area ≥ a 2 px perimeter, ≥3:1 between focused and unfocused pixels | [W-fa] | | Pointer target (AA) | ≥24×24 px, or a 24 px circle that touches no other target | [W-ts] | | macOS controls | 28×28 pt default, 20×20 pt minimum | [A-a11y] | | Padding around targets | ≈12 pt with a bezel, ≈24 pt without | [A-a11y] | | Windows touch target | 7.5 mm ≈ 40×40 px at 135 PPI | [MS-tgt] | | macOS text | 13 pt default, 10 pt minimum; support enlargement up to 200 % | [A-a11y] | | macOS menu bar height | 24 pt | [A-mb] | | KDE grid unit | 18 px; spacing uses small, medium and large units | [K-ln] | | Spacing rules | title↔subtitle 0, related items small, toolbar items medium, groups and edges large | [K-ln] | | Icon sizes | 16 px and 22 px symbolic, 32 px and up full colour | [K-ic] | | Line length | ≤85 characters (≈450 px) | [K-tl] | | Interactive label length | no longer than "Configure Keyboard Shortcuts" | [K-tl] | | Menu size | 3–12 items; submenus 3–6; no nested submenus | [G-menu] | | Hamburger menu | about 15 items or fewer | [K-ln] | | Choice controls | radio buttons for ≤3 options, combo box for ≤10, list for more | [K-gi] | | Inline actions on a list row | at most 2 | [K-ic] | | Notification buttons | at most 3 | [G-notif] | | Button widths | 1–2 widths per window | [G-btn] | | Progress indicator | for tasks over 1 s | [K-sd] | | Delay before spinner or search | `humanMoment` (2 s per its doc; the numeric value isn't on the page) | [K-u] | | Animation durations | 83, 167 and 250 ms | [MS-tim] | | Easing | enter `cubic-bezier(0,0,0,1)`, exit `cubic-bezier(1,0,1,1)` | [MS-tim] | | Kirigami durations | named (veryShort through veryLong), no ms values published | [K-u] | | Notification display time | fixed 9 s, queued while the user is inactive (Win7-era guide) | [MS-notif] | | Time-sensitive notifications | only for events now or within an hour | [A-mn] | | Moving or auto-updating content | anything running over 5 s needs pause, stop or hide | [W-psh] | | Flashing | no more than 3 flashes per second | [W-3f] | | Hover or focus content | dismissible, hoverable, persistent | [W-hov] | ## 3. Anti-patterns ### Popovers and flyouts - Mixing many control types in one popover, or adding unneeded close/done buttons. [G-pop] [A-pop] - Opening several popovers at once, or a cascade of popovers. [A-pop] - *Disagreement:* Microsoft allows nested flyouts. [MS-fly] - Drawing anything except an alert over a popover. [A-pop] - Requiring two clicks to switch from one bar popover to another. [A-pop] - Showing warnings in a popover. [A-pop] - Losing work when a popover closes because the user clicked outside it. [A-pop] - Resizing a popover without animation, so it looks like a new popover replaced it. [A-pop] - Using a flyout instead of a tooltip or context menu. [MS-fly] - Showing flyouts so often that they distract. [MS-dlg] ### Panels and bars - Crowding the bar with controls, or showing controls that don't apply in the current context. [G-hb] [K-sd] - Opening a dialog for anything other than a blocking decision, or opening one dialog from another. [K-gi] ### Tray and menu bar extras - A tray icon that is always visible; KDE says show it only for abnormal status, and opt-in. [K-st] - Forcing the icon into the bar; the user decides. [A-mb] [MS-tray] - Relying on the icon being present. [A-mb] - Opening a popover where a menu would do. [A-mb] - *Disagreement:* Microsoft's tray guide prefers a light-dismiss popup with the common settings. [MS-tray] - Icons that flash, animate for long periods, change rapidly, or are disabled. [MS-tray] - A left click that does nothing. [MS-tray] - An "About" item in the tray menu. [MS-tray] - Interactive-looking elements inside tooltips. [MS-tray] - Using the tray for status that is irrelevant to the user, such as disk activity. [MS-tray] ### Notifications, toasts and OSDs - Notifying for routine success, ignorable events, advertising, or real-time data such as progress. [K-st] [MS-notif] - Repeating notifications about the same thing. [A-notif] - Error messages delivered as notifications; use an alert instead. [A-notif] - Notifications that tell the user to go do something elsewhere. [A-notif] - Making a notification the only place information appears. [G-notif] - Notification buttons that duplicate the default action. [G-notif] - Inflated urgency. [A-mn] - OSDs for changes the user didn't start. [K-st] - Toasts used for ongoing state, or toasts that always carry a button. [G-toast] ### Gaps - **Fetched only after retry:** the WCAG pages returned 403 through the web tool; I read the normative text directly over HTTP from the W3C Understanding pages instead. - **Not read:** - KDE Plasma widget/applet guidance: the KDE HIG has no applet page, and I didn't read `/docs/plasma/widget/`. - Windows 11 Quick Settings: no design page found. - GNOME's full keyboard reference table. - Apple's keyboard page. - WCAG 1.4.1 (use of colour) and 2.2.1 (timing adjustable). - **Partly read:** the GNOME menus, Apple notifications and Microsoft flyout pages were cut off by the fetch character limit; the GNOME keyboard page's standard-keys table was also truncated. - **Dated source:** the Microsoft Win7 UX guide is labelled outdated by Microsoft but still applies in principle. ## Sources - G-pr https://developer.gnome.org/hig/principles.html - G-pop …/hig/patterns/containers/popovers.html - G-menu …/patterns/controls/menus.html - G-btn …/patterns/controls/buttons.html - G-sw …/patterns/controls/switches.html - G-notif …/patterns/feedback/notifications.html - G-toast …/patterns/feedback/toasts.html - G-tt …/patterns/feedback/tooltips.html - G-hb …/patterns/containers/header-bars.html - G-a11y …/guidelines/accessibility.html - G-ws …/guidelines/writing-style.html - G-kb …/guidelines/keyboard.html - G-pt …/guidelines/pointer-touch.html - G-sty …/guidelines/ui-styling.html - K-ia https://develop.kde.org/hig/ - K-sd …/hig/simple_by_default/ - K-pw …/powerful_when_needed/ - K-ln …/layout_and_nav/ - K-gi …/getting_input/ - K-st …/status_changes/ - K-tl …/text_and_labels/ - K-ic …/icons/ - K-a11y …/accessibility/ - K-u https://api.kde.org/qml-org-kde-kirigami-platform-units.html - A-mb https://developer.apple.com/design/human-interface-guidelines/the-menu-bar - A-pop …/popovers - A-notif …/notifications - A-mn …/managing-notifications - A-a11y …/accessibility - A-mo …/motion - MS-fly https://learn.microsoft.com/en-us/windows/apps/develop/ui/controls/dialogs-and-flyouts/flyouts - MS-dlg …/dialogs-and-flyouts/ - MS-un https://learn.microsoft.com/en-us/windows/apps/develop/notifications/app-notifications/app-notifications-ux-guidance - MS-tray https://learn.microsoft.com/en-us/windows/win32/uxguide/winenv-notification - MS-notif https://learn.microsoft.com/en-us/windows/win32/uxguide/mess-notif - MS-tgt https://learn.microsoft.com/en-us/windows/apps/develop/input/guidelines-for-targeting - MS-tim https://learn.microsoft.com/en-us/windows/apps/design/motion/timing-and-easing - NN https://www.nngroup.com/articles/ten-usability-heuristics/ - W-cm https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html - W-ntc …/non-text-contrast.html - W-fv …/focus-visible.html - W-fa …/focus-appearance.html - W-fno …/focus-not-obscured-minimum.html - W-ts …/target-size-minimum.html - W-anim …/animation-from-interactions.html - W-psh …/pause-stop-hide.html - W-3f …/three-flashes-or-below-threshold.html - W-hov …/content-on-hover-or-focus.html