Historical archive

This page records a dated plan, audit, or research context, not a current product contract. Project status distinguishes current source behavior, published releases, and unfinished acceptance gates.

macOS UX surface table

The bar every SummonOS app and every app Summon makes is measured against. Each column is one kind of surface a Mac app can show; each row is one UX dimension. Pick the column for what you are building, then read down it.

This is the table as Rohi gave it on 2026-10-25, with only spacing typos fixed. Numbers here (sizes, timings, point sizes) are targets from practice, not Apple rules. The per-surface pages in this folder check each cell against Apple's documentation and the HIG, and say where a cell is an Apple rule, a common convention, or wrong; when a surface page and this table disagree, the surface page wins. The ten corrections are listed in Findings.

UX / UI Dimension	1. Menu Bar App (MenuBarExtra / Popover)	2. Full Desktop App (NSWindow / Main Workspace)	3. Settings Window (Settings Scene)	4. Command Launcher (NSPanel / Spotlight Style)	5. Floating HUD / PiP (NSPanel / Always-on-Top)	6. Onboarding Wizard (First-Run Flow)	7. System Extensions (Notch, Widgets, Finder)
Core Philosophy & Mental Model	Zero-Friction Utility ("Peek & Pop"): Instant 3-second interactions, status checks, and quick toggles without leaving the current task.	Deep Workspace ("Focus & Create"): Primary environment for sustained work, heavy content management, editing, and complex analysis.	Control & Calibration ("Set & Forget"): Visited occasionally to configure behavior, shortcuts, permissions, and accounts. Clarity over flair.	Speed & Execution ("Type & Go"): Keyboard-driven central command bar. Zero mouse usage; summon, type intent, execute, vanish.	Ambient Companion ("Monitor & Drop"): Persistent mini-overlay that stays visible while working in other apps (recording, timers, drop shelf).	Trust & Activation ("Guide & Permit"): Smooth 60-second setup that explains value, secures macOS permissions, and shows where the app lives.	Invisible Integration ("In-Context"): Brings the app's power directly into the OS (Desktop, Notch, Right-Click menu) without opening the app.
Window Anatomy & Traffic Lights	Frameless Popover: No Title Bar, no Traffic Lights (Red/Yellow/Green). Anchored to the top Menu Bar icon with an arrow or sleek border.	Full Standard Window: Unified Title Bar + Toolbar, all 3 Traffic Lights enabled, supports Sidebar + Main Canvas + Inspector split views.	Utility Window: Title Bar + Close (Red) & Minimize (Yellow) enabled; Full Screen (Green) disabled. Top Icon Tabs or Sidebar + Grouped Form.	Borderless Floating Panel: No Title Bar, no Traffic Lights. Giant search input at the top, dynamic results list below, shortcut hints in footer.	Micro-Panel / HUD: Hidden or hover-only mini Traffic Lights (or simple X button). Pill, circle, or rounded card shape with subtle border.	Centered Modal Window: Fixed frame, Close (Red) optional or deferred until completion, no Minimize/Zoom. Step progress indicator at the bottom.	OS-Defined Containers: Hardware Notch morphing box, standard macOS Widget rounded squares, or native Finder context menu rows.
Sizing, Grid & Resizing	Fixed & Compact: Width 260px–360px, dynamic height (max ~500px). Strictly non-resizable by the user.	Fluid & Responsive: minWidth: 800px, minHeight: 550px. Freely resizable, supports Full Screen, Split View, and Stage Manager.	Fixed Width, Dynamic Height: Width 480px–600px (Top Tabs) or 680px (Sidebar). Height animates smoothly per tab. Non-resizable width.	Fixed Width, Collapsible Height: Width 600px–750px. Starts as a 56px single bar; expands up to ~450px as search results populate.	Ultra-Compact & Draggable: 120px–320px footprint. Draggable from anywhere on its background; snaps magnetically to screen corners/edges.	Fixed Golden Ratio: Typically 640px × 440px or 720px × 480px. Centered on the active screen. Non-resizable.	Strict Apple Grid: Widgets follow Small/Medium/Large system dimensions; Notch UI matches exact MacBook camera housing width and expands down.
Window Lifecycle & Focus Behavior	Transient Focus: Clicking outside or pressing Esc closes it immediately. Does not change the active app Menu Bar at top-left.	Persistent Standard Focus: Remains open behind other apps when unfocused. Cmd + W closes window; Cmd + Q terminates the app.	Explicit Focus Theft: Must call NSApp.activate() when opened from Menu Bar so it never spawns behind browsers. Cmd + W closes Settings only.	Non-Activating Ephemeral Focus: Receives keystrokes over any active app (even Full Screen apps) and vanishes the millisecond focus is lost or Esc is pressed.	Floating Level (.floating / .statusBar): Always stays on top of regular windows without stealing keyboard focus from the app the user is typing in.	One-Time Lifecycle: Automatically launches on first boot; once completed, destroys itself and transitions seamlessly into the Menu Bar or Main App.	Event-Driven / Passive: Widgets refresh via background timelines; Notch expands on cursor hover; Share/Finder actions run headlessly and exit.
Themes, Colors & Vibrancy (Materials)	High Vibrancy (Popover Material): Heavy behind-window blur. Menu Bar icon must be a Template Image / SF Symbol (monochrome).	Layered Hierarchy: Sidebar Material (translucent) for navigation; opaque WindowBackgroundColor for main canvas to prevent eye strain.	Structured Contrast (Grouped Form): Neutral background with elevated translucent cards (ControlBackgroundColor). Supports Light/Dark/System override.	Ultra-Thick HUD Blur (HUDWindow): Deep translucent glass with a crisp 1px inner border (white 15% in Dark Mode) so it pops over busy windows.	Dark Bias / High Contrast: Usually forces Dark HUD styling (even in Light Mode) for video/audio overlays, or uses semi-transparent glass when idle.	Brand-Forward + Native: Clean native surface combined with rich visual illustrations, subtle gradients, or short looping video demos.	Pure Black (Notch) / System Adaptive: Notch UI uses #000000 True Black to blend invisibly with the physical camera cutout; Widgets adapt to Wallpaper tinting.
Typography & Hierarchy (SF Pro)	Compact Scale: Body 12pt–13pt, Headers 13pt Semibold, Captions 11pt Secondary. Tight line-height and 8pt–12pt padding.	Standard Desktop Scale: Body 13pt–14pt, Section Titles 17pt–22pt Bold, Sidebar items 13pt. Generous breathing room (16pt–24pt).	Form Alignment Scale: Labels 13pt Regular, Group Headers 12pt Semibold, Footnote descriptions 11pt SecondaryLabelColor.	Large Input Scale: Search query 18pt–22pt Light/Regular, Result titles 13pt–14pt Medium, Kbd shortcut badges 11pt Monospaced.	Tabular Numbers (monospacedDigit): Essential for timers, FPS, or audio meters (12pt–14pt) so numbers never jitter horizontally as they change.	Expressive Scale: Hero Titles 24pt–28pt Bold, Subtitles 14pt–15pt Secondary, clear step labels 13pt Medium.	Glanceable Scale: High-legibility bold metrics (16pt–24pt) and micro-labels (10pt–11pt) with zero text wrapping.
UI Controls & Visual Density	Control-Center Style: Thick sliders, pill buttons, icon grids, and quick hover rows. Minimal text input.	Full Native Toolkit: Tables, SplitViews, Toolbars, Segmented Controls, Inspectors, and multi-selection lists.	Standard Form Controls: Toggles/Switches, Checkboxes, Pop-up Menus, Steppers, and Shortcut Recorder inputs. No "Save" button (instant apply).	Zero-Chrome List: Keyboard-highlighted rows, inline parameter chips/tags, and an action sub-menu (Cmd + K) at the bottom-right.	Minimalist Micro-Controls: 2–4 icon-only buttons (Pause, Stop, Mute, Expand). Controls often fade out to 30% opacity until hovered.	Guided Steppers: Large Primary CTA button (Continue), visual permission cards with live status checkmarks, and "Skip for now" links.	Non-Scrolling Micro-Targets: Interactive Widget buttons (macOS Sonoma+) or immediate drop/play triggers inside the Notch.
Navigation & Keyboard Shortcuts	Global Hotkey + Arrows: Summoned via global shortcut. Up/Down arrows navigate, Enter triggers, Cmd + , jumps to Settings.	Full Menu Bar + Shortcuts: Complete top-left Menu Bar (File, Edit, View, Window, Help), Cmd + 1/2/3 tabs, Cmd + F search.	Cmd + , & Tab Focus: Universal Cmd + , trigger, Tab key cycling through controls, and optional search bar at top of Sidebar.	100% Keyboard Driven: Summoned via Cmd + Space / Opt + Space. Up/Down/Tab to traverse, Enter to run, Cmd + 1..9 for quick execution.	Global Action Hotkeys: Controlled primarily via background shortcuts (e.g., Cmd + Shift + R to stop recording) or direct single-click on the HUD.	Linear Forward Progression: Enter or Space advances to the next step; minimal backward navigation required.	Zero Navigation: Single-level immediate interaction (Hover → Click/Drop → Done).
Drag & Drop Interactions	Menu Bar Icon Drop Zone: Dragging files/text onto the top Menu Bar icon highlights it or auto-opens the popover after 0.4s to accept the drop.	Bi-directional Canvas Drop: Drag files in from Finder, reorder internal items with spring animations, and drag processed files back out.	Config & Asset Drop: Dropping .json backups, license files, or custom app icons onto designated wells.	File Action Piping: Dragging a file into the launcher loads the file as an argument (e.g., "Compress this video", "Convert to PNG").	Dynamic Drop Shelf: Can automatically appear on screen edge when the user starts dragging a file in Finder (shake cursor or drag to edge).	Interactive Demo Drop: Optional sandbox step ("Try dragging a file here to see how it works") to build muscle memory.	Notch Drop Tray & Finder Share: Dragging files directly into the physical MacBook Notch to store/convert them, or using Finder Right-Click Quick Actions.
Audio & Video Handling	Quick Switcher & Mini-Wave: Mic/Camera quick selector, live mini audio waveform, or instant Mute toggle.	Pro Timeline & Canvas: AVKit hardware player, multi-track scrubbing, Space play/pause, J/K/L shuttle speed, and batch export queues.	Hardware Calibration: Input/Output device dropdowns, Live Mic Level Meter (green/yellow/red), resolution/FPS/codec pickers, and output folder selector.	Headless Media Commands: Text commands like "Switch audio to AirPods", "Trim clipboard video", or quick audio snippet preview via Spacebar.	Live Camera Bubble & Recording Bar: Circular/rounded live webcam preview (PiP), live elapsed recording timer, and real-time voice reactivity ring.	Interactive Mic/Cam Test: Live camera mirror and microphone bounce test right inside the permission step so the user sees it working immediately.	Now Playing & Live Waveform: Expanding Notch media controller with album art and live audio visualizer bars.
States, Alerts & System Permissions	Inline Banners Only: Never trigger NSAlert modals from a popover: they detach and break focus. Use inline warning pills that link to Settings.	Attached Sheets (NSAlert.beginSheetModal): Modals slide down attached to the window title bar; Empty States show helpful illustrations + primary CTA.	Permissions Dashboard: Dedicated list of macOS permissions (Accessibility, Screen Recording, Mic) with Green/Orange status dots + Deep-Link buttons to System Settings.	Inline Toast / Status Footer: Errors or confirmations appear as a subtle 2-second status message in the bottom bar of the launcher without blocking input.	Visual State Borders: Glowing red border/dot when actively recording, pulsing amber when paused, or brief checkmark animation on file processing completion.	Step-by-Step Permission Handshake: Explains why each permission is needed before triggering the macOS system prompt, and auto-detects when the user toggles it on.	Graceful Fallback: If permissions or data are missing, Widgets/Notch show a clean single-click prompt: "Click to configure in App".
Context Menus & Secondary Actions	Right-Click on Menu Bar Icon: Left-click opens the visual Popover; Right-click opens a fast native NSMenu (Settings..., Pause App, Quit).	Rich Right-Click & Quick Look: Every item supports Right-Click context menus (NSMenu) and pressing Spacebar to preview files via native Quick Look.	Reset to Defaults: Subtle context action or button per section to restore factory settings, plus Export/Import Settings.	Action Panel (Cmd + K): Pressing Cmd + K on any selected result opens a secondary mini-menu with all alternative actions (Copy, Reveal in Finder, Delete).	Hover Gear / Right-Click: Right-clicking the floating HUD lets the user change opacity (25%–100%), resize (Small/Med/Large), or snap to another corner.	None: Keep the user focused strictly on the primary setup path without distracting secondary menus.	Native OS Context Menus: Standard Widget right-click (Edit Widgets...) and Finder Services / Quick Actions integration.
Motion & Micro-Animations	Instantaneous (<150ms): Zero-lag fade + subtle scale (0.96 → 1.0). Hover states highlight in 0ms.	Spatial Continuity (200–300ms): Smooth sidebar collapse, spring physics on list reordering, and fluid inspector drawers.	Height Morphing (200ms ease-in-out): Window height smoothly expands or shrinks when switching between top tabs while cross-fading content.	Zero-Latency Spring (<100ms): Appears instantly on keystroke; results list height animates smoothly without shifting the top search input box.	Magnetic Spring Physics: Flicking the HUD throws it smoothly to the nearest screen corner with natural deceleration (like iOS Picture-in-Picture).	Choreographed Polish: Smooth horizontal slide transitions between steps and a pointing bounce animation near the Menu Bar icon at the end so the user sees where the app lives.	Liquid Morphing (Spring): The Notch seamlessly expands outward from the black camera cutout using organic spring curves when hovered.
Performance, Memory & Battery Impact	Near-Zero Idle CPU (0.0%): Must sleep completely when the popover is closed. Stop all UI timers and animations the instant the popover hides.	Hardware Accelerated & Paged: Lazy-load large lists/grids, offload media processing to background threads/Metal, and support App Nap when minimized.	On-Demand Allocation: Destroy or deallocate the Settings view hierarchy from memory when the user closes the Settings window (Cmd + W).	Pre-Warmed in RAM: Keep the panel window initialized and hidden in memory so summoning it takes <16ms (1 frame at 60/120Hz ProMotion).	Throttled Refresh Rate: When idle, render at low frame rates; during active video/waveform feedback, use Metal/CoreAnimation layers to keep CPU usage under 3%.	Single-Use Disposal: Completely unload all onboarding assets, videos, and views from RAM once the user finishes the wizard.	Strict OS Memory Limits: Widgets and Finder extensions have tiny RAM caps (~30MB–50MB) enforced by macOS: keep assets lightweight and cached on disk.
Dock & App Switcher (Cmd + Tab)	Hidden (LSUIElement = YES): Invisible in the Dock and Cmd + Tab when operating purely as a Menu Bar utility.	Visible (.regular Policy): Full Dock icon with badge support, Dock right-click menu, and Cmd + Tab presence.	Runtime Policy Controller: Houses the toggle (NSApp.setActivationPolicy) allowing the user to switch between Menu Bar Only, Dock Only, or Both.	Hidden: Summoned purely via hotkey or Menu Bar icon; never clutters the Dock.	Hidden / Attached to Parent: Acts as a child utility window; never spawns a separate Dock icon or extra window entry in Mission Control.	Temporary Dock Presence: Can show in Dock during initial setup so the user doesn't lose the window while toggling System Settings, then hides into Menu Bar at the final step.	Zero Dock Presence: Managed entirely by macOS WidgetKit or System Extension daemons.