UI Glossary

Standard terminology for Zus shell, components, and interaction patterns. Use these terms in code, issues, specs, and help docs.

Shell and Layout

Term Meaning
Shell The outermost application frame. Renders toolbars, sidebars, and the main content area from a view descriptor. Component: ZuiShell.
View Descriptor A pure-data object that declares a page layout (which panels go where, what toolbar items appear). No React — just structure. Lives in .zui.ts files.
Sidebar A collapsible panel docked to the left or right edge of the shell. Resizable via drag handle. Clips content on collapse (no reflow). Component: SidebarPanel.
Inspector The right-side sidebar. Currently hosts the AI Chat panel. Same mechanics as the left sidebar.
Workspace The flex container that holds left sidebar + main content + right sidebar. Component: Workspace.
Main Content Area The central region between sidebars. Fills available space. Hosts the detail panel (document browser or editor).
Toolbar Horizontal bar at the top or bottom of the shell. Contains actions, toggles, status indicators, and dividers. Declared in the view descriptor.
Status Indicator A read-only display in the toolbar (e.g., word count, keymap mode). Registered via registerStatus().

Perspectives

The shell uses a cascading master-detail model with two perspective positions:

Term Meaning
Position A (Browsing) [ Navigator | Document Browser ] — the user is navigating folders and browsing documents. The left sidebar shows the Navigator; the main content area shows the Document Browser.
Position B (Editing) [ Document Content Navigator | Editor ] — the user is editing a document. The left sidebar swaps to the Document Content Navigator; the main content area shows the Editor.
Perspective Transition The animated swap between Position A and Position B. Opening a document transitions A → B; the editor back button transitions B → A. Navigator state (expanded folders, scroll position) is preserved across transitions.

Navigator

Term Meaning
Navigator The generic, data-model-agnostic tree-view component. Renders any hierarchical data as an interactive tree. Does not know about folders, documents, or any domain. Component: Navigator.
Navigator Panel The folder-tree sidebar panel shown in Position A. A consumer of Navigator — transforms folder/section NodeRecords into NavigatorNodes and provides domain callbacks (rename, delete, import, etc.). Component: NavigatorPanel. Panel ID: navigator.
Row A single interactive line in the navigator tree. Displays: disclosure triangle, icon, name, optional count badge, optional ellipsis button.
Section Header A non-interactive grouping label in the navigator (e.g., "Notes", "Shared"). Rendered for nodes with kind: 'section'. Cannot be selected, collapsed, or renamed.
Disclosure Triangle The expand/collapse control to the left of a row's icon. Rotates 90° when expanded. Clicking it toggles children without selecting the row. Only appears on rows with children.
Count Badge A small number displayed to the right of a row's name, showing the count of items (e.g., documents in a folder). Hidden when zero or undefined.
Ellipsis Button The three-dot (...) context menu trigger. Appears on hover, opens the action menu. Uses press-and-hold interaction pattern (Apple HIG). Component: EllipsisButton.
Inline Edit In-place text editing for rename operations. Replaces the name label with an input field. Enter commits, Escape cancels, blur commits. Component: InlineEdit.
Drop Target A navigator row highlighted as a valid destination during a drag operation. Indicated by outline + background. The navigator does not initiate drags — it only highlights targets.

Document Browser

The Document Browser is the main content view in Position A. It displays the contents of the selected folder in one of two view modes.

Term Meaning
Document Browser The view-mode switcher panel that renders either the Gallery or List view based on workspace.document.viewMode. Component: DocumentBrowserPanel. Panel ID: document-browser.
Gallery View A responsive card grid showing document preview cards for the selected folder. Includes a header (folder name + count). Component: DocumentGridPanel.
List View A tabular list of documents for the selected folder, with columns for title, date, and other metadata. Component: DocumentListView.
Document Preview Card A single card in the gallery view. Fixed dimensions, shows a rendered content snapshot and metadata (title + date). Clicking opens the document in the editor with an expand transition. Component: DocumentCard.
Card Preview The content preview area inside a document preview card. Renders a non-interactive snapshot of the document's formatted content. Component: CardPreview.
Document Preview The read-only document preview shown in the right sidebar when the Document Browser is in list view. Renders the selected document using the Editor in read-only mode. Component: DocPreviewPanel. Panel ID: doc-preview.
Marquee Selection Drag-to-select interaction in the gallery. Dragging from empty space draws a selection rectangle. Cards intersecting the rectangle are selected.

Document Content Navigator

Term Meaning
Document Content Navigator The sidebar panel shown in Position B (editing). Displays a navigable outline of the open document's structure. Clicking an entry scrolls the editor to that section. Currently a stub showing the document title; full heading-tree implementation is a follow-up. Component: DocTocPanel. Panel ID: doc-toc.

Editor

Term Meaning
Editor The Slate-based rich text editor. One editor instance per open document. Component: Editor.
Editor Panel The detail panel that hosts the editor when a document is open. Component: EditorPanel. Panel ID: editor.
Content Panel The routing panel for the main content area. Switches between Document Browser (Position A) and Editor (Position B). Orchestrates the expand/collapse transition animation between perspectives. Component: ContentPanel. Panel ID: content.

Menus and Overlays

Term Meaning
Action Menu A popover menu anchored to a trigger element (ellipsis button, toolbar button, etc.). Displays a list of labeled actions with optional icons. Viewport-aware positioning. Component: ActionMenu.
Drag Overlay A floating card preview that follows the pointer during cross-panel drag operations. Scales down (40%) when entering the navigator zone. Shows a count badge for multi-drag. Component: DragOverlay.
Toast A transient notification bar at the bottom center of the shell. Auto-dismisses after 6 seconds. May include an action button (e.g., "Undo"). Component: Toast.

Selection States

Term Meaning
Focused Selection The selected navigator row when the navigator has keyboard focus. Accent-colored background with contrasting text. Driven by :focus-within.
Unfocused Selection The selected navigator row when focus is elsewhere (e.g., in the editor or gallery). Muted background with accent-colored text. The row is still selected, just visually quieter.
Card Selection One or more cards highlighted in the gallery. Orange border. Supports click, Cmd/Ctrl-click (toggle), Shift-click (range), and marquee drag. State: workspace.document.selectedDocIds.

Interaction Patterns

Term Meaning
Ambient UI The design philosophy where interface elements are invisible until needed. Controls fade in on hover/proximity and fade out when the pointer moves away. The interface disappears so the writer can focus on words.
Collapse Zone The region near a sidebar's minimum width where releasing a drag-resize snaps the sidebar fully closed, rather than leaving it at an awkward narrow width. Apple Notes-inspired.
Soft Delete Deletion that sets a deletedAt timestamp rather than removing data. Items disappear immediately from the UI. Reversible via toast undo or future trash view.
Pointer Events All custom drag interactions use the Pointer Events API (pointerdown/pointermove/pointerup), never HTML5 drag-and-drop. See pointer-events.md rule.
Frost Edge Frosted blur strips at the top and bottom edges of a scrollable panel. Provides a visual cue that content extends beyond the viewport. Uses backdrop-filter: blur() with gradient masks on pseudo-elements.

Data Model

Term Meaning
Node The universal entity in the storage tree. Every item — folder, section, document, resource — is a NodeRecord with id, type, name, parentId, and timestamps.
Section A top-level grouping node (type: 'section'). Non-interactive in the navigator. Contains folders. Example: "Notes", "Shared".
Folder A container node (type: 'folder'). Interactive in the navigator — can be selected, expanded, renamed, deleted. Contains documents and subfolders.
Document A node (type: 'document') whose content is stored separately in the content store. The node holds metadata and tree position; the content store holds the markdown/CRDT data.

Design Tokens

Category Pattern Example
Colors --color-{name} --color-text-primary, --color-accent
Selection --color-selection-{state}-{property} --color-selection-focused-bg
Typography --font-family-{variant}, --font-size-{name} --font-family-sans, --font-size-h1
Spacing --spacing-{name} --spacing-block-gap
Animation --transition-{name}, --duration-{name}, --easing-{name} --transition-sidebar, --easing-ambient
Shadows --shadow-{name} --shadow-popover
Layout --{component}-{property} --sidebar-default-width, --content-width

Naming Conventions