Instructions file CodexOpenCode
AGENTS.md instructions for hanthor/gnome-gui-spec: This repository IS the instruction set. Start at SKILL.md and follow its routing table — read only the one or two files your task needs.
Skill Claude CodeCodex
Authoritative resource for building, auditing, and improving GNOME GTK4/libadwaita apps. Design tokens, 42-widget component library, 21 pattern skills, 47 mirrored HIG pages, 34 real-app audits, and lint scripts. Use when building a GNOME app, adding GNOME GUI features, auditing HIG compliance, packaging for…
Skill Claude CodeCodex
Add a standard AdwAboutDialog wired to app metadata, plus the AppStream metainfo file it should share data with. Use when adding an About entry, release notes, credits, or preparing app metadata.
Skill Claude CodeCodex
Make a GTK4/libadwaita app accessible — accessible labels and roles, tooltips on icon-only buttons, keyboard navigation, contrast, and testing with Orca/Accerciser. Use when fixing a11y issues or running the accessibility category of a HIG audit.
Skill Claude CodeCodex
Responsive GNOME layouts: AdwBreakpoint conditions, BreakpointBin, MultiLayoutView, BottomSheet, narrow/wide layout swaps. Use when making an app work on phones or narrow windows.
Skill Claude CodeCodex
Onboarding tour with AdwCarousel and navigation dots, skippable welcome screens. Use when adding a first-run tour or feature showcase to a GNOME app.
Skill Claude CodeCodex
Implement GNOME's 4-tier destructive-action pattern: undo toasts instead of confirmation dialogs, AdwAlertDialog for irreversible actions. Use when adding delete, remove, clear, or other destructive actions.
Skill Claude CodeCodex
Loading, empty, and error states with AdwStatusPage and AdwSpinner — placeholder icons, titles, action buttons. Use when an app view can be empty, loading, or failed.
Skill Claude CodeCodex
Package a GNOME app as a Flatpak — manifest for the GNOME runtime, sandbox permissions, build/run/test loop, and Flathub submission checklist. Use when packaging, distributing, or preparing a GNOME app for Flathub.
Skill Claude CodeCodex
GitHub Actions CI/CD for GNOME apps — build+test with GTK4/libadwaita on runners, Flatpak builds via flatpak-github-actions, attaching .flatpak bundles to releases, optional OCI publishing to GHCR, and headless GUI smoke tests with Xvfb/AT-SPI. Use when setting up CI, release automation, or GUI testing for a GTK app.
Skill Claude CodeCodex
Wire up GSettings: schema authoring, key naming, settings binding to widgets, window state persistence. Use when persisting app settings or window size/state in a GNOME app.
Skill Claude CodeCodex
AdwHeaderBar layout rules: button placement, flat/icon-only buttons, tooltips, title widgets, split buttons. Use when designing or fixing a GNOME app's header bar.
Skill Claude CodeCodex
Audit a GTK4/libadwaita app for GNOME HIG compliance across 12 categories (text, icons, layout, shortcuts, accessibility, color, dialogs, responsiveness, CSS, GSettings, i18n), then fix violations category by category. Use when asked to audit, review, polish, or "make HIG-compliant" a GNOME app, or before a…
Skill Claude CodeCodex
Build-system setup for GNOME apps per language: Python/PyGObject, Rust/gtk-rs, C, Vala, JavaScript/GJS — meson files, blueprint-compiler wiring, Flatpak manifests. Use when choosing a language for a GNOME app or setting up its build.
Skill Claude CodeCodex
Add a standard GNOME preferences dialog (AdwPreferencesDialog) with Ctrl+comma shortcut, PreferencesPage/Group rows, and GSettings bindings. Use when adding settings or preferences UI to a GNOME app.
Skill Claude CodeCodex
Scaffold a minimal GNOME-compliant GTK4/libadwaita app from scratch — window, header bar, ViewSwitcher, adaptive breakpoint, menu, preferences, GSettings schema, desktop entry, meson. Use when starting a new GNOME app or when the user asks for a GNOME app template.
Skill Claude CodeCodex
Exclusive-choice UI: CheckButton radio groups in list rows, when to use them vs ComboRow vs ToggleGroup. Use when presenting mutually exclusive options in GNOME preferences or dialogs.
Skill Claude CodeCodex
Add search to a GNOME app — header-bar search button toggling a GtkSearchBar with SearchEntry, live filtering, Ctrl+F, and empty "no results" state. Use when adding search or filtering to lists or content views.
Skill Claude CodeCodex
Add a Keyboard Shortcuts help window (Ctrl+question) listing all app accelerators, plus the standard GNOME accelerator set. Use when wiring keyboard shortcuts or the Keyboard Shortcuts menu item.
Skill Claude CodeCodex
Sidebar layouts: AdwNavigationSplitView vs OverlaySplitView, sidebar widths, collapse breakpoints, navigation-sidebar styling. Use when adding a sidebar or master-detail layout to a GNOME app.
Skill Claude CodeCodex
Multi-document tabs with AdwTabView/TabBar/TabOverview — tab menus, pinning, keyboard shortcuts. Use when an app opens multiple documents or sessions in tabs.
Skill Claude CodeCodex
In-app notifications: AdwToast/ToastOverlay with undo buttons, when to use toasts vs banners vs dialogs. Use when giving feedback after user actions in a GNOME app.
Skill Claude CodeCodex
Flat page switching with AdwViewStack + AdwViewSwitcher (3-5 top-level views) and ViewSwitcherBar on narrow widths. Use when an app needs tabs/views in the header bar.
Skill Claude CodeCodex
Sequential multi-step setup flow (assistant/wizard) with AdwNavigationView, Back/Forward navigation, progress indication. Use when building onboarding or setup flows with ordered steps.