Designing GNOME UI Skill

Designing GNOME UI

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

Core principle: No UI code without design decisions. Pattern selection and quality verification happen before implementation.

Quality layers: Compliance (follows HIG) → Polish (feels premium) → Rigor (handles edge cases)

Companion skill: For app architecture (lifecycle, threading, GSettings, actions, packaging), use developing-gtk-apps.

What's New (libadwaita 1.6-1.8)

| Need | Widget/API | Notes | |------|------------|-------| | Exclusive toggles (view mode) | AdwToggleGroup | Replaces multiple GtkToggleButton | | Loading indicator | AdwSpinner | Works with animations disabled | | Persistent bottom controls | AdwBottomSheet | Music player, persistent actions | | Wrapping content (tags) | AdwWrapBox | Auto-wraps like text | | Inline view switching | AdwInlineViewSwitcher | For cards, sidebars | | Keyboard shortcuts | AdwShortcutsDialog | Replaces deprecated GtkShortcutsWindow | | System accent color | Automatic | Apps follow desktop preference via portal | | System fonts | AdwStyleManager | Access monospace/document fonts |

Deprecations: .dim-label → use .dimmed class

# AdwToggleGroup - view mode switching
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)  # Show sheet
window.set_content(bottom_sheet)

# AdwWrapBox - tag display
wrap_box = Adw.WrapBox(spacing=6)
for tag in ["Python", "GTK", "GNOME", "libadwaita"]:
    chip = Gtk.Label(label=tag)
    chip.add_css_class("chip")  # Custom styling
    wrap_box.append(chip)

# System fonts (1.7+) - for code editors, document views
style_manager = Adw.StyleManager.get_default()
mono_font = style_manager.get_monospace_font_name()  # User's preferred mono font
doc_font = style_manager.get_document_font_name()    # User's preferred document font
# Also available as CSS: --monospace-font-family, --document-font-family

The Process

digraph gnome_ui_process {
    rankdir=LR;
    node [shape=box];

    "UI Task" -> "1. Context" -> "2. Patterns" -> "3. Details" -> "4. Checklist" -> "Implement";
    "4. Checklist" -> "2. Patterns" [label="issues" style=dashed];
}

Context: User goal, app type, constraints (screen size, input)
Patterns: Select containers, navigation, controls, feedback
Details: Typography, spacing, icons, writing style
Checklist: Verify compliance, polish, rigor before code

Container Selection

digraph containers {
    rankdir=TB;
    node [shape=box];

    "Building what?" [shape=diamond];
    "AdwApplicationWindow + HeaderBar" [style=filled fillcolor=lightgreen];
    "AdwPreferencesWindow" [style=filled fillcolor=lightgreen];
    "AdwDialog" [style=filled fillcolor=lightgreen];

    "Building what?" -> "AdwApplicationWindow + HeaderBar" [label="main window"];
    "Building what?" -> "AdwPreferencesWindow" [label="settings"];
    "Building what?" -> "AdwDialog" [label="modal action"];
}

| Scenario | Default | Notes | |----------|---------|-------| | App window | AdwApplicationWindow + AdwHeaderBar | Remember user size, start ~800x600 | | Settings | AdwPreferencesWindow | Handles groups, search, subpages | | List of items | AdwPreferencesGroup with rows | Boxed list style | | Primary action | Single button, header bar end | suggested-action class if emphasized | | Destructive action | destructive-action class | Requires undo or confirmation |

Navigation Selection

| Structure | Default Pattern | |-----------|-----------------| | Single view | None needed | | 2-4 views | AdwViewSwitcher in header bar | | Many/dynamic views | AdwNavigationSplitView (sidebar) | | Hierarchical | AdwNavigationView (drill-down) |

Control Defaults

| Need | Default | Avoid | |------|---------|-------| | On/Off | AdwSwitchRow | Checkbox for settings | | Choose one (few) | AdwComboRow | Radio buttons outside dialogs | | Choose one (many) | AdwComboRow + search | Long unsearchable dropdowns | | Text input | AdwEntryRow | Bare GtkEntry | | Multiline text | GtkTextView + card class | Bare unstyled text view | | Number | AdwSpinRow | Text entry for numbers | | Date | GtkCalendar in popover | Text entry for dates | | Action in list | AdwActionRow + suffix button | Multiple buttons per row | | Search | GtkSearchBar + toggle button | Always-visible search box |

Search Bar Pattern

# Search bar slides down from header, toggle with button or Ctrl+F
search_bar = Gtk.SearchBar()
search_entry = Gtk.SearchEntry()
search_bar.set_child(search_entry)
search_bar.connect_entry(search_entry)
search_bar.set_key_capture_widget(window)  # Type-to-search

# Toggle button in header bar
search_btn = Gtk.ToggleButton(icon_name="system-search-symbolic")
search_btn.set_tooltip_text("Search")
search_bar.bind_property("search-mode-enabled", search_btn, "active",
    GObject.BindingFlags.BIDIRECTIONAL | GObject.BindingFlags.SYNC_CREATE)
header.pack_end(search_btn)
toolbar_view.add_top_bar(search_bar)

Form Validation Pattern

# Use error CSS class on invalid fields
def validate_entry(row):
    text = row.get_text()
    if not text or len(text) < 3:
        row.add_css_class("error")
        row.set_tooltip_text("Name must be at least 3 characters")
        return False
    row.remove_css_class("error")
    row.set_tooltip_text("")
    return True

name_row.connect("changed", lambda r: validate_entry(r))

Validation timing: On change for format checks, on focus-out for expensive checks, on submit for final validation.

List Widget Selection

| Content | Widget | Why | |---------|--------|-----| | Settings/preferences | AdwPreferencesGroup | Boxed list style, handles rows | | Navigation list (sidebar) | GtkListBox | Selection support, activatable rows | | Large/dynamic data | GtkListView | Virtual scrolling, performance | | Grid of items | GtkGridView | Thumbnail grids, icon views |

Selection modes: Use Gtk.SingleSelection for navigation, Gtk.MultiSelection for bulk actions. Toggle selection mode with header bar button + action bar for bulk operations. See reference for code patterns.

Iconography

Rules:

Symbolic icons only (outline, monochrome) - never full-color in UI
Source from GNOME Icon Library (icon-library app)
Header bar: icon-only buttons, always add tooltips
Naming: action-object-symbolic (e.g., list-add-symbolic)
Dynamic icons: Update icon name based on state (e.g., user-trash-symbolic → user-trash-full-symbolic)

| Action | Icon | |--------|------| | Add/New | list-add-symbolic | | Delete | user-trash-symbolic | | Settings | emblem-system-symbolic | | Menu | open-menu-symbolic | | Search | system-search-symbolic | | Edit | document-edit-symbolic | | Back | go-previous-symbolic | | Drill-down | go-next-symbolic | | Sync | emblem-synchronizing-symbolic | | Offline | network-offline-symbolic | | Warning | dialog-warning-symbolic | | Error | dialog-error-symbolic | | Select mode | selection-mode-symbolic | | Check/Done | emblem-ok-symbolic | | Close | window-close-symbolic | | Refresh | view-refresh-symbolic |

Feedback Selection

digraph feedback {
    rankdir=TB;
    node [shape=box];

    "What happened?" [shape=diamond];
    "Transient or persistent?" [shape=diamond];
    "AdwToast" [style=filled fillcolor=lightgreen label="AdwToast (default)"];
    "AdwBanner" [style=filled fillcolor=lightyellow];
    "AdwDialog" [style=filled fillcolor=lightpink];
    "Progress/Spinner" [style=filled fillcolor=lightblue];

    "What happened?" -> "Transient or persistent?" [label="state/error"];
    "What happened?" -> "AdwDialog" [label="needs decision"];
    "What happened?" -> "Progress/Spinner" [label="ongoing operation"];
    "Transient or persistent?" -> "AdwToast" [label="transient event"];
    "Transient or persistent?" -> "AdwBanner" [label="persistent state"];
}

| Scenario | Default | Details | |----------|---------|---------| | Action done | AdwToast | Short message, optional undo | | Destructive action | AdwToast + undo | Prefer over confirmation dialog | | Error (recoverable) | AdwToast | Brief, auto-retry silently | | Error (blocking) | AdwDialog | Explain problem and required fix | | Persistent state | AdwBanner | Offline, degraded mode, auth required | | Needs decision | AdwDialog | Conflicts, irreversible actions | | Short wait (<5s) | AdwSpinner | No progress bar | | Long operation (>30s) | Progress bar + text | "13 of 42 processed" |

Error escalation: Toast (transient) → Banner (persists) → Dialog (requires action)

Network blip: Toast, auto-retry
Prolonged offline: Banner with "Retry" button
Auth expired: Dialog + Banner until resolved

Dialog rules:

Cancel button first (left), action button last (right)
Specific verbs ("Delete", "Save"), never "OK" or "Yes"
Destructive actions use destructive-action style

Context menus: Use GtkPopoverMenu for right-click actions (remove, rename, properties). Keep menus short; move complex actions to dialogs.

Empty State Pattern

# Show placeholder when list is empty
empty_state = Adw.StatusPage(
    icon_name="folder-symbolic",
    title="No Projects",
    description="Create a project to get started"
)
create_btn = Gtk.Button(label="Create Project")
create_btn.add_css_class("pill")
create_btn.add_css_class("suggested-action")
empty_state.set_child(create_btn)

# Use stack to switch between list and empty state
stack.add_named(list_view, "content")
stack.add_named(empty_state, "empty")
stack.set_visible_child_name("empty" if model.get_n_items() == 0 else "content")

Quality Checklist

Create TodoWrite items for each applicable check before implementing.

Layer 1: Compliance

[ ] Correct container type and header bar structure
[ ] Navigation pattern matches content structure
[ ] Standard widgets used (not custom where native exists)
[ ] Symbolic icons from GNOME Icon Library
[ ] Typography uses style classes (title-1, heading, body, caption)
[ ] Libadwaita spacing defaults (no custom margins)
[ ] Header capitalization for labels, sentence for descriptions

Layer 2: Polish

[ ] Clear visual hierarchy - important elements prominent
[ ] Controls and text properly aligned
[ ] Consistent patterns throughout
[ ] Empty states have placeholder page (icon + message + action)
[ ] Loading states show spinner/skeleton, never frozen UI
[ ] Smooth resize and view transitions
[ ] Comfortable density - not cramped, not sparse

Layer 3: Rigor

[ ] All controls keyboard-accessible (Tab, Enter, Space)
[ ] All elements have accessible names for screen readers
[ ] Works with high contrast (GTK_THEME=Adwaita:hc)
[ ] Works with 200% text scaling
[ ] Error handling for every input/action
[ ] Edge cases handled (empty lists, long text, missing data)
[ ] Destructive actions have undo where possible
[ ] Responsive: works at 800x600, adapts to larger

Accessibility Quick Check

# Test high contrast
GTK_THEME=Adwaita:hc ./myapp

# Test large text (set in GNOME Settings > Accessibility first)

# Test with screen reader
orca &
./myapp

# Keyboard-only: unplug mouse, navigate entire app with Tab/Enter/Space

Code: Set accessible labels for icon-only buttons and images:

button.update_property([Gtk.AccessibleProperty.LABEL], ["Add new item"])
image.update_property([Gtk.AccessibleProperty.LABEL], ["Project thumbnail"])

Red Flags - STOP

Custom styling where libadwaita has a pattern
Multiple "suggested" or "destructive" buttons per view
Confirmation dialogs for reversible actions (use undo)
Text over images or textured backgrounds
Non-GNOME icons without strong justification
Missing tooltips on icon-only header bar buttons
Generic labels ("OK", "Yes", "No", "Submit")
Frozen UI during operations (missing loading states)

Non-GTK Apps (Qt/PySide6)

When styling Qt apps for GNOME:

Use Adwaita-qt or manual QSS matching Adwaita colors
Follow same patterns conceptually (header bar → toolbar, etc.)
Match spacing, typography scale, and icon style
Test alongside native GNOME apps for consistency

Reference Files

| Need | File | |------|------| | Basic UI patterns | gnome-hig-reference.md | | Advanced patterns | gnome-advanced-patterns.md |

gnome-hig-reference.md - Read for most apps:

Container, navigation, control, feedback patterns with code
Search bar, form validation, filter models, grid views, selection modes
File chooser dialogs, dark/light mode, responsive breakpoints
Primary menu structure, About dialog, Shortcuts window
Typography, writing style, CSS color variables, common mistakes
Accessibility testing commands (high contrast, screen reader)
Phone/tablet breakpoints, adaptive layouts

gnome-advanced-patterns.md - Read when building:

Drag & drop (reordering, file drops, cross-widget DnD)
Undo/Redo (command pattern, history management)
Tabs (AdwTabView, multi-document apps)
System notifications (GNotification vs Toast)
Media display (image viewers, video controls, pinch-to-zoom gestures)
Split/Paned views (resizable panels)
Welcome/Onboarding (first-run, feature callouts)
Popovers (tool palettes, color pickers)
Keyboard shortcuts (mnemonics, shortcut controllers)

Agent Skills: Designing GNOME UI

Install this agent skill to your local

Skill Files