Designing GNOME UI

Design GNOME UIs that are HIG-compliant, polished, and user-centered.

Core principle: No UI code without design decisions. Pattern selection happens before implementation.

Companion skill: For app architecture (lifecycle, threading, GSettings, actions, list-model/factory code, packaging), use developing-gtk-apps. Snippets in this skill are Python (PyGObject) and illustrate which widget and how it fits together; for Vala or Rust syntax, use that skill's language branch files.

Subagents: a subagent given UI work loads no skills on its own — its prompt must tell it to invoke designing-gnome-ui (and developing-gtk-apps for plumbing).

What's Current (libadwaita 1.9, GTK 4.22)

Training data reaches for APIs that are now deprecated. Write the current column, every time:

Why the *Window → *Dialog shift: AdwDialog (1.5) presents adaptively — a centered dialog on desktop, a bottom sheet on narrow/mobile screens — and attaches with dialog.present(parent) instead of transient_for. Every window-based dialog type was retired in its favor; when you meet a new Adw*Window/Adw*Dialog pair, the *Dialog one is current.

Widgets newer than training data (verify the API, don't guess it):

# AdwToggleGroup - view mode switching (note: Adw.Toggle objects, not buttons)
toggle_group = Adw.ToggleGroup()
toggle_group.add(Adw.Toggle(icon_name="view-grid-symbolic", name="grid"))
toggle_group.add(Adw.Toggle(icon_name="view-list-symbolic", name="list"))
toggle_group.connect("notify::active-name", lambda g, p: set_view(g.get_active_name()))
header.pack_start(toggle_group)

# AdwBottomSheet - music player controls
bottom_sheet = Adw.BottomSheet()
bottom_sheet.set_content(main_content)
bottom_sheet.set_sheet(player_controls)
bottom_sheet.set_open(True)
window.set_content(bottom_sheet)

# AdwWrapBox - tag display (child_spacing/line_spacing, NOT spacing)
wrap_box = Adw.WrapBox(child_spacing=6, line_spacing=6)
for tag in ["Python", "GTK", "GNOME"]:
    wrap_box.append(Gtk.Label(label=tag))

Verify, Then Claim

A widget or version claim is confirmed by the installed introspection data, not by memory: /usr/share/gir-1.0/Adw-1.gir and Gtk-4.0.gir carry version="1.x" (since) and deprecated-version="1.x" attributes on each class — parse them (attributes span multiple lines; plain grep on the class name misses them). A CSS class is confirmed by the shipped stylesheet: gresource extract /usr/lib/x86_64-linux-gnu/libadwaita-1.so.0 /org/gnome/Adwaita/styles/default-light-yaru-default.css (path varies by distro patching; gresource list shows what's there). Presence in the stylesheet proves a class exists; only the GIR/docs settle whether it is current or a deprecated alias (.dim-label still ships beside .dimmed). An icon name is confirmed by the installed theme:

find /usr/share/icons/Adwaita -name 'NAME-symbolic.svg' | head -1

Some icons ship inside GTK/libadwaita gresources, so an empty result is a strong signal rather than proof — gtk4-icon-browser is the exhaustive check.

Container Selection

Navigation Selection

Adaptivity comes from AdwBreakpoint setters on the window (max-width: 600sp → set collapsed), never from swapping widget trees by hand.

Control Defaults

List Widget Selection

Selection: Gtk.SingleSelection for navigation, Gtk.MultiSelection behind an explicit selection mode (header toggle + GtkActionBar for bulk actions). Factory/model code lives in developing-gtk-apps.

Iconography

Symbolic icons only (-symbolic, monochrome). Header bar buttons are icon-only with tooltips. Icons beyond the system theme (browse the GNOME Icon Library app) must be bundled as resources — a bare icon_name string only resolves from the installed theme.

Plausible-sounding names are routinely absent (chain-link-, attach-, dock-left-, view-sidebar-start-, emblem-ok-symbolic all fail on this system) — run any name not in this table through the find check in "Verify, Then Claim" before using it.

Designing Against Platform Limits

Some controls cannot work on GNOME Wayland without a companion shell extension: positioning a window, keeping it above others, hiding it from the dock, grabbing a global shortcut. The design question is what the UI does when the capability is absent — and the answer is never "look like it worked".

pin_button.set_sensitive(available)
pin_button.set_tooltip_text(
    "Keep on Top" if available else
    "Keep on Top needs the … extension — Wayland does not let apps raise "
    "their own windows")

Architecture for this lives in developing-gtk-apps (gnome-shell-companion-reference.md).

Feedback Selection

Escalation: Toast (transient) → Banner (persists) → Dialog (requires action).

Typography & Color

Style classes, not custom CSS: title-1…title-4, heading, body, caption, caption-heading, monospace, numeric, dimmed — and card, pill, flat, boxed-list, navigation-sidebar, toolbar, osd, error/warning/success (all present in the 1.9 stylesheet). Colors via var(--accent-color)-style variables only — full table in gnome-hig-reference.md.

Writing: header capitalization for buttons/menus/titles, sentence capitalization for descriptions/switch labels, no trailing periods, verbs not "OK". Details in gnome-hig-reference.md.

Definition of Done

The design is implemented when the assembled window has been rendered and looked at, and every line checks out against the code.

Render first. Launch the app (or a screenshot harness — developing-gtk-apps has the run/render plumbing) and inspect the actual window before calling anything done; compiling and passing tests draw zero frames. Check in the render:

• Close/minimise/maximise are visible in every pane state — libadwaita puts window controls on the outermost header bar, so show-end-title-buttons(false) on the wrong pane's header removes them entirely.
• The shortcuts dialog shows its accelerators — accelerator strings in code are plain <Control>n; XML-escaped entities (<Control>n) belong only inside .ui files.
• Sidebars/panes start in their intended state — set the split view's show-sidebar explicitly and bind the toggle from it; a sync_create bind from a default-inactive toggle hides the sidebar at launch.
• Content fills the window — a custom widget sets vexpand/hexpand on itself; a scroller expanding inside a 30px-tall parent means the parent lacks the flag.

Then line checks:

• Every Adw/Gtk class used appears non-deprecated in the installed GIR (the "What's Current" table has the swaps; anything unfamiliar goes through "Verify, Then Claim").
• Dialogs are AdwDialog subclasses presented with present(parent).
• Windows that can go narrow have AdwBreakpoints driving collapsed/switcher-bar changes.
• Colors and fonts come from var(--…) variables or style classes — zero hardcoded hex values.
• Text uses .dimmed, never .dim-label.
• Every icon-only button has tooltip_text; every icon name either exists in the Adwaita theme or is bundled.
• Each user action has exactly one affordance in the visible view — count across header bar, sidebar, and content together (a header +, a sidebar pill, and a content pill for the same "New" is two too many), and at most one empty state is on screen at a time.
• At most one suggested-action per view and destructive actions carry undo or an AdwAlertDialog confirmation.
• Controls for capabilities the platform may not provide are insensitive with an explanatory tooltip, never silently inert.
• Failures that lose user data raise a persistent banner, not a toast.
• Labels follow the capitalization table (header caps for buttons/menus, sentence caps for descriptions).

Non-GTK Apps (Qt/PySide6)

No maintained Adwaita Qt theme exists — style via QSS using the color variables above, map header bar → fixed toolbar, and reuse this skill's pattern/spacing/typography decisions. Test beside a native GNOME app.

Reference Files