UI Components & Design System
Relevant source files
The following files were used as context for generating this wiki page:
The mausVoice UI Components & Design System follows an Operate-mode philosophy, prioritizing tool utility and high-density information display over decorative aesthetics. It is a cross-platform system built using React and Material UI (MUI), optimized for desktop performance with a "Rust is the API, TypeScript is the Brain" architectural split.
The system is characterized by a "cream paper" light mode and an "onyx" dark mode, utilizing a 4-step surface elevation ladder driven by luminance rather than shadows. It integrates native-level desktop features like custom title bars and global hotkey indicators to remain functional while staying out of the user's primary workflow.
Sources: apps/desktop/DESIGN.md:3-8, apps/desktop/PRODUCT.md:3-10, llms.txt:30-36
Core Visual Language
Surface Ladder and Elevation
mausVoice uses a specific 4-tier surface elevation system. Instead of standard shadows, surfaces are primarily separated by 1px translucent hairlines (hairline.light and hairline.dark). Elevation shadows, referred to as premiumSurface, are reserved for layered or floating elements like cards and hover states.
| Tier | Light (Cream) | Dark (Onyx) | Description |
|---|---|---|---|
| Level 0 | #F5F2ED | #0C0C0D | Main application background |
| Level 1 | #FDFBF8 | #161617 | Primary surface container |
| Level 2 | #ECE8E1 | #1F1F21 | Raised elements |
| Level 3 | #E0DBD2 | #2A2A2C | Elevated/Floating elements |
Sources: apps/desktop/DESIGN.md:10-22, apps/desktop/index.html:15-32
Color Palette and Accents
The system is intentionally restrained, featuring only one primary accent color: Blue.
- Primary Action Blue:
#1B8AF8(Light) /#3198FF(Dark). - Status Indicators:
Goldfor rewards/inactive features andRedfor destructive actions. - Neutral Palette: Tints are derived from
ink(α)(rgba(26,23,18,α)) in light mode andhighlight(α)in dark mode. Pure black (#000) and pure white (#FFF) are avoided for surfaces to reduce eye strain.
Sources: apps/desktop/DESIGN.md:32-40
Typography and Spacing
Font Families
The design system utilizes two main font families to distinguish between branding and functional UI.
- UI/Body Face:
SatoshiorPlus Jakarta. Thetabular-numsproperty is applied globally to prevent width jitter in timers and metrics. - Display Face:
TAN-PARADISO. Reserved strictly for the logo wordmark and the welcome screen. - Technical Content:
JetBrains Monois utilized for monospaced content and coding examples.
Sources: apps/desktop/DESIGN.md:44-50, index.html:62-117, apps/desktop/PRODUCT.md:21-25
Layout Geometry
Standardized dimensions ensure consistency across the desktop application:
- Rail Sidebars: 224px – 240px wide.
- Icons: 22px stroke nodes (primarily Lucide).
- Dense Rows: 32px – 36px height.
- Spacing: A 4px base rhythm.
- Border Radius: 14px for cards; smaller semantic values for MUI controls.
Sources: apps/desktop/DESIGN.md:50-56
Theme Implementation and Hydration
The system uses a pre-hydration script to prevent "white flashes" during application startup. It resolves the persisted user theme (light, dark, or system) from localStorage and applies a data attribute to the HTML element before the React bundle is painted.
The diagram shows the logic for resolving the theme mode during the initial HTML load to ensure the background color matches the user's preference immediately.
Sources: apps/desktop/index.html:43-85, apps/desktop/src/main.tsx:109-119
Interaction Components
Functional Layouts
The system uses standardized components for list-heavy interfaces, such as the ScrollListPage. These components handle empty states, loading indicators, and actions consistently.
- AppStylingLayout: Manages writing styles per application. It uses
useAppStoreto access Zustand state andloadTonesactions to fetch data. - ManualAddStyle: Allows users to manually create custom refinement rules.
- HotkeyBadge: A specialized component that displays keyboard shortcut combinations, helping users discover how to cycle styles via
SWITCH_WRITING_STYLE_FORWARD_HOTKEY.
Sources: apps/desktop/src/components/styling/AppStylingLayout.tsx:18-60, apps/desktop/src/components/styling/ManualStylingLayout.tsx:13-35
The Recording Pill
The "Pill" is the primary native overlay showing the application state. It uses height and native channels to convey information rather than complex animations.
- States: Recording, Transcribing, Done.
- Visuals: Sine-wave waveforms (270.1 x 72.9 px) driven by a specialized sine engine.
Sources: apps/desktop/DESIGN.md:62-65, index.html:920-940, apps/desktop/PRODUCT.md:12-16
Implementation Details
Theme Provider Configuration
The application is wrapped in a ThemeProvider using a custom theme and THEME_PROVIDER_CONFIG.
// apps/desktop/src/main.tsx:112-119
<IntlProvider {...intlConfig}>
<ThemeProvider theme={theme} {...THEME_PROVIDER_CONFIG}>
<CssBaseline />
{children}
</ThemeProvider>
</IntlProvider>
CSS Baseline and Global Overrides
- Scrollbars: Themed from the palette to match the "cream/onyx" aesthetic.
- Focus Visible: 2px offset brand-tinted rings.
- Press Feedback: All interactive elements use a
scale(0.97)transform on active states. - Reduced Motion: Honored via
prefers-reduced-motionmedia queries; keyboard-invoked actions never animate.
Sources: apps/desktop/DESIGN.md:60-70, apps/desktop/src/main.tsx:115
Conclusion
The mausVoice design system is a highly specialized "Operate-mode" framework. By strictly adhering to its surface ladder and typographic constraints, the system maintains a professional, tool-like feel that integrates seamlessly into the user's desktop environment while minimizing cognitive load through consistent micro-interactions.