Design desktop window systems that feel native on macOS and Windows: split views, inspectors, auxiliary windows, tiling, snap-safe sizes, default placement, and chrome density. Use when a Tauri/Electron/WinUI/SwiftUI app feels awkward, overlapping, over-chromed, or generic, or when you need a real geometry contract for multiple surfaces. NOT for mobile layouts, marketing pages, or CSS-only component styling without multi-window or multi-pane behavior.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Design desktop window systems that feel native on macOS and Windows: split views, inspectors, auxiliary windows, tiling, snap-safe sizes, default placement, and chrome density. Use when a Tauri/Electron/WinUI/SwiftUI app feels awkward, overlapping, over-chromed, or generic, or when you need a real geometry contract for multiple surfaces. NOT for mobile layouts, marketing pages, or CSS-only component styling without multi-window or multi-pane behavior.
{"category":"Desktop & Native","tags":["desktop","windows","macos","tauri","electron","window-management","split-view","inspector","layout","chrome"],"pairs-with":[{"skill":"cross-platform-desktop","reason":"Platform-specific conventions and packaging differences complement layout decisions."},{"skill":"native-app-designer","reason":"Once the surface model is correct, visual refinement should preserve the platform feel."},{"skill":"mobile-ux-optimizer","reason":"Use only when the desktop shell must gracefully degrade at very narrow widths."},{"skill":"reactflow-expert","reason":"Graph-heavy apps often need role-aware panes, inspectors, and canvas prioritization."}],"argument-hint":"[target-path-or-app-shell] [audit|design|fix]"}
Desktop Window Layout Architect
Make desktop applications feel like they belong on a real operating system, not like web cards trapped in draggable divs.
When to Use
✅ Use for:
Tauri, Electron, WinUI, SwiftUI, or hybrid desktop shells that feel spatially wrong.
Multi-surface apps with a main canvas plus navigation, inspectors, logs, results, or task artifacts.
Overlapping windows, ugly default placement, brittle tiling, or restore/maximize behavior that feels fake.
Decisions about split view vs auxiliary window vs floating panel vs modal sheet.
Fixing title bar density, command placement, and “too much chrome, not enough field.”
❌ NOT for:
Mobile navigation patterns, tab bars, or handset-only adaptive layouts.
Landing pages, dashboards in the browser, or ordinary responsive marketing surfaces.
Pure component styling where the problem is typography/color/spacing, not window or pane behavior.
Backend orchestration, IPC wiring, or packaging/signing issues that do not affect desktop interaction design.
Fast Signals
Use these to pull the relevant geometry and shell clues into context before deciding anything.
Window Management Files
!`rg -n "openWindow|snapWindow|tileWindows|cascadeWindows|arrangeReviewWorkspace|WindowFrame|Titlebar|Taskbar|SplitView|TwoPane|NavigationView""${ARGUMENTS:-.}" 2>/dev/null | head -n 120`
Geometry and Restore Signals
!`rg -n "innerHeight|innerWidth|defaultSize|minSize|restoreBounds|window-state|isMaximized|position|size""${ARGUMENTS:-.}" 2>/dev/null | head -n 120`
Support Files
Load only the files that match the current blocking question.
File
Load when
Purpose
references/INDEX.md
First
Decide which deep-dive file to read instead of loading everything
references/platform-principles.md
When grounding decisions in OS conventions
Apple HIG, Windows Fluent, and Tauri state-restoration synthesis
references/surface-selection.md
When deciding split pane vs panel vs auxiliary window
Surface taxonomy and role-based routing
references/geometry-and-placement.md
When defining default sizes, mins, snap safety, or restore rules
Geometry contract and placement heuristics
references/chrome-density-and-commanding.md
When the UI feels crowded or command-heavy
Title bars, gutters, bottom bars, action placement
references/workspace-presets.md
When designing review, compare, authoring, or inspect modes
Role-aware workspace recipes
references/implementation-patterns.md
When translating guidance into code
Tauri/Electron/WinUI/SwiftUI implementation notes
scripts/preflight.sh
Before any repo-specific audit
Read-only inspection of likely shell/layout files
scripts/audit_window_layout.py
When you want a fast static audit
Emits findings plus JSON, Markdown, or HTML reports about geometry, tiling, snap safety, and restore behavior
templates/layout-audit-template.md
When returning a structured review
Reusable final answer skeleton
templates/window-registry-template.ts
When designing a new window registry or refactor
Role- and mode-aware config template
templates/workspace-preset-template.json
When defining breakpoints and workspace presets
Serializable layout contract
examples/windags-review-workspace.md
When auditing a graph + inspector + artifact app
Concrete before/after reasoning
examples/surface-selection-scenarios.md
When the right surface is unclear
Trigger examples that provoke different surface choices
agents/desktop-window-layout-architect-worker.md
When a clean-room critique or parallel audit helps
Narrow worker for isolated layout review
Output Contract
Unless the user explicitly asks for something narrower, structure the answer like this:
Surface Map — what surfaces should exist and their roles
Chrome and Commanding — what belongs in title bars, panes, bottom bars, and menus
Workspace Presets — how the layout should adapt across wide / medium / narrow desktop widths
Implementation Moves — the smallest code changes that produce the biggest improvement
Use templates/layout-audit-template.md when emitting this structure verbatim.
Core Process
flowchart TD
A[Identify app type and current pain] --> B{Same task context?}
B -->|Yes| C[Prefer panes inside one primary window]
B -->|No| D{Transient or persistent?}
D -->|Transient| E[Modal sheet or popover]
D -->|Persistent task area| F[Auxiliary window]
C --> G{Supplemental live selection details?}
G -->|Yes| H[Trailing inspector or inspector panel]
G -->|No| I[Sidebar + content or two-pane layout]
H --> J[Define geometry contract]
I --> J
F --> J
E --> J
J --> K[Define placement and restore rules]
K --> L[Trim chrome and command duplication]
L --> M[Validate against wide, medium, narrow desktop widths]
M --> N[Ship role-aware presets instead of fixed percentages]
Step 1: Classify the Surface Model
Decide whether the problem belongs to:
a primary window with multiple panes,
an auxiliary window dedicated to one task,
a floating panel like an inspector,
or a modal/sheet for short blocking work.
Rules:
If users need to read two or three related regions together, default to a single primary window with panes, not multiple floating windows.
If a surface tracks the current selection and updates live, prefer a trailing inspector or inspector panel.
If a surface represents a separate durable task with its own lifecycle, use an auxiliary window.
If the interaction is short and blocking, use a sheet/popover/modal, not a whole extra window.
Step 2: Map Roles Before Coordinates
Assign each surface a role:
navigation
canvas
detail
inspector
artifact
console
utility
Then rank them:
Field-first: canvas/detail/artifact that benefits from visual area
Supportive: navigation/inspector/console
Transient: utility/panel/modal
Never choose percentages before roles. Percentages are outputs of role priority, not the other way around.
Step 3: Write a Geometry Contract
Define, per surface:
default size,
minimum content size,
minimum snap-safe width,
collapse priority,
and whether it can hide.
Hard rules:
On Windows, keep the minimum width of a snappable primary window at 500 epx or less, and preferably around 330 epx when possible.
If panes are resizable, set mins and maxes that keep dividers usable.
If the sum of pane minimums does not fit, change layout mode. Do not enforce mins after a percentage split and let panes overlap.
Keep the primary content area dominant. Tooling should compress or hide before the main canvas does.
Step 4: Write a Placement Contract
Define:
first-open placement,
reopen / restore behavior,
parent-relative placement for auxiliary surfaces,
clamp behavior when viewport/display changes,
and maximize/snap restore semantics.
Rules:
First launch can center a window. After that, restore prior normal bounds.
Auxiliary windows should open near the invoking parent without obscuring the point of origin.
Floating panels should not masquerade as normal documents.
Keep at least a draggable title region visible when clamping a moved window back onscreen.
Model explicit window modes such as normal, maximized, snapped-left, snapped-right, tiled, with restoreBounds.
Step 5: Reduce Chrome Before Rearranging Content
Check whether the app is losing field to shell chrome:
title bars too tall,
duplicate headings inside panes,
oversized caption buttons,
permanent bottom bars,
or navigation plus commanding stacked redundantly.
Prefer:
a single meaningful window title,
thin dividers,
toolbar/title integration,
and command placement near the relevant pane.
Avoid putting critical actions in bottom bars on macOS-style desktop apps.
Step 6: Design Workspace Presets
Instead of one fixed arrangement, define at least three desktop-width regimes:
Medium: sidebar or inspector becomes collapsible/overlay
Narrow desktop: single primary pane plus toggleable support pane or tabs
The goal is not generic “responsiveness.” The goal is preserving task comprehension as width changes.
Step 7: Validate Like a Desktop Product
Validate at minimum:
1280×720
1440×900
1728×1117 or similar high-density laptop
ultrawide / dual-monitor assumptions if relevant
Check:
no overlap after minimum sizes apply,
snap works,
restore works,
no content-critical bottom bar is hidden,
and auxiliary surfaces do not steal focus unnecessarily.
Anti-Patterns
Anti-Pattern: Every Problem Gets Another Window
Novice: "If the screen feels crowded, split it into more floating windows."
Expert: Related work should usually stay inside one primary window with panes. New windows are for distinct task areas, not for every supportive region.
Timeline: Apple’s current HIG explicitly pushes supplementary information toward split views and inspectors before new windows; Windows pushes adaptive panes and navigation surfaces before ad hoc floaters.
Anti-Pattern: Chrome Is Free
Novice: "A 40px child title bar, thick borders, giant controls, and an always-on bottom action bar are fine."
Expert: Desktop users will trade ornamental chrome for field. Keep title bars draggable, legible, and system-like, but aggressively protect the content area.
Timeline: Windows 11 title bars remain concise and system-integrated; Apple guidance emphasizes content-first windows and warns against hiding critical actions in bottom bars.
Anti-Pattern: Percentages First, Minimums Later
Novice: "Split the screen 66/34 and 58/42, then clamp each pane to its minimum."
Expert: That causes overlap. Start from minimum viable pane sizes and role priority. If the floor sum does not fit, switch to a different preset.
Timeline: Mature desktop shells moved toward breakpoint- and mode-based arrangements because static percentages fail under resize and snap.
Novice: "New windows can open at x + 24, y + 24; that’s enough."
Expert: Window managers need restore bounds, snap modes, clamp-on-move, viewport recovery, and parent-relative placement. Cascade is an escape hatch, not the whole policy.
Timeline: Users now expect snap layouts, restore semantics, and remembered bounds out of the box on both Windows and modern desktop frameworks like Tauri.
Anti-Pattern: Inspector as a Mini Document Window
Novice: "The inspector can minimize, live forever in the task list, and behave like a peer document."
Expert: Inspectors are supplemental. They either live in a trailing pane or behave like panels with lighter lifecycle semantics.
Timeline: Apple’s panel guidance is explicit: panels are not documents, generally should not minimize, and should appear/disappear with app relevance.
Worked Examples
Example 1: Review Workspace for a Graph App
Load examples/windags-review-workspace.md.
Use it when the app has:
a graph/canvas,
a details inspector,
an exported artifact or log,
and currently opens them as overlapping windows.
Example 2: Choosing the Right Supplemental Surface
Load examples/surface-selection-scenarios.md.
Use it when the team is arguing about:
pane vs panel,
panel vs auxiliary window,
or modal vs persistent surface.
Quality Gates
The app has a named surface map before anyone debates percentages.
Every primary or auxiliary window has a default size, minimum content size, and restore policy.
Snap-safe surfaces support a minimum width of 500 epx or less on Windows; target 330 epx where practical.
No fixed workspace preset can overlap once minimum sizes are applied.
Title bars remain draggable and system legible; the app does not fake caption behavior badly.
The primary canvas/content region retains visual priority over inspectors and utilities.
Related content is unified into split panes before additional windows are introduced.
Bottom bars never contain mission-critical primary actions unless there is a strong, explicit reason.
The layout has explicit wide / medium / narrow desktop behavior.
Restored windows reappear onscreen even after display or viewport changes.
NOT-FOR Boundaries
Do not use this skill when:
the problem is just CSS polish inside a single page,
the product has no multi-surface behavior,
or the user needs mobile-first interaction patterns instead of desktop workspace ergonomics.
If the request is mostly about color, typography, or visual taste, pair this with a design skill after the surface model is fixed.
