Main Window & Navigation Layout
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Main Window & Navigation Layout of MacParakeet defines the primary user interface structure and navigation paradigms used to interact with the application's core speech-to-text and AI features. It is designed to follow a "premium enterprise-grade" aesthetic, prioritizing findability and a "Linear-grade" experience for power users on macOS. Sources: plans/active/2026-04-settings-ia-overhaul.md.
The layout utilizes a primary sidebar for high-level navigation between modes (Transcribe, Library, Dictation) and utility views (Vocabulary, Settings). Within these views, the application employs a mix of grid-based card layouts for media selection and split-pane detail views for content analysis and interaction. Sources: plans/completed/2026-03-video-player-and-transcription-ui-revamp.md, spec/04-ui-patterns.md.
Primary Navigation Structure
The application's top-level navigation is anchored by a sidebar that organizes features into logical groups. This sidebar facilitates rapid switching between recording, library management, and system configuration.
Sidebar Organization
The sidebar is tinted with the "coral" brand accent to maintain visual consistency and indicate selection status. Sources: plans/completed/vocabulary-surface-refinement.md.
| Navigation Item | Description | Source |
|---|---|---|
| Transcribe | The home page containing primary input cards for YouTube URLs and Local Files. | spec/README.md |
| Library | A grid-based repository of all historical transcriptions, filterable by source type. | spec/README.md |
| Dictations | A historical list of voice dictations, typically grouped by date. | spec/README.md |
| Vocabulary | Management of custom words, text snippets, and processing rules. | spec/04-ui-patterns.md |
| Settings | A tabbed, searchable interface for application-wide configuration. | plans/active/2026-04-settings-ia-overhaul.md |
Navigation Flow Diagram
The following diagram illustrates the primary navigation paths from the Sidebar to specific functional modules.
Home Page & Transcription Input
The "Transcribe" home page uses a side-by-side card layout to differentiate between the two primary ways to initiate a transcription task. Sources: plans/completed/2026-03-video-player-and-transcription-ui-revamp.md.
Input Cards
- YouTube Card: Contains a URL text field, a paste button, and an action button to trigger the analysis.
- Local File Card: Features a drag-and-drop zone and a "Select File" button for local media.
Sources: plans/completed/2026-03-video-player-and-transcription-ui-revamp.md.
Recently Transcribed Grid
Below the input cards, the home page displays a grid of "thumbnail cards" for recently completed tasks. Each card provides a visual preview (YouTube thumbnail or extracted video frame) along with metadata like duration and title. Sources: plans/completed/2026-03-video-player-and-transcription-ui-revamp.md.
Content Detail Layouts
When a user selects a transcription from the Library or finishes a new one, the application transitions to a detail view. This view is adaptive, changing its layout based on the media type (Video vs. Audio). Sources: plans/completed/2026-03-video-player-and-transcription-ui-revamp.md.
Video Mode (Split-Pane)
For YouTube or local video files, a 40/60 split-pane layout is used. The video player occupies the left pane, while the right pane contains a tabbed content area for the transcript, summary, and AI chat. Sources: plans/completed/2026-03-video-player-and-transcription-ui-revamp.md.
Audio Mode (Full-Width)
For audio-only files, the layout is full-width. A compact, ~44px horizontal "audio scrubber bar" is pinned to the top, providing playback controls and a waveform. The remainder of the vertical space is dedicated to the tabbed content area. Sources: plans/completed/2026-03-video-player-and-transcription-ui-revamp.md.
Component Architecture
Settings Information Architecture
The Settings surface underwent a significant overhaul to transition from a single-scroll card list to a tabbed and searchable interface. Sources: plans/active/2026-04-settings-ia-overhaul.md.
Tabbed Organization
| Tab | Primary Contents |
|---|---|
| Modes | Audio input, Dictation hotkeys, Transcription settings, Meeting recording configuration. |
| Engine | Speech recognition engine selection (Parakeet/Whisper), language defaults, and model management. |
| AI | LLM provider configuration (Claude/OpenAI/Ollama) and prompt formatter settings. |
| System | Startup behavior, Permissions dashboard, Storage stats, and destructive Reset actions. |
| Sources: plans/active/2026-04-settings-ia-overhaul.md |
Search and Navigation
Settings features a "search escape hatch" accessible via ⌘F. When active, the tabbed layout collapses into a flat list of results. Selecting a result navigates the user to the specific tab and scrolls the relevant card into view with a 200ms accent-color flash. Sources: plans/active/2026-04-settings-ia-overhaul.md.
Visual Design & Polish Patterns
The application enforces a strict "coral discipline" where the brand accent is used for calls-to-action (CTAs) and recording state indicators, but removed from secondary chrome like focus rings and selection backgrounds. Sources: plans/completed/2026-05-restrained-brand-apple-grade-polish.md.
- Button Roles: Buttons are semantically categorized into
.primary(coral),.secondary(neutral), and.destructive(red). Sources: plans/completed/2026-05-restrained-brand-apple-grade-polish.md. - Materials: Floating elements like sheets and popovers utilize
.thickMaterialor.regularMaterialto achieve a native macOS aesthetic. Sources: plans/completed/2026-05-restrained-brand-apple-grade-polish.md. - Status Awareness: Navigation tabs and card headers use status chips (green/yellow/red) to indicate required actions or system health without cluttering the primary UI. Sources: plans/active/2026-04-settings-ia-overhaul.md.
Conclusion
The navigation layout of MacParakeet is designed to support both high-frequency dictation tasks and deep content analysis. By utilizing adaptive layouts for different media types and a centralized, searchable settings architecture, the system provides a clear hierarchy that scales as the user's library of transcriptions and recordings grows.