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: v2 · 2026-09-06 · History
Domain-specific #: 1479
Origin domain: computer science
Subdomain: window systems
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]

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¶

Negotiate or detect the permitted decoration mode.
Reserve a client-rendered frame region outside or above primary content.
Draw title, state, actions, and controls using current scale and theme.
Mark draggable and resizable regions without stealing ordinary widget input.
Translate control activation into window-protocol requests.
React to focus, maximization, tiling, fullscreen, and capability changes.
Expose controls and title semantics to accessibility services.
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.

Delegation of Authority is the proposed immediate parent. Interface, Information Locality, Failure Containment, Feedback, and Presentation are related primes.

The prospective queue contains one strict edge to prime:delegation_of_authority. No live DAG mutation is authorized.

Relationships to Other Abstractions¶

Current abstraction Client-Side Decoration Domain-specific

Parents (1) — more general patterns this builds on

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

Delegation of Authority is the proposed immediate parent.

Hierarchy path (1) — routes to 1 parentless root

Client-Side Decoration → Delegation of Authority → 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 (1565 abstractions)

Nearest neighbors

Interaction Flow Modeling Language — 0.77
Virtual Desktop — 0.75
Frame (GUI) — 0.73
Non-local variable — 0.71
Context-sensitive user interface — 0.71

Computed from structural-signature embeddings · 2026-09-08

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. registry ↩

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

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

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