App UI & Views

Relevant source files

The following files were used as context for generating this wiki page:

• apps/desktop/Sources/Crisp/Views/ContentView.swift
• apps/desktop/Sources/Crisp/Views/SettingsView.swift
• apps/desktop/Sources/Crisp/Views/Components/Card.swift
• apps/desktop/Sources/Crisp/Views/Onboarding/OnboardingView.swift
• apps/desktop/Sources/Crisp/Views/WhatsNewView.swift
• apps/web/src/components/AppWindow.tsx
• CLAUDE.md

The Crisp User Interface is built using native macOS technologies, primarily SwiftUI for the desktop application and React/Tailwind for high-fidelity web recreations used in marketing. The design philosophy emphasizes a "Native, Apple-like" aesthetic, utilizing SF Symbols, standard system materials, and consistent spacing to ensure the app feels like an integrated part of the macOS ecosystem.

The UI is architected into three primary layers: Services (logic), Models (data), and Views (display). Views are strictly responsible for display, observing changes from @Observable services like CleanModel and EngineSettings to update the interface in real-time. Shared visual primitives, such as the .cardBackground modifier, ensure a unified look across the workspace, onboarding, and settings windows.

Sources: CLAUDE.md:121-137, apps/desktop/Sources/Crisp/Views/Onboarding/OnboardingView.swift:239-258

Core View Architecture

The desktop application UI is organized into distinct specialized views, each handling a specific stage of the user lifecycle or a focused configuration task.

Main Workspace (ContentView)

The ContentView serves as the primary interaction hub. It composes several modular components to facilitate the video cleaning workflow, including drop zones for file input, option cards for cutting strength, and progress sections for active operations.
Sources: CLAUDE.md:135-137, apps/web/src/components/AppWindow.tsx:35-103

Onboarding Flow (OnboardingView)

A multi-step, paged tour that appears on first launch. It guides the user through feature explanations (capabilities, fidelity), initial setup (speech model installation), and automation preferences (Finder actions, Watch folders).
Sources: apps/desktop/Sources/Crisp/Views/Onboarding/OnboardingView.swift:10-23

Settings & Configuration (SettingsView)

A standard macOS tabbed preferences window (accessible via ⌘,) organized into logical sections:

• Cutting: Custom thresholds for pauses and silence.
• Output: Encoder settings (H.264, HEVC, VP9) and container choices.
• Automation: Management of the background Watch folder and Menu Bar icon.
• General: Updates, licensing, and diagnostic logs.
  Sources: apps/desktop/Sources/Crisp/Views/SettingsView.swift:15-60

Visual Components & Design System

Crisp utilizes a custom design system built on top of SwiftUI primitives to maintain a "dark, cinematic" identity.

Card System

The primary container for UI elements is the "Card." It uses a specific radius (12–14) and materials like .regularMaterial or .quaternary.
Sources: CLAUDE.md:204-206, apps/desktop/Sources/Crisp/Views/Components/Card.swift

UI Hierarchy & Data Flow

The following diagram illustrates how user interactions in the View layer flow through to the underlying Engine via Services.

The UI observes @Observable objects, ensuring that when the Python engine emits progress via NDJSON, the ProgressSection in the UI updates automatically without manual state management.
Sources: CLAUDE.md:123-137

Feature-Specific UI Modules

Module	Key Components	Purpose
Onboarding	ModelInstallControl, featureRow	Handles first-run setup and model downloads.
Cutting UI	StrengthPicker, KnobSlider	Allows users to choose between Gentle/Aggressive presets or Custom values.
Encoding UI	Picker, Toggle	Configures hardware acceleration, codecs (AAC, Opus, H.264), and bitrates.
Automation	WatchAgentController, LaunchAgent	Manages background services for automatic folder cleaning.

Sources: apps/desktop/Sources/Crisp/Views/SettingsView.swift:85-150, apps/desktop/Sources/Crisp/Views/Onboarding/OnboardingView.swift:230-260

Multi-Step Onboarding Logic

The OnboardingView uses an internal state machine to manage transitions between educational and functional steps.

Technical Implementation Details

Custom Settings Binding

The UI uses specialized bindings to intercept user actions, such as warning when a user selects 10-bit color depth for 8-bit sources.
Sources: apps/desktop/Sources/Crisp/Views/SettingsView.swift:39-50

// Example of Intercepting Binding in SettingsView.swift:39
private var colorDepthBinding: Binding<String> {
    Binding(
        get: { settings.colorDepth },
        set: { newValue in
            if ColorDepth(rawValue: newValue)?.warnsOnSelect == true {
                confirmForce10 = true // Triggers a confirmation sheet
            } else {
                settings.colorDepth = newValue
            }
        }
    )
}

Web Recreation

The AppWindow.tsx file provides a functional recreation of the ContentView.swift for the marketing site, mirroring the 24pt padding and 16pt stack spacing defined in the desktop app.
Sources: apps/web/src/components/AppWindow.tsx:1-5

Conclusion

The Crisp UI & Views system prioritizes a native macOS experience while abstracting the complexity of the underlying Python-based cleaning engine. By leveraging SwiftUI's data-driven nature, the interface remains reactive and consistent across the main application, onboarding, and background automation status.