[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7AMTAYAWQVFH8N6M2V09VQJ":3,"skill-same:01M7AMTAYAWQVFH8N6M2V09VQJ":48},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":29,"ownerHtmlUrl":30,"ownerBlogUrl":31,"ownerDescription":32,"updatedAt":33,"install":34,"resources":47},"01M7AMTAYAWQVFH8N6M2V09VQJ","desktop-linux-platform",null,"Use when building or debugging a Linux desktop app. Covers why 'Linux' is not one platform (the stack, XDG base directories, .desktop files and app IDs), D-Bus as the desktop's nervous system, PipeWire, the honest accessibility picture, GTK4 + libadwaita, Qt 6, the other toolkits, and the Wayland transition — what Wayland takes away from X11 (global hotkeys, window positioning, screen capture) and what replaces it (portals, layer-shell).","the-vibey-project\u002Fvibey","the-vibey-project","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F329298758?v=4","01M7AJHGZ9722CTJ4JNQZVRH0Q","the vibey project","01M7AJHGZVMG2K7TGXQ6XFHVG3",5,"MIT","https:\u002F\u002Fgithub.com\u002Fthe-vibey-project\u002Fvibey\u002Fblob\u002Fdevelop\u002Fsrc\u002Fvibey_tools\u002Fskills\u002Fplugins\u002Fdesktop-apps-macos-linux\u002Fskills\u002Fdesktop-linux-platform\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: desktop-linux-platform\ndescription: \"Use when building or debugging a Linux desktop app. Covers why 'Linux' is not one platform (the stack, XDG base directories, .desktop files and app IDs), D-Bus as the desktop's nervous system, PipeWire, the honest accessibility picture, GTK4 + libadwaita, Qt 6, the other toolkits, and the Wayland transition — what Wayland takes away from X11 (global hotkeys, window positioning, screen capture) and what replaces it (portals, layer-shell).\"\n---\n\n# Desktop Apps (macOS & Linux): Linux Desktop Architecture, Toolkits, and Wayland\n\n> **Part 2 of 5** of the *Desktop Application Programming — macOS & Linux* reference (plugin `desktop-apps-macos-linux`), covering §4–§6. Sibling skills: `desktop-macos-platform` (§0–§3), `desktop-cross-platform-and-architecture` (§7–§9), `desktop-packaging-security-and-testing` (§10–§13), `desktop-reference` (§14–§20). Section numbers are shared across the set; a reference written as §N → `skill` points into that sibling skill.\n>\n> **Currency:** Verified August 2026. See §18 → `desktop-reference` for the currency snapshot and what goes stale first.\n\n> **How to read this.** Reference, not tutorial. Sections are independent. Three markers:\n> - **[UNIVERSAL]** — true of desktop software regardless of platform or toolkit.\n> - **[PLATFORM]** — specific to macOS or a particular Linux stack. Verify against current docs.\n> - **[CONTESTED]** — competent engineers disagree. Both cases given; don't adjudicate for the reader.\n>\n> **⚠️ GOTCHA** boxes mark the failure modes that actually cost people days.\n>\n> **The single most important framing in this document:** macOS is *one* platform with\n> *one* vendor, *one* HIG, and *one* blessed path. Linux is *not a platform* — it is a\n> family of overlapping conventions (freedesktop specs), two dominant toolkits, two\n> display protocols, three packaging formats, and a dozen desktop environments. Advice\n> that treats them symmetrically is wrong. Almost every difficulty in cross-platform\n> desktop work traces back to this asymmetry.\n\n---\n\n## §4. Linux Desktop Architecture\n\n### 4.1 The stack — and why \"Linux\" isn't one platform\n\n```\n┌─────────────────────────────────────────────────────────┐\n│ Your app: GTK4 \u002F Qt6 \u002F Electron \u002F Tauri \u002F SDL \u002F raw      │\n├─────────────────────────────────────────────────────────┤\n│ Toolkit + desktop integration: libadwaita \u002F KDE Frameworks│\n│ XDG Desktop Portals (D-Bus) ── the sandbox-safe API       │\n├─────────────────────────────────────────────────────────┤\n│ Session services: D-Bus, systemd --user, PipeWire,        │\n│ PolicyKit, UPower, NetworkManager, AT-SPI\u002FNewton (a11y)   │\n├─────────────────────────────────────────────────────────┤\n│ Display: Wayland compositor (Mutter\u002FKWin\u002Fwlroots\u002FCOSMIC)  │\n│          + XWayland for legacy X11 clients                │\n├─────────────────────────────────────────────────────────┤\n│ Graphics: Mesa, DRM\u002FKMS, GBM, Vulkan\u002FOpenGL               │\n├─────────────────────────────────────────────────────────┤\n│ Kernel: Linux, evdev\u002Flibinput, udev                       │\n└─────────────────────────────────────────────────────────┘\n```\n\n**[UNIVERSAL for Linux] The single most useful mental model: there is no vendor, only\nspecs.** freedesktop.org publishes the conventions; GNOME, KDE, and everyone else\nimplement them with varying completeness. Your app's job is to speak the specs, not to\ntarget a desktop environment. Apps that hardcode \"if GNOME then X\" age badly.\n\n**The specs you must actually know:**\n\n| Spec | What it governs | Practical impact |\n|---|---|---|\n| **XDG Base Directory** | Where files go | `$XDG_CONFIG_HOME` (`~\u002F.config`), `$XDG_DATA_HOME` (`~\u002F.local\u002Fshare`), `$XDG_CACHE_HOME` (`~\u002F.cache`), `$XDG_STATE_HOME` (`~\u002F.local\u002Fstate`), `$XDG_RUNTIME_DIR` (`\u002Frun\u002Fuser\u002FUID`, tmpfs, cleared at logout) |\n| **Desktop Entry** | `.desktop` files | How your app appears in menus\u002Flaunchers, handles MIME types, declares actions |\n| **Icon Theme** | Icon lookup | Ship SVG at `hicolor\u002Fscalable\u002Fapps\u002F\u003Capp-id>.svg`; never hardcode a path |\n| **AppStream (MetaInfo)** | App store metadata | Required by Flathub and by GNOME Software\u002FDiscover to show your app at all |\n| **MIME (shared-mime-info)** | File types | Custom formats need a MIME XML + magic bytes |\n| **Notifications** | `org.freedesktop.Notifications` | D-Bus, not a toolkit API |\n| **Autostart** | `~\u002F.config\u002Fautostart\u002F*.desktop` | Launch at login (or use a systemd user unit) |\n| **Secret Service** | Credential storage | `libsecret` → GNOME Keyring \u002F KWallet. **The Keychain equivalent.** |\n| **XDG Desktop Portal** | Sandboxed access to host resources | §12.3 → `desktop-packaging-security-and-testing` — increasingly the *only* way to do screen capture, and the *best* way to do file dialogs |\n| **Trash** | `~\u002F.local\u002Fshare\u002FTrash` | Don't `unlink()` user files; use `gio trash` semantics |\n\n```ini\n# \u002Fusr\u002Fshare\u002Fapplications\u002Fcom.example.MyApp.desktop  (or ~\u002F.local\u002Fshare\u002Fapplications)\n# The filename SHOULD equal your app ID — Wayland window matching depends on it.\n[Desktop Entry]\nType=Application\nName=My App\nComment=Short one-line description shown in launchers\nExec=myapp %U\nIcon=com.example.MyApp\nTerminal=false\nCategories=Utility;TextEditor;\nMimeType=text\u002Fplain;application\u002Fx-myformat;\nStartupNotify=true\nStartupWMClass=com.example.MyApp\nKeywords=notes;editor;markdown;\nX-GNOME-UsesNotifications=true\n\n[Desktop Action NewWindow]\nName=New Window\nExec=myapp --new-window\n```\n\n> **⚠️ GOTCHA — the app ID must match everywhere.** Your D-Bus name, `.desktop` filename,\n> icon filename, AppStream `\u003Cid>`, Flatpak app ID, GTK `Application` `application-id`, and\n> (critically) the Wayland `app_id` your toolkit reports must all be the same reverse-DNS\n> string. When they don't match, the symptom is: your window shows a generic icon in the\n> dock\u002Foverview, notifications aren't attributed to your app, and \"focus existing window\"\n> doesn't work. This is the single most common Linux packaging bug and it's invisible in\n> development.\n\n```xml\n\u003C!-- \u002Fusr\u002Fshare\u002Fmetainfo\u002Fcom.example.MyApp.metainfo.xml — required for Flathub -->\n\u003Ccomponent type=\"desktop-application\">\n  \u003Cid>com.example.MyApp\u003C\u002Fid>\n  \u003Cname>My App\u003C\u002Fname>\n  \u003Csummary>Edit notes quickly\u003C\u002Fsummary>\n  \u003Cmetadata_license>CC0-1.0\u003C\u002Fmetadata_license>\n  \u003Cproject_license>GPL-3.0-or-later\u003C\u002Fproject_license>\n  \u003Cdescription>\u003Cp>Longer description. Shown in software centres.\u003C\u002Fp>\u003C\u002Fdescription>\n  \u003Claunchable type=\"desktop-id\">com.example.MyApp.desktop\u003C\u002Flaunchable>\n  \u003Cscreenshots>\n    \u003Cscreenshot type=\"default\">\u003Cimage>https:\u002F\u002Fexample.com\u002Fshot1.png\u003C\u002Fimage>\u003C\u002Fscreenshot>\n  \u003C\u002Fscreenshots>\n  \u003Ccontent_rating type=\"oars-1.1\"\u002F>\n  \u003Creleases>\n    \u003Crelease version=\"1.2.0\" date=\"2026-08-01\">\n      \u003Cdescription>\u003Cp>Fixed the thing.\u003C\u002Fp>\u003C\u002Fdescription>\n    \u003C\u002Frelease>\n  \u003C\u002Freleases>\n  \u003Cbranding>\u003Ccolor type=\"primary\" scheme_preference=\"light\">#3584e4\u003C\u002Fcolor>\u003C\u002Fbranding>\n\u003C\u002Fcomponent>\n```\n\n### 4.2 D-Bus — the desktop's nervous system\n\nTwo buses: the **system bus** (root services: NetworkManager, UPower, logind, UDisks) and\nthe **session bus** (per-login: notifications, portals, your app, media players).\n\nAnatomy: **bus name** (`org.freedesktop.Notifications`) → **object path**\n(`\u002Forg\u002Ffreedesktop\u002FNotifications`) → **interface** (`org.freedesktop.Notifications`) →\n**method\u002Fsignal\u002Fproperty**.\n\n```bash\n# The three commands that make D-Bus tractable\nbusctl --user list                              # what's on the session bus\nbusctl --user introspect org.freedesktop.portal.Desktop \u002Forg\u002Ffreedesktop\u002Fportal\u002Fdesktop\ngdbus call --session --dest org.freedesktop.Notifications \\\n  --object-path \u002Forg\u002Ffreedesktop\u002FNotifications \\\n  --method org.freedesktop.Notifications.Notify \\\n  \"MyApp\" 0 \"dialog-information\" \"Title\" \"Body\" \"[]\" \"{}\" 5000\n```\n\n**Why your app should own a D-Bus name**: single-instance enforcement, `Activate`\u002F`Open`\nactions from the launcher, MPRIS media control, and the `org.freedesktop.Application`\ninterface. GTK's `GApplication` and Qt's `QDBusConnection` both give you this. It is also\nhow \"click the launcher again and raise the existing window\" works.\n\n**systemd user units** (`~\u002F.config\u002Fsystemd\u002Fuser\u002F`) are the modern way to run a background\nhelper, with socket activation, restart policy, and journal integration — the launchd\nequivalent, and preferable to a stray autostart `.desktop` for anything daemon-shaped.\n\n### 4.3 Audio\u002Fvideo: PipeWire\n\n**PipeWire has replaced PulseAudio and JACK** as the default on essentially all modern\ndistributions, handling both audio and video streams with low latency. What app developers\nneed:\n- Use a **high-level API** (GStreamer, libpulse compatibility, or PipeWire's own) rather\n  than talking to ALSA directly.\n- **Screen capture on Wayland goes through PipeWire** via the ScreenCast portal — there is\n  no `XShmGetImage` equivalent. This is the #1 porting surprise for screenshot, screen\n  recording, and video-conferencing apps.\n- **WirePlumber** is the session manager (policy); PipeWire is the transport. Bugs are\n  usually WirePlumber policy, not PipeWire.\n- PipeWire requires an active **D-Bus session bus**. In minimal WM setups without one,\n  everything silently fails — `dbus-run-session` is the fix.\n\n### 4.4 Accessibility on Linux — the honest picture\n\n**[UNIVERSAL] Build for accessibility from the start.** On Linux specifically:\n- **AT-SPI2** over D-Bus is the current accessibility API. **Orca** is the dominant screen\n  reader; **Odilia** is a newer entrant. GTK4 rewrote its a11y layer to talk to the AT-SPI\n  registry directly; KDE Plasma 6 added AT-SPI2 support in 6.0.\n- **AT-SPI has real architectural problems under Wayland and sandboxing**: the accessibility\n  tree is severed from the windowing system (so an AT can't verify an event came from the\n  focused app), and its \"chatty IPC\" requires many round trips, producing latency that\n  makes a screen reader unresponsive when the app is merely busy.\n- **Newton** is the in-progress Wayland-native replacement (built on AccessKit, with\n  Wayland protocol and Mutter\u002FGTK work), specifically designed so **Flatpak apps get\n  accessibility without punching a hole in the sandbox for the AT-SPI bus**. It is\n  experimental as of 2026 — track it, don't depend on it.\n- **The field is chronically under-resourced** — credible assessments put the number of\n  people working significantly on Linux a11y in the single digits historically. This means:\n  use your toolkit's standard widgets (which carry a11y for free), don't roll custom\n  controls without accessible implementations, and test with Orca yourself, because nobody\n  else will.\n\n---\n\n## §5. Linux UI Toolkits\n\n### 5.1 GTK4 + libadwaita\n\n**GTK 4** is the current major version (4.22.x as of mid-2026); **libadwaita** is the\nseparate library that supplies GNOME's design language: adaptive containers, modern\nwidgets (`AdwToastOverlay`, `AdwNavigationSplitView`, `AdwPreferencesPage`,\n`AdwStatusPage`), and the Adwaita style.\n\n**[CONTESTED] The GTK\u002Flibadwaita split is politically live.** GNOME's position: GTK is a\ngeneral toolkit; libadwaita is GNOME's design language layered on top, so GTK doesn't have\nto encode one desktop's opinions. Critics (notably from the Mint\u002FCinnamon direction, and\nmuch of the theming community): libadwaita apps resist system theming, look foreign\noutside GNOME, and the split effectively makes \"GTK app\" mean \"GNOME app.\" Both readings\nare defensible. **Practical consequence for you:** if you use libadwaita, your app will\nlook excellent on GNOME and slightly alien on KDE\u002FXFCE, and users *will* file issues about\ntheming. If you use plain GTK4 without libadwaita, you get more theme neutrality and less\npolish.\n\n```c\n\u002F* GTK4 + libadwaita, C. Note GtkApplication gives you D-Bus name ownership,\n   single-instance, and the org.freedesktop.Application interface for free. *\u002F\n#include \u003Cadwaita.h>\n\nstatic void on_activate(GtkApplication *app, gpointer user_data) {\n    GtkWidget *window = adw_application_window_new(app);\n    gtk_window_set_default_size(GTK_WINDOW(window), 900, 600);\n\n    GtkWidget *header = adw_header_bar_new();\n    GtkWidget *toast_overlay = adw_toast_overlay_new();\n    GtkWidget *content = gtk_box_new(GTK_ORIENTATION_VERTICAL, 0);\n\n    gtk_box_append(GTK_BOX(content), header);\n    gtk_box_append(GTK_BOX(content), toast_overlay);\n    adw_application_window_set_content(ADW_APPLICATION_WINDOW(window), content);\n    gtk_window_present(GTK_WINDOW(window));\n}\n\nint main(int argc, char **argv) {\n    \u002F* app id MUST match .desktop filename, icon name, and AppStream id *\u002F\n    AdwApplication *app = adw_application_new(\"com.example.MyApp\",\n                                              G_APPLICATION_HANDLES_OPEN);\n    g_signal_connect(app, \"activate\", G_CALLBACK(on_activate), NULL);\n    int status = g_application_run(G_APPLICATION(app), argc, argv);\n    g_object_unref(app);\n    return status;\n}\n```\n\n```rust\n\u002F\u002F GTK4 from Rust via gtk4-rs — increasingly the default for new GTK apps.\n\u002F\u002F Keep the gtk4 and libadwaita crate versions in lockstep; they're coupled.\nuse adw::prelude::*;\nuse adw::{Application, ApplicationWindow, HeaderBar};\nuse gtk::{Box as GtkBox, Orientation};\n\nfn main() -> glib::ExitCode {\n    let app = Application::builder()\n        .application_id(\"com.example.MyApp\")\n        .build();\n    app.connect_activate(|app| {\n        let content = GtkBox::new(Orientation::Vertical, 0);\n        content.append(&HeaderBar::new());\n        ApplicationWindow::builder()\n            .application(app)\n            .default_width(900).default_height(600)\n            .content(&content)\n            .build()\n            .present();\n    });\n    app.run()\n}\n```\nNote the trend: GNOME itself is migrating components to Rust (GNOME Disks' 51 rewrite\nmoved UI code and libgdu utilities to Rust talking to UDisks2 via `udisks-rs`). gtk4-rs is\nproduction-grade.\n\n**GTK4 concepts that trip people up:** the shift from GTK3's `pack_start`\u002Fcontainer model\nto explicit `append`\u002Fsingle-child layout; `GtkListView`\u002F`GtkColumnView` with\n`GListModel`+factories replacing `GtkTreeView`\u002F`GtkListStore`; CSS-based styling with GTK's\nown subset (not web CSS); `GtkEventController` replacing direct event handling; and\n`GtkBuilder`\u002F`.ui` XML plus **Blueprint** (a friendlier DSL that compiles to `.ui`) for\ndeclarative UI.\n\n**GTK5** is not imminent; treat GTK4 as the target for the foreseeable future.\n\n### 5.2 Qt 6\n\nCurrent: **Qt 6.11.x** (6.11.1, May 2026), on a ~6-month minor cadence. **Licensing is the\ndecision, not the technology:**\n- **LGPLv3** (most modules): free, but you must permit relinking — practically, dynamic\n  linking, or shipping object files. Some modules are **GPL-only** (notably Qt Charts,\n  Qt Data Visualization, and parts of the tooling), which will contaminate a proprietary\n  app if you use them.\n- **Commercial**: required for static linking in a closed-source product, and for LTS\n  patch releases. **LTS patch releases are commercial-only**; open-source users get LTS\n  branches treated as ordinary releases. Since 6.8.0, LTS support runs five years\n  (three before that).\n- The KDE Free Qt Foundation agreement is the backstop that keeps Qt open-source.\n\n**Qt Widgets vs Qt Quick\u002FQML [CONTESTED]:**\n- *Widgets*: mature, native-ish look, excellent for dense desktop tools (IDEs, CAD,\n  engineering software), C++ only, retained-mode. Not deprecated but not where new\n  investment goes.\n- *Quick\u002FQML*: declarative, GPU-accelerated, animation-friendly, JavaScript for logic,\n  designed for touch\u002Fembedded\u002Ffluid UI. Better for modern-looking apps; worse for dense\n  data grids and for teams that don't want a second language in the build.\n- Most desktop-tool companies still ship Widgets. Most new embedded\u002FHMI work is Quick.\n\n**PySide6** (official, LGPL) and **PyQt6** (Riverbank, GPL\u002Fcommercial) are the Python\nbindings; PySide6's licensing is friendlier for proprietary work. Note that free-threaded\n(GIL-less) Python support is still being worked out because a GIL-less runtime requires\nQt's own locking against the event loop.\n\n### 5.3 The rest\n\n| Toolkit | Status | Use when |\n|---|---|---|\n| **wxWidgets** | Alive, native controls per platform | You want genuinely native widgets and C++ |\n| **FLTK** | Alive, tiny | Minimal dependency footprint, simple tools |\n| **Tk\u002FTkinter** | Alive, ancient | Python scripts that need *a* window |\n| **Dear ImGui** | Thriving | Debug UIs, tools, game editors. Immediate-mode; not for consumer apps |\n| **EFL\u002FEnlightenment** | Niche | — |\n| **Motif\u002FXt** | Legacy | Maintaining 1990s software |\n\n---\n\n## §6. Wayland and X11\n\n### 6.1 The state of the transition (2026) — this changed recently\n\n- **GNOME removed X11 session support**: the X11 session was disabled by default in\n  GNOME 49, and the X11 backend code was **removed from Mutter**, with GNOME 50 (March\n  2026) shipping with no X11 code at all.\n- **KDE Plasma will be Wayland-only in Plasma 6.8**, expected **October 2026**; the Plasma\n  X11 session is supported into **early 2027** for 6.7 users. KDE's stated rationale: the\n  vast majority of Plasma users are already on Wayland and many distros already dropped\n  the X11 session independently.\n- Distros moved first in several cases: **Fedora 43** and **Ubuntu 25.10** already ship\n  without a GNOME X11 session.\n- Other desktops lag: **XFCE 4.20** added initial Wayland support (using labwc as a\n  stop-gap; xfwm4 is not yet a compositor); LXQt is further along than expected; Cinnamon\n  and MATE are behind.\n- **Xorg is not abandoned but its feature development is halted** — the same maintainers\n  fix security issues; new capability work happens in Wayland. **XLibre** is a fork with\n  more active development, of contested provenance, adopted by a small number of distros.\n- **X11 applications keep working** through **XWayland**. Dropping the X11 *session* is not\n  dropping X11 *apps*.\n\n**[UNIVERSAL, practical] Your app must work under Wayland in 2026.** Testing only on X11 is\nnow testing on a legacy path.\n\n### 6.2 What Wayland takes away, and what replaces it\n\nThis is the porting checklist. Under Wayland, a client **cannot**, by design:\n\n| X11 capability | Wayland status | Replacement |\n|---|---|---|\n| Read other windows' pixels (screenshot\u002Fcapture) | Forbidden | **ScreenCast portal** → PipeWire stream |\n| Global hotkeys | Not in core | **GlobalShortcuts portal**, or compositor-specific |\n| Set absolute window position | Forbidden | Compositor decides. `xdg-positioner` for popups only |\n| Query\u002Fset the pointer position | Forbidden | Relative motion only (pointer-constraints for games) |\n| Inject input into other apps | Forbidden | **RemoteDesktop portal**, **libEI** |\n| Read the clipboard without focus | Forbidden | `wl_data_device`, requires focus\u002Fuser action |\n| Override-redirect windows | No | `xdg-shell` roles: toplevel, popup; `layer-shell` for panels |\n| `XTest` automation | No | libEI \u002F portal, or compositor-specific test protocols |\n\n> **⚠️ GOTCHA — this list *is* the port.** If your app does screen capture, global\n> hotkeys, remote control, window positioning, or input automation, \"porting to Wayland\"\n> is not a rendering change — it's replacing those features with portal-mediated,\n> user-consenting equivalents that have different UX (a permission prompt, a picker\n> dialog). Budget for the UX redesign, not just the code.\n\n**Server-side vs client-side decorations (SSD\u002FCSD)** is a long-running friction point:\nGNOME\u002FMutter prefers CSD (the app draws its own titlebar — that's what a GTK `HeaderBar`\nis); KDE supports SSD via the `xdg-decoration` protocol. An app that assumes one gets\neither a double titlebar or none. Toolkits handle this; hand-rolled Wayland clients must\nnegotiate it.\n\n**Fractional scaling**: `wp_fractional_scale_v1` lets clients render at a fractional\nbuffer scale instead of rendering at 2× and downscaling (which is blurry). Modern GTK4\u002FQt6\nsupport it; older toolkits and XWayland clients often don't, which is why \"text is blurry\nat 125%\" is still a live complaint.\n\n**Remote desktop is the current genuine regression.** GNOME and KDE offer RDP-based remote\ndesktop; many third-party tools require someone physically present to accept the\nconnection because of Wayland's permission model. TigerVNC has shipped a Wayland-first VNC\nserver. If your product does unattended remote access, investigate carefully — this is not\nsolved to X11 parity.\n","# Desktop Apps (macOS & Linux): Linux Desktop Architecture, Toolkits, and Wayland\n\n> **Part 2 of 5** of the *Desktop Application Programming — macOS & Linux* reference (plugin `desktop-apps-macos-linux`), covering §4–§6. Sibling skills: `desktop-macos-platform` (§0–§3), `desktop-cross-platform-and-architecture` (§7–§9), `desktop-packaging-security-and-testing` (§10–§13), `desktop-reference` (§14–§20). Section numbers are shared across the set; a reference written as §N → `skill` points into that sibling skill.\n>\n> **Currency:** Verified August 2026. See §18 → `desktop-reference` for the currency snapshot and what goes stale first.\n\n> **How to read this.** Reference, not tutorial. Sections are independent. Three markers:\n> - **[UNIVERSAL]** — true of desktop software regardless of platform or toolkit.\n> - **[PLATFORM]** — specific to macOS or a particular Linux stack. Verify against current docs.\n> - **[CONTESTED]** — competent engineers disagree. Both cases given; don't adjudicate for the reader.\n>\n> **⚠️ GOTCHA** boxes mark the failure modes that actually cost people days.\n>\n> **The single most important framing in this document:** macOS is *one* platform with\n> *one* vendor, *one* HIG, and *one* blessed path. Linux is *not a platform* — it is a\n> family of overlapping conventions (freedesktop specs), two dominant toolkits, two\n> display protocols, three packaging formats, and a dozen desktop environments. Advice\n> that treats them symmetrically is wrong. Almost every difficulty in cross-platform\n> desktop work traces back to this asymmetry.\n\n---\n\n## §4. Linux Desktop Architecture\n\n### 4.1 The stack — and why \"Linux\" isn't one platform\n\n```\n┌─────────────────────────────────────────────────────────┐\n│ Your app: GTK4 \u002F Qt6 \u002F Electron \u002F Tauri \u002F SDL \u002F raw      │\n├─────────────────────────────────────────────────────────┤\n│ Toolkit + desktop integration: libadwaita \u002F KDE Frameworks│\n│ XDG Desktop Portals (D-Bus) ── the sandbox-safe API       │\n├─────────────────────────────────────────────────────────┤\n│ Session services: D-Bus, systemd --user, PipeWire,        │\n│ PolicyKit, UPower, NetworkManager, AT-SPI\u002FNewton (a11y)   │\n├─────────────────────────────────────────────────────────┤\n│ Display: Wayland compositor (Mutter\u002FKWin\u002Fwlroots\u002FCOSMIC)  │\n│          + XWayland for legacy X11 clients                │\n├─────────────────────────────────────────────────────────┤\n│ Graphics: Mesa, DRM\u002FKMS, GBM, Vulkan\u002FOpenGL               │\n├─────────────────────────────────────────────────────────┤\n│ Kernel: Linux, evdev\u002Flibinput, udev                       │\n└─────────────────────────────────────────────────────────┘\n```\n\n**[UNIVERSAL for Linux] The single most useful mental model: there is no vendor, only\nspecs.** freedesktop.org publishes the conventions; GNOME, KDE, and everyone else\nimplement them with varying completeness. Your app's job is to speak the specs, not to\ntarget a desktop environment. Apps that hardcode \"if GNOME then X\" age badly.\n\n**The specs you must actually know:**\n\n| Spec | What it governs | Practical impact |\n|---|---|---|\n| **XDG Base Directory** | Where files go | `$XDG_CONFIG_HOME` (`~\u002F.config`), `$XDG_DATA_HOME` (`~\u002F.local\u002Fshare`), `$XDG_CACHE_HOME` (`~\u002F.cache`), `$XDG_STATE_HOME` (`~\u002F.local\u002Fstate`), `$XDG_RUNTIME_DIR` (`\u002Frun\u002Fuser\u002FUID`, tmpfs, cleared at logout) |\n| **Desktop Entry** | `.desktop` files | How your app appears in menus\u002Flaunchers, handles MIME types, declares actions |\n| **Icon Theme** | Icon lookup | Ship SVG at `hicolor\u002Fscalable\u002Fapps\u002F\u003Capp-id>.svg`; never hardcode a path |\n| **AppStream (MetaInfo)** | App store metadata | Required by Flathub and by GNOME Software\u002FDiscover to show your app at all |\n| **MIME (shared-mime-info)** | File types | Custom formats need a MIME XML + magic bytes |\n| **Notifications** | `org.freedesktop.Notifications` | D-Bus, not a toolkit API |\n| **Autostart** | `~\u002F.config\u002Fautostart\u002F*.desktop` | Launch at login (or use a systemd user unit) |\n| **Secret Service** | Credential storage | `libsecret` → GNOME Keyring \u002F KWallet. **The Keychain equivalent.** |\n| **XDG Desktop Portal** | Sandboxed access to host resources | §12.3 → `desktop-packaging-security-and-testing` — increasingly the *only* way to do screen capture, and the *best* way to do file dialogs |\n| **Trash** | `~\u002F.local\u002Fshare\u002FTrash` | Don't `unlink()` user files; use `gio trash` semantics |\n\n```ini\n# \u002Fusr\u002Fshare\u002Fapplications\u002Fcom.example.MyApp.desktop  (or ~\u002F.local\u002Fshare\u002Fapplications)\n# The filename SHOULD equal your app ID — Wayland window matching depends on it.\n[Desktop Entry]\nType=Application\nName=My App\nComment=Short one-line description shown in launchers\nExec=myapp %U\nIcon=com.example.MyApp\nTerminal=false\nCategories=Utility;TextEditor;\nMimeType=text\u002Fplain;application\u002Fx-myformat;\nStartupNotify=true\nStartupWMClass=com.example.MyApp\nKeywords=notes;editor;markdown;\nX-GNOME-UsesNotifications=true\n\n[Desktop Action NewWindow]\nName=New Window\nExec=myapp --new-window\n```\n\n> **⚠️ GOTCHA — the app ID must match everywhere.** Your D-Bus name, `.desktop` filename,\n> icon filename, AppStream `\u003Cid>`, Flatpak app ID, GTK `Application` `application-id`, and\n> (critically) the Wayland `app_id` your toolkit reports must all be the same reverse-DNS\n> string. When they don't match, the symptom is: your window shows a generic icon in the\n> dock\u002Foverview, notifications aren't attributed to your app, and \"focus existing window\"\n> doesn't work. This is the single most common Linux packaging bug and it's invisible in\n> development.\n\n```xml\n\u003C!-- \u002Fusr\u002Fshare\u002Fmetainfo\u002Fcom.example.MyApp.metainfo.xml — required for Flathub -->\n\u003Ccomponent type=\"desktop-application\">\n  \u003Cid>com.example.MyApp\u003C\u002Fid>\n  \u003Cname>My App\u003C\u002Fname>\n  \u003Csummary>Edit notes quickly\u003C\u002Fsummary>\n  \u003Cmetadata_license>CC0-1.0\u003C\u002Fmetadata_license>\n  \u003Cproject_license>GPL-3.0-or-later\u003C\u002Fproject_license>\n  \u003Cdescription>\u003Cp>Longer description. Shown in software centres.\u003C\u002Fp>\u003C\u002Fdescription>\n  \u003Claunchable type=\"desktop-id\">com.example.MyApp.desktop\u003C\u002Flaunchable>\n  \u003Cscreenshots>\n    \u003Cscreenshot type=\"default\">\u003Cimage>https:\u002F\u002Fexample.com\u002Fshot1.png\u003C\u002Fimage>\u003C\u002Fscreenshot>\n  \u003C\u002Fscreenshots>\n  \u003Ccontent_rating type=\"oars-1.1\"\u002F>\n  \u003Creleases>\n    \u003Crelease version=\"1.2.0\" date=\"2026-08-01\">\n      \u003Cdescription>\u003Cp>Fixed the thing.\u003C\u002Fp>\u003C\u002Fdescription>\n    \u003C\u002Frelease>\n  \u003C\u002Freleases>\n  \u003Cbranding>\u003Ccolor type=\"primary\" scheme_preference=\"light\">#3584e4\u003C\u002Fcolor>\u003C\u002Fbranding>\n\u003C\u002Fcomponent>\n```\n\n### 4.2 D-Bus — the desktop's nervous system\n\nTwo buses: the **system bus** (root services: NetworkManager, UPower, logind, UDisks) and\nthe **session bus** (per-login: notifications, portals, your app, media players).\n\nAnatomy: **bus name** (`org.freedesktop.Notifications`) → **object path**\n(`\u002Forg\u002Ffreedesktop\u002FNotifications`) → **interface** (`org.freedesktop.Notifications`) →\n**method\u002Fsignal\u002Fproperty**.\n\n```bash\n# The three commands that make D-Bus tractable\nbusctl --user list                              # what's on the session bus\nbusctl --user introspect org.freedesktop.portal.Desktop \u002Forg\u002Ffreedesktop\u002Fportal\u002Fdesktop\ngdbus call --session --dest org.freedesktop.Notifications \\\n  --object-path \u002Forg\u002Ffreedesktop\u002FNotifications \\\n  --method org.freedesktop.Notifications.Notify \\\n  \"MyApp\" 0 \"dialog-information\" \"Title\" \"Body\" \"[]\" \"{}\" 5000\n```\n\n**Why your app should own a D-Bus name**: single-instance enforcement, `Activate`\u002F`Open`\nactions from the launcher, MPRIS media control, and the `org.freedesktop.Application`\ninterface. GTK's `GApplication` and Qt's `QDBusConnection` both give you this. It is also\nhow \"click the launcher again and raise the existing window\" works.\n\n**systemd user units** (`~\u002F.config\u002Fsystemd\u002Fuser\u002F`) are the modern way to run a background\nhelper, with socket activation, restart policy, and journal integration — the launchd\nequivalent, and preferable to a stray autostart `.desktop` for anything daemon-shaped.\n\n### 4.3 Audio\u002Fvideo: PipeWire\n\n**PipeWire has replaced PulseAudio and JACK** as the default on essentially all modern\ndistributions, handling both audio and video streams with low latency. What app developers\nneed:\n- Use a **high-level API** (GStreamer, libpulse compatibility, or PipeWire's own) rather\n  than talking to ALSA directly.\n- **Screen capture on Wayland goes through PipeWire** via the ScreenCast portal — there is\n  no `XShmGetImage` equivalent. This is the #1 porting surprise for screenshot, screen\n  recording, and video-conferencing apps.\n- **WirePlumber** is the session manager (policy); PipeWire is the transport. Bugs are\n  usually WirePlumber policy, not PipeWire.\n- PipeWire requires an active **D-Bus session bus**. In minimal WM setups without one,\n  everything silently fails — `dbus-run-session` is the fix.\n\n### 4.4 Accessibility on Linux — the honest picture\n\n**[UNIVERSAL] Build for accessibility from the start.** On Linux specifically:\n- **AT-SPI2** over D-Bus is the current accessibility API. **Orca** is the dominant screen\n  reader; **Odilia** is a newer entrant. GTK4 rewrote its a11y layer to talk to the AT-SPI\n  registry directly; KDE Plasma 6 added AT-SPI2 support in 6.0.\n- **AT-SPI has real architectural problems under Wayland and sandboxing**: the accessibility\n  tree is severed from the windowing system (so an AT can't verify an event came from the\n  focused app), and its \"chatty IPC\" requires many round trips, producing latency that\n  makes a screen reader unresponsive when the app is merely busy.\n- **Newton** is the in-progress Wayland-native replacement (built on AccessKit, with\n  Wayland protocol and Mutter\u002FGTK work), specifically designed so **Flatpak apps get\n  accessibility without punching a hole in the sandbox for the AT-SPI bus**. It is\n  experimental as of 2026 — track it, don't depend on it.\n- **The field is chronically under-resourced** — credible assessments put the number of\n  people working significantly on Linux a11y in the single digits historically. This means:\n  use your toolkit's standard widgets (which carry a11y for free), don't roll custom\n  controls without accessible implementations, and test with Orca yourself, because nobody\n  else will.\n\n---\n\n## §5. Linux UI Toolkits\n\n### 5.1 GTK4 + libadwaita\n\n**GTK 4** is the current major version (4.22.x as of mid-2026); **libadwaita** is the\nseparate library that supplies GNOME's design language: adaptive containers, modern\nwidgets (`AdwToastOverlay`, `AdwNavigationSplitView`, `AdwPreferencesPage`,\n`AdwStatusPage`), and the Adwaita style.\n\n**[CONTESTED] The GTK\u002Flibadwaita split is politically live.** GNOME's position: GTK is a\ngeneral toolkit; libadwaita is GNOME's design language layered on top, so GTK doesn't have\nto encode one desktop's opinions. Critics (notably from the Mint\u002FCinnamon direction, and\nmuch of the theming community): libadwaita apps resist system theming, look foreign\noutside GNOME, and the split effectively makes \"GTK app\" mean \"GNOME app.\" Both readings\nare defensible. **Practical consequence for you:** if you use libadwaita, your app will\nlook excellent on GNOME and slightly alien on KDE\u002FXFCE, and users *will* file issues about\ntheming. If you use plain GTK4 without libadwaita, you get more theme neutrality and less\npolish.\n\n```c\n\u002F* GTK4 + libadwaita, C. Note GtkApplication gives you D-Bus name ownership,\n   single-instance, and the org.freedesktop.Application interface for free. *\u002F\n#include \u003Cadwaita.h>\n\nstatic void on_activate(GtkApplication *app, gpointer user_data) {\n    GtkWidget *window = adw_application_window_new(app);\n    gtk_window_set_default_size(GTK_WINDOW(window), 900, 600);\n\n    GtkWidget *header = adw_header_bar_new();\n    GtkWidget *toast_overlay = adw_toast_overlay_new();\n    GtkWidget *content = gtk_box_new(GTK_ORIENTATION_VERTICAL, 0);\n\n    gtk_box_append(GTK_BOX(content), header);\n    gtk_box_append(GTK_BOX(content), toast_overlay);\n    adw_application_window_set_content(ADW_APPLICATION_WINDOW(window), content);\n    gtk_window_present(GTK_WINDOW(window));\n}\n\nint main(int argc, char **argv) {\n    \u002F* app id MUST match .desktop filename, icon name, and AppStream id *\u002F\n    AdwApplication *app = adw_application_new(\"com.example.MyApp\",\n                                              G_APPLICATION_HANDLES_OPEN);\n    g_signal_connect(app, \"activate\", G_CALLBACK(on_activate), NULL);\n    int status = g_application_run(G_APPLICATION(app), argc, argv);\n    g_object_unref(app);\n    return status;\n}\n```\n\n```rust\n\u002F\u002F GTK4 from Rust via gtk4-rs — increasingly the default for new GTK apps.\n\u002F\u002F Keep the gtk4 and libadwaita crate versions in lockstep; they're coupled.\nuse adw::prelude::*;\nuse adw::{Application, ApplicationWindow, HeaderBar};\nuse gtk::{Box as GtkBox, Orientation};\n\nfn main() -> glib::ExitCode {\n    let app = Application::builder()\n        .application_id(\"com.example.MyApp\")\n        .build();\n    app.connect_activate(|app| {\n        let content = GtkBox::new(Orientation::Vertical, 0);\n        content.append(&HeaderBar::new());\n        ApplicationWindow::builder()\n            .application(app)\n            .default_width(900).default_height(600)\n            .content(&content)\n            .build()\n            .present();\n    });\n    app.run()\n}\n```\nNote the trend: GNOME itself is migrating components to Rust (GNOME Disks' 51 rewrite\nmoved UI code and libgdu utilities to Rust talking to UDisks2 via `udisks-rs`). gtk4-rs is\nproduction-grade.\n\n**GTK4 concepts that trip people up:** the shift from GTK3's `pack_start`\u002Fcontainer model\nto explicit `append`\u002Fsingle-child layout; `GtkListView`\u002F`GtkColumnView` with\n`GListModel`+factories replacing `GtkTreeView`\u002F`GtkListStore`; CSS-based styling with GTK's\nown subset (not web CSS); `GtkEventController` replacing direct event handling; and\n`GtkBuilder`\u002F`.ui` XML plus **Blueprint** (a friendlier DSL that compiles to `.ui`) for\ndeclarative UI.\n\n**GTK5** is not imminent; treat GTK4 as the target for the foreseeable future.\n\n### 5.2 Qt 6\n\nCurrent: **Qt 6.11.x** (6.11.1, May 2026), on a ~6-month minor cadence. **Licensing is the\ndecision, not the technology:**\n- **LGPLv3** (most modules): free, but you must permit relinking — practically, dynamic\n  linking, or shipping object files. Some modules are **GPL-only** (notably Qt Charts,\n  Qt Data Visualization, and parts of the tooling), which will contaminate a proprietary\n  app if you use them.\n- **Commercial**: required for static linking in a closed-source product, and for LTS\n  patch releases. **LTS patch releases are commercial-only**; open-source users get LTS\n  branches treated as ordinary releases. Since 6.8.0, LTS support runs five years\n  (three before that).\n- The KDE Free Qt Foundation agreement is the backstop that keeps Qt open-source.\n\n**Qt Widgets vs Qt Quick\u002FQML [CONTESTED]:**\n- *Widgets*: mature, native-ish look, excellent for dense desktop tools (IDEs, CAD,\n  engineering software), C++ only, retained-mode. Not deprecated but not where new\n  investment goes.\n- *Quick\u002FQML*: declarative, GPU-accelerated, animation-friendly, JavaScript for logic,\n  designed for touch\u002Fembedded\u002Ffluid UI. Better for modern-looking apps; worse for dense\n  data grids and for teams that don't want a second language in the build.\n- Most desktop-tool companies still ship Widgets. Most new embedded\u002FHMI work is Quick.\n\n**PySide6** (official, LGPL) and **PyQt6** (Riverbank, GPL\u002Fcommercial) are the Python\nbindings; PySide6's licensing is friendlier for proprietary work. Note that free-threaded\n(GIL-less) Python support is still being worked out because a GIL-less runtime requires\nQt's own locking against the event loop.\n\n### 5.3 The rest\n\n| Toolkit | Status | Use when |\n|---|---|---|\n| **wxWidgets** | Alive, native controls per platform | You want genuinely native widgets and C++ |\n| **FLTK** | Alive, tiny | Minimal dependency footprint, simple tools |\n| **Tk\u002FTkinter** | Alive, ancient | Python scripts that need *a* window |\n| **Dear ImGui** | Thriving | Debug UIs, tools, game editors. Immediate-mode; not for consumer apps |\n| **EFL\u002FEnlightenment** | Niche | — |\n| **Motif\u002FXt** | Legacy | Maintaining 1990s software |\n\n---\n\n## §6. Wayland and X11\n\n### 6.1 The state of the transition (2026) — this changed recently\n\n- **GNOME removed X11 session support**: the X11 session was disabled by default in\n  GNOME 49, and the X11 backend code was **removed from Mutter**, with GNOME 50 (March\n  2026) shipping with no X11 code at all.\n- **KDE Plasma will be Wayland-only in Plasma 6.8**, expected **October 2026**; the Plasma\n  X11 session is supported into **early 2027** for 6.7 users. KDE's stated rationale: the\n  vast majority of Plasma users are already on Wayland and many distros already dropped\n  the X11 session independently.\n- Distros moved first in several cases: **Fedora 43** and **Ubuntu 25.10** already ship\n  without a GNOME X11 session.\n- Other desktops lag: **XFCE 4.20** added initial Wayland support (using labwc as a\n  stop-gap; xfwm4 is not yet a compositor); LXQt is further along than expected; Cinnamon\n  and MATE are behind.\n- **Xorg is not abandoned but its feature development is halted** — the same maintainers\n  fix security issues; new capability work happens in Wayland. **XLibre** is a fork with\n  more active development, of contested provenance, adopted by a small number of distros.\n- **X11 applications keep working** through **XWayland**. Dropping the X11 *session* is not\n  dropping X11 *apps*.\n\n**[UNIVERSAL, practical] Your app must work under Wayland in 2026.** Testing only on X11 is\nnow testing on a legacy path.\n\n### 6.2 What Wayland takes away, and what replaces it\n\nThis is the porting checklist. Under Wayland, a client **cannot**, by design:\n\n| X11 capability | Wayland status | Replacement |\n|---|---|---|\n| Read other windows' pixels (screenshot\u002Fcapture) | Forbidden | **ScreenCast portal** → PipeWire stream |\n| Global hotkeys | Not in core | **GlobalShortcuts portal**, or compositor-specific |\n| Set absolute window position | Forbidden | Compositor decides. `xdg-positioner` for popups only |\n| Query\u002Fset the pointer position | Forbidden | Relative motion only (pointer-constraints for games) |\n| Inject input into other apps | Forbidden | **RemoteDesktop portal**, **libEI** |\n| Read the clipboard without focus | Forbidden | `wl_data_device`, requires focus\u002Fuser action |\n| Override-redirect windows | No | `xdg-shell` roles: toplevel, popup; `layer-shell` for panels |\n| `XTest` automation | No | libEI \u002F portal, or compositor-specific test protocols |\n\n> **⚠️ GOTCHA — this list *is* the port.** If your app does screen capture, global\n> hotkeys, remote control, window positioning, or input automation, \"porting to Wayland\"\n> is not a rendering change — it's replacing those features with portal-mediated,\n> user-consenting equivalents that have different UX (a permission prompt, a picker\n> dialog). Budget for the UX redesign, not just the code.\n\n**Server-side vs client-side decorations (SSD\u002FCSD)** is a long-running friction point:\nGNOME\u002FMutter prefers CSD (the app draws its own titlebar — that's what a GTK `HeaderBar`\nis); KDE supports SSD via the `xdg-decoration` protocol. An app that assumes one gets\neither a double titlebar or none. Toolkits handle this; hand-rolled Wayland clients must\nnegotiate it.\n\n**Fractional scaling**: `wp_fractional_scale_v1` lets clients render at a fractional\nbuffer scale instead of rendering at 2× and downscaling (which is blurry). Modern GTK4\u002FQt6\nsupport it; older toolkits and XWayland clients often don't, which is why \"text is blurry\nat 125%\" is still a live complaint.\n\n**Remote desktop is the current genuine regression.** GNOME and KDE offer RDP-based remote\ndesktop; many third-party tools require someone physically present to accept the\nconnection because of Wayland's permission model. TigerVNC has shipped a Wayland-first VNC\nserver. If your product does unattended remote access, investigate carefully — this is not\nsolved to X11 parity.\n",{"name":5,"description":7},"develop","ae32736a1aabddabca5d2c96d665aa0ebc7d8700","src\u002Fvibey_tools\u002Fskills\u002Fplugins\u002Fdesktop-apps-macos-linux\u002Fskills\u002Fdesktop-linux-platform",3,"https:\u002F\u002Fgithub.com\u002Fthe-vibey-project\u002Fvibey","https:\u002F\u002Fthe-vibey-project.github.io\u002Fvibey\u002F","https:\u002F\u002Fgithub.com\u002Fthe-vibey-project","https:\u002F\u002Fvibewithadam.matthewsteinberger.com","freedom for software engineers","2026-11-15 05:47:42",{"source":8,"skillName":5,"commands":35,"prompt":45,"zipAvailable":46},[36,39,42],{"tool":37,"command":38},"npx","npx skills add the-vibey-project\u002Fvibey --skill desktop-linux-platform",{"tool":40,"command":41},"bunx","bunx skills add the-vibey-project\u002Fvibey --skill desktop-linux-platform",{"tool":43,"command":44},"pnpm","pnpm dlx skills add the-vibey-project\u002Fvibey --skill desktop-linux-platform","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fthe-vibey-project\u002Fvibey\u002Fblob\u002Fdevelop\u002Fsrc\u002Fvibey_tools\u002Fskills\u002Fplugins\u002Fdesktop-apps-macos-linux\u002Fskills\u002Fdesktop-linux-platform\u002FSKILL.md",true,[],[49,56,63,70,77,84],{"skillNo":50,"name":51,"nameZh":6,"description":52,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":53,"categories":54,"keywords":55,"publishedAt":19},"01M7AT1FQJAE1FQYAMDTF490Y4","white-paper-writing","Use when writing white papers, technical reports, policy documents, thought leadership pieces, or any long-form authoritative document. Triggers on requests to write, structure, outline, or review white papers, technical reports, position papers, policy briefs, or evidence-driven arguments. Also use for B2B content marketing strategy, technical documentation requiring authority, academic-style reports, or any document that must educate while persuading. Use when someone asks \"how should I structure this\" for a long-form document.","https:\u002F\u002Fgithub.com\u002Fthe-vibey-project\u002Fvibey\u002Fblob\u002Fdevelop\u002Fsrc\u002Fvibey_tools\u002Fskills\u002Fplugins\u002Fwriting-craft\u002Fskills\u002Fwhite-paper-writing\u002FSKILL.md",[],[],{"skillNo":57,"name":58,"nameZh":6,"description":59,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":60,"categories":61,"keywords":62,"publishedAt":19},"01M7AT16BJRJJKK2MASXRZS76G","prose-technical-mechanics","Use when editing or writing prose at a technical\u002Fmechanical level: choosing between Anglo-Saxon and Latinate diction, placing information in topic vs stress positions, writing periodic vs cumulative sentences, handling sentence rhythm, punctuation as logic, transitions, paragraph structure, or phonesthetics. Use when someone wants to understand WHY prose works or doesn't, not just surface-level style advice. Triggers on word choice, sentence structure, emphasis, rhythm, diction, or any deep writing mechanics question.","https:\u002F\u002Fgithub.com\u002Fthe-vibey-project\u002Fvibey\u002Fblob\u002Fdevelop\u002Fsrc\u002Fvibey_tools\u002Fskills\u002Fplugins\u002Fwriting-craft\u002Fskills\u002Fprose-technical-mechanics\u002FSKILL.md",[],[],{"skillNo":64,"name":65,"nameZh":6,"description":66,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":67,"categories":68,"keywords":69,"publishedAt":19},"01M7AT0W9HT0ZZ9Y287NW99MR3","prose-mechanics","Use when writing, editing, or analyzing prose style; when trying to avoid generic AI-sounding writing; when applying specific prose styles such as journalistic, academic, narrative, KJV biblical, Hemingway plain, Latinate\u002FJamesian, Orwellian, Augustan, Victorian, Early Modern (Bacon, Browne, Milton), or free indirect discourse; or when coaching someone on writing voice and mechanics. Triggers on any request to improve, analyze, or write in a specific prose style, to fix \"AI-sounding\" writing, to make prose more vivid or concrete, to vary sentence rhythm, or to understand how a particular writer achieves their effects.","https:\u002F\u002Fgithub.com\u002Fthe-vibey-project\u002Fvibey\u002Fblob\u002Fdevelop\u002Fsrc\u002Fvibey_tools\u002Fskills\u002Fplugins\u002Fwriting-craft\u002Fskills\u002Fprose-mechanics\u002FSKILL.md",[],[],{"skillNo":71,"name":72,"nameZh":6,"description":73,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":74,"categories":75,"keywords":76,"publishedAt":19},"01M7AT0KR635JX66X2X6F3E2CP","narrative-structure","Use when structuring stories, pitches, presentations, white papers, or any persuasive narrative; analyzing the hero's journey in fiction or non-fiction; applying StoryBrand for business communication; designing narrative arcs for thought leadership; or understanding Vogler, Snyder, Propp, or Campbell frameworks. Triggers on any narrative structure, storytelling, pitch structure, StoryBrand, hero's journey, three-act structure, Freytag, Save the Cat, narrative arc, or \"how should I structure this story\u002Fpitch\u002Fpresentation\" request.","https:\u002F\u002Fgithub.com\u002Fthe-vibey-project\u002Fvibey\u002Fblob\u002Fdevelop\u002Fsrc\u002Fvibey_tools\u002Fskills\u002Fplugins\u002Fwriting-craft\u002Fskills\u002Fnarrative-structure\u002FSKILL.md",[],[],{"skillNo":78,"name":79,"nameZh":6,"description":80,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":81,"categories":82,"keywords":83,"publishedAt":19},"01M7AT0AKGW09NKKZDYBT8VRDE","legal-brief-writing","Use when writing legal briefs, motions, or any court filing; when analyzing judicial cognition and persuasion; when applying elite brief-writing techniques from Roberts, Clement, Kagan, Garner; or when structuring legal arguments for maximum persuasion. Also use for autistic\u002Fneurodivergent advocates who need to understand how their natural communication style maps to elite legal advocacy. Triggers on any legal writing, brief drafting, motion preparation, or legal argument structuring request.","https:\u002F\u002Fgithub.com\u002Fthe-vibey-project\u002Fvibey\u002Fblob\u002Fdevelop\u002Fsrc\u002Fvibey_tools\u002Fskills\u002Fplugins\u002Fwriting-craft\u002Fskills\u002Flegal-brief-writing\u002FSKILL.md",[],[],{"skillNo":85,"name":86,"nameZh":6,"description":87,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":88,"categories":89,"keywords":90,"publishedAt":19},"01M7AT00VWPS4Q8B5VEMXX9NQT","journal-publishability-criteria","Use whenever a research paper, article or preprint is being written, revised, reviewed or published, and specifically before every publication of docs\u002Fpaper.md. Covers what legitimate journals actually gate on, in order of gating — the editor's desk screen (scope, novelty, package problems), what reviewers judge (methodological soundness, claims the evidence can carry, statistical and qualitative reporting), EQUATOR reporting guidelines, the ICMJE authorship criteria, COPE's view of text recycling, the near-universal generative-AI policy (no AI author, disclosure, author responsibility), TOP 2025 transparency standards, how to verify a journal is legitimate, submitting without an institution, and a pre-submission checklist. Triggers on requests to evaluate, review, prepare or submit a paper, to judge publishability, to write a declarations or data-availability section, to disclose AI use, or to check a journal.","https:\u002F\u002Fgithub.com\u002Fthe-vibey-project\u002Fvibey\u002Fblob\u002Fdevelop\u002Fsrc\u002Fvibey_tools\u002Fskills\u002Fplugins\u002Fwriting-craft\u002Fskills\u002Fjournal-publishability-criteria\u002FSKILL.md",[],[]]