/desktop-ui-electron

name: desktop-ui-electron
description: Frameless windows, custom title bars, tray, menus, dock badges, vibrancy, kiosk mode, window state persistence

Electron Desktop UI Patterns

> **Quick Guide:** Use `titleBarStyle: 'hidden'` for custom title bars with native traffic lights on macOS, combined with `titleBarOverlay` for Windows/Linux window controls. Mark draggable regions with `app-region: drag` in CSS and exclude interactive elements with `app-region: no-drag`. Keep a module-level reference to `Tray` objects (garbage collection silently destroys the icon). Use `vibrancy` for macOS translucency effects and `backgroundMaterial` for Windows 11 Mica/Acrylic. Persist window bounds manually with `getBounds()`/`setBounds()` on the `close` event.

---

<critical_requirements>

CRITICAL: Before Using This Skill

**(You MUST keep a module-level reference to `Tray` objects -- garbage collection silently destroys the tray icon with no error)**

**(You MUST use `app-region: no-drag` on ALL interactive elements (buttons, inputs, links) inside a drag region -- draggable areas swallow all pointer events)**

**(You MUST add `user-select: none` to draggable title bar regions -- dragging conflicts with text selection)**

**(You MUST NOT use `transparent: true` with `backgroundMaterial` on Windows -- set `backgroundColor: '#00000000'` instead to allow the DWM material to show through)**

</critical_requirements>

---

**Auto-detection:** titleBarStyle, titleBarOverlay, trafficLightPosition, frameless window, frame false, app-region drag, custom title bar, Tray, system tray, tray icon, Menu.buildFromTemplate, context menu, app.setBadgeCount, dock badge, splash screen, kiosk, alwaysOnTop, vibrancy, backgroundMaterial, mica, acrylic, transparent window, electron-window-state, window state persistence, getBounds, setBounds

**When to use:**

• Building custom title bars (frameless, overlay controls, macOS traffic light positioning)
• Creating system tray icons with context menus
• Building application menus and context menus
• Adding dock/taskbar badges for notifications
• Implementing splash screens or always-on-top windows
• Making windows transparent or applying vibrancy/material effects
• Persisting and restoring window position and size
• Entering kiosk mode for single-app displays

**When NOT to use:**

• Choosing a UI framework for the renderer content (not this skill's scope)
• Styling renderer page content (not this skill's scope)
• Configuring IPC or preload security (separate from window chrome customization)
• Packaging or distributing the application (separate from window chrome customization)

**Key patterns covered:**

• Frameless windows with `titleBarStyle: 'hidden'` and `titleBarOverlay`
• Custom title bars with CSS `app-region: drag` / `no-drag`
• macOS traffic light positioning via `trafficLightPosition`
• Native application menus and context menus
• System tray icons with menus and click handlers
• Dock/taskbar badges (`app.setBadgeCount`, `app.dock.setBadge`)
• Splash screens and always-on-top windows
• Window state persistence (position, size, maximized)
• Transparent windows, vibrancy (macOS), backgroundMaterial (Windows 11)
• Kiosk mode

---

<philosophy>

Philosophy

Electron desktop UI customization operates at two levels: **window chrome** (title bar, frame, transparency, system tray) controlled via `BrowserWindow` constructor options and main process APIs, and **in-window layout** (drag regions, custom title bar HTML/CSS) controlled via the renderer. The main process owns window-level behavior; the renderer owns the visual presentation within the window.

**Platform-aware design is essential.** macOS has native traffic lights and vibrancy. Windows 11 has Mica/Acrylic materials and `titleBarOverlay` for window controls. Linux varies by desktop environment. Always test UI customizations on all target platforms -- what works on macOS may look wrong on Windows or be unsupported on Linux.

**When to customize window chrome:**

• App requires a branded header or sidebar navigation alongside window controls
• App needs to minimize visual chrome (media player, creative tool)
• App runs in kiosk/display mode (digital signage, POS terminal)
• App needs persistent system tray presence (background services, communication tools)

**When NOT to customize:**

• Standard document-based apps where native title bar is expected
• Apps where accessibility is the top priority (custom title bars can break screen readers)
• When native platform look-and-feel is more important than branding

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Frameless Windows and Custom Title Bars

Use `titleBarStyle: 'hidden'` to remove the native title bar while keeping macOS traffic lights. On Windows/Linux, add `titleBarOverlay` to get native window control buttons overlaid on your content.

const TITLE_BAR_OVERLAY_HEIGHT = 40;

const mainWindow = new BrowserWindow({
  titleBarStyle: "hidden",
  // Windows/Linux: overlay native controls on custom title bar
  titleBarOverlay: {
    color: "#2f3241",
    symbolColor: "#74b1be",
    height: TITLE_BAR_OVERLAY_HEIGHT,
  },
  // macOS: position traffic lights within custom title bar
  trafficLightPosition: { x: 16, y: 12 },
});

**Key point:** `titleBarStyle: 'hidden'` hides the title text and title bar area but keeps macOS traffic lights visible. `titleBarOverlay` creates a Windows Controls Overlay (WCO) with native minimize/maximize/close buttons on Windows and Linux. See [examples/core.md](examples/core.md) for the full CSS title bar implementation.

---

Pattern 2: CSS Drag Regions

Mark custom title bar areas as draggable with `app-region: drag`. All interactive elements (buttons, inputs) inside a drag region MUST be marked `app-region: no-drag` or they will be unclickable.

.title-bar {
  app-region: drag;
  user-select: none;
  height: 40px;
}

.title-bar button,
.title-bar input {
  app-region: no-drag;