UI Components and Shared Systems

Overview of shared UI components and system-wide utilities that power the ryOS desktop environment.

Overview

The ryOS component architecture is organized into distinct categories, each serving specific purposes across the desktop environment. Components are built with React and TypeScript, leveraging Tailwind CSS for styling and shadcn/ui as the foundation for consistent, accessible UI elements. The system emphasizes reusability, theme-aware components, and cross-app compatibility.

The component library is structured hierarchically: base UI components provide fundamental building blocks, layout components handle window management and desktop structure, dialog components manage modal interactions, shared components offer cross-application utilities, and error components provide crash recovery surfaces. This organization ensures consistent behavior and appearance across all 20 built-in applications while maintaining flexibility for app-specific customizations.

Component Categories

Category	Description	Location
UI Components	shadcn-based components and custom primitives	`src/components/ui/`
Layout Components	Window frames, desktop layout, menu bars	`src/components/layout/`
Dialog Components	Modal dialogs, alerts, and system dialogs	`src/components/dialogs/`
Shared Components	Cross-app utilities and themed components	`src/components/shared/`
Error Components	App/desktop error boundaries with crash dialogs	`src/components/errors/`

graph LR
    subgraph src/components
        UI[ui/]
        Layout[layout/]
        Dialogs[dialogs/]
        Shared[shared/]
        Errors[errors/]
    end
    
    UI --> |primitives| Layout
    UI --> |primitives| Dialogs
    UI --> |primitives| Shared
    UI --> |primitives| Errors
    Layout --> |frames| Apps[src/apps/]
    Dialogs --> |modals| Apps
    Shared --> |utilities| Apps
    Errors --> |crash recovery UI| Apps

Technologies

React 19 with TypeScript for type-safe component development

Tailwind CSS for utility-first styling and theme support
shadcn/ui component library for accessible, customizable UI primitives
Framer Motion for animations and transitions

Component Architecture

The UI system follows a layered approach:

Base Layer: shadcn/ui components (19 components: button, dialog, input, select, etc.) provide accessible, themeable primitives

Custom Layer: Specialized components (10 components: activity-indicator, aqua-checkbox, audio-bars, dial, playback-bars, etc.) extend functionality for app-specific needs
Layout Layer: WindowFrame, MenuBar, Desktop, and Dock components manage the desktop environment structure
Application Layer: Dialog, shared, and error components provide common patterns used across multiple apps (including runtime crash recovery)

graph TD
    subgraph Layer 4: Application
        D1[Dialog Components]
        D2[Shared Components]
        D3[Error Boundaries
Crash Dialog]
    end
    
    subgraph Layer 3: Layout
        C1[WindowFrame]
        C2[MenuBar]
        C3[Desktop]
        C4[Dock]
    end
    
    subgraph Layer 2: Custom
        B1[activity-indicator]
        B2[aqua-checkbox]
        B3[audio-bars]
        B4[dial]
        B5[playback-bars]
        B6[volume-bar]
        B7[audio-input-button]
    end
    
    subgraph Layer 1: Base
        A1[shadcn/ui]
        A2[button, dialog, input, select, ...]
    end
    
    A1 --> B1 & B2 & B3 & B4 & B5 & B6 & B7
    B1 & B2 & B3 & B4 & B5 & B6 & B7 --> C1 & C2 & C3 & C4
    C1 & C2 & C3 & C4 --> D1 & D2 & D3

All components are theme-aware, automatically adapting to the active system theme (System 7, Mac OS X, Windows XP, Windows 98) through the theme system.

Subsections

Component Library - Core UI component library including 19 shadcn components, 10 custom primitives, 16 shared components, and crash boundary components

Internationalization - i18n hooks and translation system supporting 10 languages