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. GTK's header-bar component exemplifies a client-rendered surface that can combine title, controls, and application actions.

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.

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. AppKit likewise exposes window style, title visibility, and movable regions through NSWindow.

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.

Relationships to Other Abstractions

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

• Client-Side Decoration → is a kind of Delegation of Authority → presupposes Authority

Neighborhood in Abstraction Space

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

Family — Unclustered & Miscellaneous (2769 abstractions)

Nearest neighbors

• Virtual Desktop — 0.75
• State management — 0.72
• Interface transparency (computing) — 0.71
• Non-local variable — 0.71
• Context-sensitive user interface — 0.71

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