There are fundamentally two different ways to think about application windows.
In the first paradigm, an application exposes a single visual identity. The frame, header, and content are all part of the same visual and conceptual entity, drawn by the application itself. This is the model Wayland is built around by default: the client renders its entire window, and there is no inherent notion of a window being split into independent parts. Importantly, this paradigm implies that an application fully owns its visual identity. If it uses the native toolkit of the desktop—such as GTK on GNOME—it will naturally follow the desktop’s design language and style guide, not just for the titlebar but for every detail of its widgets, spacing, typography, and interactions. If it uses a different toolkit, then by definition it cannot fully match those native design constraints, and it will look different as a whole. In that sense, the titlebar is not a special case: it is simply another piece of UI, subject to the same rules as the rest of the application.
The second paradigm embraces a split visual identity. Here, a window is explicitly composed of two separate and non-cooperating parts. The header or frame is owned and drawn by the compositor, and therefore follows the visual style and design decisions of the desktop environment. The content area is entirely owned by the application and can follow its own visual language, independently of the desktop. In this model, difference is not an accident but a structural property: the two parts are distinct by design, with different owners, different responsibilities, and potentially different aesthetics.
Wayland allows these two approaches to be negotiated through the xdg-decoration protocol, where a client may express a preference for server-side decorations. However, this remains only a preference: the compositor always has the final say and can enforce client-side decorations regardless of what the application requests. From a protocol and architectural standpoint, the single-identity model is therefore the most robust, while the split-identity model is inherently more fragile and depends on the compositor being a willing partner that explicitly supports SSD.
GNOME fully embraces the single-identity paradigm and expects applications to be drawn as a single coherent surface, which is why client-side decorations are required there. For application developers, this means making a clear choice: either adopt the native toolkit and integrate deeply with the desktop’s design language, or embrace a distinct application identity and draw the entire window yourself, including the window decorations. In both cases, visual difference is not a flaw but the direct and consistent outcome of that choice.
It is worth noting that there is a way to approximate the split-identity model while still operating within the single-identity paradigm, by using the libdecor library. In this case, the application still draws a single surface and fully complies with client-side decorations, but delegates the drawing of its CSD to libdecor. Since libdecor styles the decorations according to the desktop environment, the resulting titlebar visually matches the desktop and can give the impression of traditional server-side decorations. Conceptually, however, nothing has changed: the window remains a single surface owned by the client, and the apparent split between “header” and “content” is purely visual, not a real separation of responsibilities.
From an application developer’s perspective, the key question is how the application behaves across desktops that enforce a single identity (native or personal) and those that support a split identity (titlebar native and content personal). The following table summarizes the main coherent approaches:
| Application Approach | Single-identity desktops (CSD-only, e.g. GNOME) | Split-identity desktops (SSD capable) | Details |
|---|---|---|---|
| 1. Native CSD with native toolkit | ✅ Supported, single native identity | ✅ Supported, single native identity | The application uses the desktop’s native toolkit. Whether the compositor enforces CSD or enables SSD, the visual identity remains native and coherent with the desktop as a whole. |
| 2. Dedicated / personal CSD | ✅ Supported, single personal identity | The application draws its own CSD with a custom style. On single-identity desktops, the application has a consistent personal identity. On SSD-capable desktops, the compositor may replace the header, resulting in a split identity (desktop-styled header, app-styled content). | |
| 3. CSD via libdecor | ✅ Supported, fake split identity | ✅ Supported, split identity | libdecor draws CSDs in the style of the desktop. This works everywhere, but always results in a split identity: the header matches the desktop, while the application content retains its own style. |
| 4. Pure SSD (no CSD) | ❌ Not supported | ✅ Supported, split identity | The application relies entirely on server-side decorations. It only works on desktops that embrace SSD. On single-identity desktops, the application has no decorations at all and effectively breaks. |
On the user side, a similar choice exists. By choosing a desktop environment, users implicitly decide whether they prefer a system that enforces single-identity applications, or one that embraces split identity and treats window decorations as a responsibility of the compositor.
See this comment as a defense for the "single-identity" (aka GNOME style): https://gitlab.gnome.org/GNOME/mutter/-/issues/217#note_356978