AGENT SKILL

gtk-architect

Architect-level Linux desktop design — GTK4/libadwaita versus Qt, Wayland and X11 realities, Flatpak/Snap packaging and portals, distribution across diverse desktops, and the accessibility and theming expectations Linux users hold. Use when shipping a Linux desktop app.

License 许可
MIT
最近更新
2026-11-13
Stars
★ 0
Forks
0

01 前言 Front Matter

name
gtk-architect
license
MIT
metadata
{ "crusor-path": "desktop-architect/runtimes-architect/gtk-architect", "crusor-domain": "desktop-architect", "crusor-origin": "original", "crusor-sources": "docs.gtk.org/gtk4; developer.gnome.org/documentation; docs.flatpak.org; doc.qt.io/qt-6", "crusor-triggers": "gtk, gtk4, libadwaita, qt, linux desktop, flatpak, snap, appimage, wayland, x11", "crusor-verified-on": "2026-10-30" }
description
Architect-level Linux desktop design — GTK4/libadwaita versus Qt, Wayland and X11 realities, Flatpak/Snap packaging and portals, distribution across diverse desktops, and the accessibility and theming expectations Linux users hold. Use when shipping a Linux desktop app.
compatibility
GTK4/libadwaita, Qt6, Flatpak, Snap, AppImage

03 SKILL.md 正文

Linux Desktop Architect

Linux means one binary and a dozen desktops. The architecture question is which display stack, which packaging, and which conventions you target.

When to use

  • A native Linux app is required (performance, system integration, licensing).
  • Packaging for multiple distributions is in scope.
  • Wayland-specific behaviour matters (fractional scaling, input methods, screen capture).

When NOT to use

  • Cross-platform UI with a webview meets the need → Tauri/Electron.
  • The app is a CLI with a config file.

Decision 1 — Toolkit

Toolkit Fit
GTK4 + libadwaita GNOME-native feel, modern adaptive widgets
Qt 6 KDE-native, commercial apps, broad platform support
Electron/Tauri web skills, faster delivery, heavier or lighter footprint
  • GTK and Qt both work on any desktop, but native look comes from the toolkit matching the user's environment; libadwaita assumes GNOME conventions.
  • Respect the desktop's dark mode and accent colour APIs rather than hardcoding.

Decision 2 — Display server

  • Wayland is the default on modern desktops; X11 remains on older setups.
  • Test on both: global shortcuts, screen capture, window positioning, and tray icons behave differently.
  • Fractional scaling and input method (IBus/Fcitx) support decide whether text entry works for non-Latin users.
  • Avoid APIs that only exist under X11 unless you ship a documented fallback.

Decision 3 — Packaging

Format Notes
Flatpak sandboxed, portals, Flathub distribution
Snap sandboxed, Ubuntu-centric, automatic updates
AppImage portable, no sandbox, manual updates
distro packages (deb/rpm) native integration, maintenance burden
  • Flatpak is the default recommendation for broad reach; portals replace direct filesystem access.
  • Sandboxing changes file access: use XDG portals (xdg-desktop-portal) for file chooser, notifications, and opening URIs.
  • Ship the runtime dependencies; do not assume the user's distro versions.

Decision 4 — Desktop integration

  • .desktop entry, icon at multiple sizes, AppStream metadata for store listings.
  • Notifications via the freedesktop spec; actions where supported.
  • Respect the user's theme, fonts, and scaling — do not force a look.
  • Accessibility: GTK/Qt provide the AT-SPI bridge; test with Orca.

Decision 5 — Updates

  • Flatpak/Snap update automatically; document the channel and rollback.
  • AppImage and distro packages need your own update path or none at all — say which.
  • Long-term support: track the runtime (e.g. GNOME runtime) lifecycle.

Failure modes at scale

  • Sandboxed Flatpak with direct ~/.config writes; the file silently goes to the sandbox.
  • Tray icon that only works under X11; missing on GNOME Wayland.
  • Hardcoded light theme; unreadable in dark mode.
  • AppImage requiring a library the user's distro does not ship.
  • Custom window decorations that break under tiling window managers.

Verification receipts

  1. Toolkit and packaging decision with the target desktops listed.
  2. Test pass on GNOME Wayland, KDE Plasma, and one X11 session.
  3. Portal-based file access verified inside the Flatpak sandbox.
  4. Dark mode, scaling, and non-Latin input tested.
  5. AppStream metadata and desktop entry validated by the packaging tools.

04 同仓库更多 Skills

SriAkhilSJ
SriAkhilSJ/PulseAIRepo

interaction-patterns-architect

Architect-level interaction design in code — choosing established patterns over invented ones, feedback and latency behaviour, destructive-action safeguards, navigation and overlay conventions, and the state model behind every interactive surface. Use when a screen has to behave, not just look.

★ 0
SriAkhilSJ
SriAkhilSJ/PulseAIRepo

design-system-ops-architect

Architect-level operation of a design system in code — token pipelines and versioning, component API and variant policy, the catalogue as the contract, adoption metrics, and the governance that stops a system from forking into three. Use when a component library must survive several teams.

★ 0
SriAkhilSJ
SriAkhilSJ/PulseAIRepo

design-handoff-architect

Architect-level design handoff — what must be specified before implementation starts, tokens over raw values, responsive and content-limit contracts, state matrices, and the review loop that catches drift between design and code. Use when a design is about to become code.

★ 0
SriAkhilSJ
SriAkhilSJ/PulseAIRepo

content-microcopy-architect

Architect-level UI content — where strings live, voice and terminology consistency, error and empty-state copy as part of the interface, translation-ready authoring, and the content model a product needs before it multiplies screens. Use when the words in the interface matter as much as the pixels.

★ 0
SriAkhilSJ
SriAkhilSJ/PulseAIRepo

ui-ux-implementation-architect

Architect-level direction for turning a design into working UI — the handoff contract, component ownership versus screen-level layout, interaction and state conventions, design QA gates, and the review habits that keep an implementation faithful without frozen pixels. Use before any specific UI implementation skill.

★ 0
SriAkhilSJ
SriAkhilSJ/PulseAIRepo

test-strategy-architect

Architect-level test strategy — allocating assertions across unit, integration, contract and end-to-end layers, designing for testability through dependency boundaries, fixture and data strategy, and the flake and coverage policies that keep a suite trustworthy. Use when defining how a codebase is tested.

★ 0