OS Shell design language

Parent entry: DESIGN.md (product posture, tokens map, anti-pattern summary).

This document is shell-only: desktop scene, top bar, dock, window system, and embed boundaries. Sub-app content rules live in app-design-language.md.

Visual language (shell)

The shell should feel precise, calm, and hardware-ordered: clear stacking, readable controls, thin borders and light shadow before heavy elevation, subtle glass that supports depth (not decoration). Neutral surfaces with restrained accent; accent signals action or system emphasis, not decoration.

Do not clone macOS/Windows/iOS metaphors (traffic lights, Start menu, home grid). Take inspiration from real OS ergonomics without copying trademark UI.

Shell composition

Desktop scene

Spatial host for work: wallpaper / gradient field (--os-desktop-background), optional atmospheric overlay, and normalized window stacking. The scene should imply stable space — edges, safe margins, and max width (--os-desktop-max-width) where the layout demands it.

Top bar (RuntimeCommandStrip)

Global band for identity, shell status, primary navigation anchors, and future command entry. Stays visually lighter than window titlebars; uses compact control height tied to --os-runtime-command-strip-height and density. New shell sessions default to top placement; user placement preferences only affect Desktop Runtime RuntimeCommandStrip, not the public landing nav.

Dock

Launcher strip: persistent apps, temporary running apps, running affordance, and app identity at a glance. Persistent apps remain visible even when closed and should not look disabled or show a running dot until a window exists. Temporary apps appear after a divider when they are running but not kept in Dock. Uses dock-radius (--os-radius-dock) and bottom-safe offsets so it floats above the workspace without fighting window corners.

The Dock belongs to Desktop Runtime, not to the public landing page and not to every Studio Engine. It is a separate floating launcher surface, visually close to a macOS-style icon list without copying the host OS. The existing floating surface position preference controls whether it sits on the bottom, top, left, or right edge. The RuntimeCommandStrip remains a command/status/navigation surface instead of carrying app icons.

Window grammar

• Frame: rounded outer shell (--os-radius-window), titlebar height (--os-titlebar-height), window shadow (--os-shadow-window) for elevation over desktop.
• Body: WebsiteAppHost and similar use --os-window-body-background and --os-window-body-padding so content is inset consistently across density.
• Chrome: custom macOS-adjacent traffic-light controls and drag targets live in @prox-os/os-ui (WindowFrame, Titlebar, WindowControls). The controls are Próx shell components, not browser or host OS widgets.

Active / inactive states

Active window: stronger border/contrast, title readability, shadow read as “foreground”. Inactive: toned ink, softer border, no loss of structure — user must still identify the app and recover focus quickly.

Focus, layer, resize, drag

• Focus: keyboard and pointer focus rings stay subtle (thin ring / high contrast on neutral), no neon halos.
• Layering: z-order follows window manager rules; shell popovers, menus, and tooltips sit above frames; toast / system notices use panel/window shadow tokens.
• Drag / resize: interactions should be interruptible and low-latency (react-rnd etc.); ghosting or lag is a bug, not a feature.
• Snap geometry: snapped, quartered, fullscreen-space, and desktop-filled windows use the measured workspace bounds with zero visual inset. Readability padding belongs to initial/default placement, not drag clamping or snapped rendering. Floating windows may touch every workspace edge.

Scenes And Mission Control

The shell now separates Studio switching from Scene switching. Studio switching is the global resource layer. Scenes are layout states inside the active Studio. Mission Control should feel like a calm OS-level overview, not a marketing hero:

• Control Shift Up: open Prox Mission Control. The top band shows Studio sessions; the main area shows Scenes for the active Studio.
• Control + ,/.: move to the previous or next Scene inside the active Studio.
• Control Shift + ,/.: move to the previous or next Studio session.
• Titlebar double-click zooms the window inside the current Desktop Runtime Scene.
• The green titlebar control enters focus or full presentation for the active App. Hovering it on the active window opens the window resize menu; inactive windows reveal traffic-light colors on hover without opening menus.
• Mission Control Scene thumbnails show a hover affordance when a Scene can be selected or created. Studio session cards stay visible as the global context layer.

Mission Control thumbnails must reuse the active desktop background token (--os-desktop-background) when previewing Desktop Runtime Scenes so they read as miniature work states, not generic white cards. Other Studio Engines can provide engine-specific Scene previews while preserving the shared overlay structure.

Dragging a window to the top edge and holding there can open Mission Control as a Scene drop target. Existing Scene thumbnails use a selected state when hovered as a drop target; insertion positions show a translucent temporary Scene with a + between or outside the current Scene queue.

Window edge snap should remain readable and predictable: corners produce quarter layouts, left/right edges produce half layouts, and the top edge toggles desktop zoom. The pointer activation band is intentionally narrow so normal dragging near the workspace does not snap accidentally. A previously snapped window must not re-snap unless the pointer is currently inside an activation band. The resize menu also exposes top-half and bottom-half placement for deliberate keyboard-free arrangement. Dragging an already desktop-zoomed window restores the previous layout before the drag continues.

Desktop zoom, fullscreen Space presentation, titlebar double-click zoom, and snap-to-fill must keep the same rounded WindowFrame grammar as ordinary windows. These states may remove body padding for content fit, but they must not remove the outer radius or create a visual bottom gap.

The resize menu uses compact icon tiles instead of text-heavy directional rows. Its sections are Move & Resize, Fill & Arrange, and a Full Screen submenu so common window placement, desktop zoom, centering, and focus presentation remain in one active-window affordance.

The Storybook contract for this behavior is Shell/WindowSnapGeometry. Use it when changing @prox-os/os-ui window geometry, Desktop Runtime window rendering, Alma workspace measurement, or snap preview styling.

Runtime Command Strip popovers, including future locale or translation controls, must be fixed/portal positioned against the trigger and clamped to the viewport. Do not attach absolute popovers inside the Runtime Command Strip overflow container.

Use lightweight blur only on the top strip, avoid stacking blur over every window, and respect prefers-reduced-motion.

Website Mode

Website mode is a single-app browsing surface using /website route suffixes. App Studio and focused App presentation are separate from Website mode.

Landing Navigation

The public homepage uses its own immersive glass navigation. It is product navigation for a Solutions Studio menu, Community, Docs, Pricing, Alma, sign-in, and Launch OS. It must not reuse ShellTopbar or host the Dock. Runtime Shell chrome starts after the user enters an OS or Studio route.

Studio Surface Shell

Heavy Studio Engines and windowed Studio modes render inside StudioSurfaceShell: an outer workspace background with responsive padding and an inner rounded, bordered, shadowed frame. The engine can still use 100% width and height inside that frame. This keeps Studio spaces visually bounded, differentiates global shell navigation from local Studio work, and leaves a clear future escape hatch for focus or fullscreen mode.

The inner frame is also a stacking boundary. Studio-local app dialogs, fixed menus, and high z-index content remain inside the Studio frame and below shell-owned global dialogs. Desktop Runtime renders its floating Dock inside this bounded frame, not in the homepage nav or outside the runtime container.

Local vs iframe / micro apps

The shell hosts local modules and iframe (or remote) surfaces. Boundary: shell owns frame, drag stack, and manifest; hosted app owns interior pixels. Communication crosses app contract, embed URL, or postMessage patterns — not private shell imports.

Technology position

Bundler-agnostic language. Current stack: React, TypeScript, Tailwind CSS v4 (PostCSS), Rsbuild in apps/os-shell. Do not couple look-and-feel to Rsbuild.

UI library policy

Shell chrome is implemented with custom composition in packages/ui/os-ui, backed by packages/ui/design-tokens.

Later allowances: Radix-style primitives for accessibility, Floating UI for positioning, Motion for short functional transitions.

Avoid large visual kits for OS chrome. Sub-apps may adopt other UI libraries when appropriate; shell stays opinionated.

Animation

Motion is subtle, fast, interruptible, functional. Do not use motion to mask unclear state. Respect prefers-reduced-motion (global overrides exist in shell App.css).