Overview Files Skills Discover Packages Releases Dependencies Issues Breadcrumbs Pull Requests Activity

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

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

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).

---
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).

Adom UI Design System

Floating windows and HUDs

Rules

Structure

AI-drivable

Related skills