Skip to content

Client-Side Decoration

Assign an application client responsibility for rendering its own non-content window frame while coordinating move, resize, state, focus, and decoration mode with the window manager or compositor.

Version
v3 · 2026-09-19 · History
Domain-specific #
1479
Domain group
Applied Sciences & Engineering
Origin domain
Computer Science & Software Engineering
Subdomain
Window Systems → Computer Science & Software Engineering
Aliases
CSD, Client-decorated window, Client-side window decorations

Core Idea

Client-side decoration assigns a graphical application responsibility for drawing the window frame around its content—commonly the title/header bar, border, shadows, and window controls—rather than having the window manager or compositor draw that frame. The window-management authority is not thereby abolished: the client must still request move, resize, maximize, minimize, and close behavior through the window-system protocol.

Wayland's xdg-decoration extension makes the split explicit by negotiating client-side or server-side mode between a toplevel client and compositor.[1] GTK's header-bar component exemplifies a client-rendered surface that can combine title, controls, and application actions.[2]

How would you explain it like I'm…

The App Draws Its Frame

On a computer screen, each window has a frame around it with a top bar and buttons to close it. With client-side decoration, the app draws its own frame instead of the computer's window helper drawing it. But the app still has to ask the window helper whenever it wants to move, resize, or close the window.

Self-Drawn Window Frames

Every window on a computer screen has a frame: a title bar, borders, shadows, and buttons like minimize and close. Normally a separate program that manages windows draws those frames. Client-side decoration means the app itself draws its own frame, which lets it put its own buttons and tools right in the title bar. Even so, the app is not the boss of the window: to move, resize, or close it, it must send a request to the window manager. Some systems let the app and the manager agree on who draws the frame.

App-Rendered Window Decorations

Client-side decoration means a graphical application draws its own window frame, the title or header bar, borders, shadows, and window-control buttons, rather than the window manager or compositor drawing it (server-side decoration). This lets an app merge its own controls into the frame; GTK's header bar, for example, combines the title, window controls, and application actions in one client-drawn surface. Importantly, drawing the frame does not give the app control of window management: when a user drags or clicks the close button, the app must still request move, resize, maximize, minimize, or close through the window-system protocol. On Wayland, the xdg-decoration extension lets a client and compositor negotiate whether decorations will be client-side or server-side.

 

Client-side decoration assigns the drawing of a window's frame to the client application rather than to the window manager or compositor (server-side decoration). The frame typically comprises the title or header bar, borders, drop shadows, and window controls. Moving rendering into the client lets it integrate application actions with the frame, as in GTK's header-bar component, which combines title, controls, and app actions in one client-rendered surface. Crucially, window-management authority remains with the window system: the client must request move, resize, maximize, minimize, and close operations through the protocol rather than performing them itself. Wayland's xdg-decoration protocol extension makes the division explicit by letting a toplevel client and the compositor negotiate client-side or server-side mode. So CSD relocates rendering responsibility, not management authority.

Structural Signature

  • A top-level application window owned by a client.
  • A window manager or compositor controlling placement and global state.
  • Non-content decoration rendered by the client.
  • Client-defined title or header layout.
  • Window controls tied to protocol requests.
  • Input regions for dragging and edge/corner resizing.
  • Negotiation or convention governing client- versus server-side mode.
  • Scale, theme, accessibility, focus, and active-state handling.
  • Fallback behavior when a compositor does not support the requested mode.
  • A failure boundary when the client is hung or unresponsive.

What It Is Not

It is not a borderless window: a decorated title bar may still be entirely client-rendered. It is not merely customizing title text, and it does not make the application the window manager. It is also not the same as putting content beneath a transparent system title bar unless the application assumes responsibility for the decoration surface and control integration.

Scope of Application

CSD appears in Wayland and X11 desktop applications, GTK header bars, frameless Electron windows, and operating-system APIs for custom title bars. Microsoft's title-bar customization contract preserves system interaction behaviors while allowing application content in the title region.[3] AppKit likewise exposes window style, title visibility, and movable regions through NSWindow.[4]

Clarity

Specify which party draws each pixel, owns shadows, performs hit testing, supplies window buttons, and initiates move/resize operations. State protocol and compositor support, fallback mode, accessibility representation, scale-factor handling, focus styling, and behavior when the client stalls.

Manages Complexity

The technique lets application chrome and window chrome share one layout, reclaim unused title-bar space, and adapt to narrow form factors. It also moves cross-desktop consistency, input hitboxes, and some reliability obligations into each toolkit or application.

Abstract Reasoning

  1. Negotiate or detect the permitted decoration mode.
  2. Reserve a client-rendered frame region outside or above primary content.
  3. Draw title, state, actions, and controls using current scale and theme.
  4. Mark draggable and resizable regions without stealing ordinary widget input.
  5. Translate control activation into window-protocol requests.
  6. React to focus, maximization, tiling, fullscreen, and capability changes.
  7. Expose controls and title semantics to accessibility services.
  8. Test compositor, toolkit, theme, scaling, and unresponsive-client failure cases.

Knowledge Transfer

The portable pattern is move presentation responsibility to the component with application context while retaining state-changing authority at the system boundary. It transfers to embedded editors and custom media controls. The proposed immediate parent is Delegation of Authority.

Examples

A GTK application can place search, view selection, and primary actions beside its title while drawing standard close and maximize controls. A frameless Electron application must implement its own draggable regions and controls, but the operating system still performs the requested window operations.

If a client-rendered close button freezes with the application, it may no longer offer the server-rendered escape path that a traditional frame provides. That reliability tradeoff is structural, not cosmetic.

Structural Tensions

  • Application integration versus desktop consistency.
  • Local context versus duplicated toolkit responsibility.
  • Flexible header space versus reliable system controls.
  • Client rendering versus compositor authority.
  • Custom appearance versus accessibility and theme conformance.

Structural–Framed Character

Responsibility transfer and protocol coordination are structural. Windows, clients, compositors, title bars, hit regions, and desktop controls are constitutive. The identity is domain-specific.

Structural Core vs. Domain Accent

The structural core is delegate rendering -> retain system authority -> negotiate boundary -> preserve fallback. The domain accent is non-content window frames in graphical window systems.

This entry is a kind of Delegation of Authority.

Delegation of Authority is the broader abstraction this entry instantiates. Interface, Information Locality, Failure Containment, Feedback, and Presentation are related primes.

Relationships to Other Abstractions

Local relationship map for Client-Side DecorationParents appear above the current abstraction, mutual partners to the right, and children below. Node labels state whether each abstraction is prime or domain-specific; colors identify relation types.Client-SideDecorationDOMAINPrime abstraction: Delegation of Authority — is a kind ofDelegationof AuthorityPRIME

Current abstraction Client-Side Decoration Domain-specific

Parents (1) — outgoing typed relations

  • Client-Side Decoration is a kind of Delegation of Authority Prime

    Delegation of Authority is the broader abstraction this entry instantiates.

Hierarchy path (1) — routes to 1 parentless root

Neighborhood in Abstraction Space

Client-Side Decoration sits in a sparse region of the domain-specific corpus (100th percentile for distinctiveness): few abstractions share its structure, so a faithful description tends to retrieve it precisely.

Family — Unclustered & Miscellaneous (2769 abstractions)

Nearest neighbors

Computed from structural-signature embeddings · 2026-10-25

Not to Be Confused With

  • Borderless or undecorated window.
  • Server-side decoration.
  • Custom title text.
  • Window-manager theming.
  • Content drawn under a system-controlled title bar.
  • Application ownership of global window placement policy.

References

[1] Wayland Project, “XDG Decoration Protocol,” zxdg_decoration_manager_v1, wayland-protocols specification.not authoritative registry ↩

[2] GNOME Project, “Gtk.HeaderBar,” GTK 4 API Reference.not authoritative registry ↩

[3] Microsoft, “Title Bar Customization,” Windows App SDK Design Guidance.not authoritative registry ↩

[4] Apple, “NSWindow,” AppKit Developer Documentation. registry ↩