---
name: floating-windows
user-invocable: true
description: >-
  How to build floaty tool windows and HUDs in an Adom app: draggable side panels and overlays that
  hold tools, inspectors, and controls without blocking the main content. Covers the drag grip,
  never clamping to a screen edge, max-height with internal scroll and a pinned header and footer,
  minimize / close / double-click-to-collapse, the z-index ladder slot (--z-hud), remembering
  position, and driving show/hide from the AI over the live channel for testing. Read BEFORE adding
  a floating panel, inspector, toolbar overlay, or HUD. Trigger words: floating window, floaty
  window, floaty toolbar, HUD, draggable panel, tool window, inspector panel, overlay panel,
  floating toolbar, drag handle, collapse panel, minimize panel, show hide toolbar, z-index hud.
---

# Floating windows and HUDs

A HUD is a draggable window that floats over the main content and holds a cluster of tools: an
inspector, a source list, a measurement readout, a settings panel. Done well it is always reachable
and never in the way. Done wrong it clamps to a corner, covers the thing you are working on, or
grows past the screen with no scroll.

## Rules

- **Draggable by a visible grip.** A clear header bar or a grip icon, not the whole panel (you still
  want to click controls inside). Cursor `grab` on the grip, `grabbing` while dragging.
- **Never clamp to a screen edge.** The user places it; do not snap it flush to a corner or pin it.
  Keep it fully on-screen on resize (clamp into the viewport), but do not force it to an edge.
- **Bounded height with internal scroll.** `max-height: calc(100% - <margin>)`. The header and
  footer stay pinned, the body scrolls. A HUD must never grow taller than the viewport.
- **Minimize, close, and double-click to collapse.** Every HUD offers all three. Collapsed shows
  just the header bar so it stays out of the way without disappearing.
- **It floats above content but below tooltips and modals.** Use the `--z-hud: 50` slot from the
  z-index ladder. A menu opened from a HUD button uses `--z-floating-menu: 200` so it can escape the
  HUD's box. Tooltips (99999) always win. See the `tooltips` skill for the full ladder.
- **Do not cover what the user is acting on.** Open in a neutral spot, let it be moved, and remember
  its last position (persist via the preferences API where it matters).
- **Watch the clipping trap.** If a menu inside the HUD opens out of the HUD and vanishes, that is
  `overflow: hidden` clipping, not z-index. Fix with `overflow-x: clip; overflow-y: visible` or
  reposition the menu to `position: fixed`.

## Structure

```
.hud
  .hud-head    (drag grip, title, minimize, close)   <- pinned
  .hud-body    (the tools)                            <- flex:1, min-height:0, overflow:auto
  .hud-foot    (optional status / actions)           <- pinned
```

```css
.hud {
  position: fixed; z-index: var(--z-hud);
  display: flex; flex-direction: column;
  max-height: calc(100% - 32px);
  background: #161b22; border: 1px solid #30363d; border-radius: 12px;
  box-shadow: 0 18px 50px rgba(0,0,0,.5);
}
.hud-head { cursor: grab; display: flex; align-items: center; gap: 8px; padding: 10px 12px; }
.hud-body { flex: 1 1 auto; min-height: 0; overflow: auto; padding: 12px; }
.hud.collapsed .hud-body, .hud.collapsed .hud-foot { display: none; }
```

## AI-drivable

Because the AI builds and tests the app (see `ai-driven-apps`), every HUD action has a command so
the AI can exercise it: `mytool ui toolbar show`, `mytool ui toolbar hide`, `mytool ui hud collapse
inspector`. This is also how the AI screenshots a panel open and closed during a ralph-test.

## Related skills

`tooltips` (the z-index ladder and tooltips that render above HUDs), `app-shell` (where HUDs mount
in the layout), `human-ui-patterns` (the broader interaction rules), `ai-driven-apps` (driving HUDs
for tests), and `adom-ui-design` (the hub).