Design System & UI Components
Relevant source files
The following files were used as context for generating this wiki page:
The Vata application utilizes a modern, component-based UI architecture built on React 18 and Radix Themes. The system follows a "local-first" philosophy, prioritizing desktop-class performance and native-feeling interactions. The design system is strictly defined by Radix primitives for foundational elements, while internal application components focus on high-level "organisms" and domain-specific workflows like genealogical tree management.
The UI is divided into two primary contexts: the outside picker (home) and the inside shell (active tree environment). This boundary is strictly enforced at the routing level to ensure consistent database connection management and state isolation.
Sources: CLAUDE.md:14-25, CLAUDE.md:237-248
Core Architecture & Frameworks
Vata's UI is built on a specific stack of libraries designed for accessibility and consistent styling.
- Foundation: Radix Themes provides the primary component library (
@radix-ui/themes). - Icons: Lucide React is used for all iconography, registered through a centralized icon component.
- Styling: Global styles and color scheme rules are defined in CSS, while brand tokens like
accentColorandradiusare configured through the Radix<Theme>provider. - Transitions: The application supports light, dark, and system themes, with a pre-paint script to prevent "dark flash" during initial load.
Sources: CLAUDE.md:244-248, index.html:10-22
Theme Management Flow
The following diagram illustrates how the application determines and applies visual themes during the startup sequence.
The application uses a specific vata-app-storage key in localStorage to persist user theme preferences across sessions.
Sources: index.html:10-22, src/components/app-theme.tsx
Reusable UI Organisms
Vata distinguishes between base primitives (from Radix) and application-specific "organisms." These organisms encapsulate complex logic such as file handling, data scanning, and entity management.
The Dropzone Component
The Dropzone is a controlled visual component used for file selection. While it visualizes a "drop" area, it primarily interfaces with Tauri's native file dialog for security and OS integration.
| State | Purpose | Visual Feedback |
|---|---|---|
idle | Waiting for user interaction | Gray icon (upload) |
selected | File picked, awaiting next step | Indigo icon (folder-open) |
scanning | Processing file content | Spinner |
done | Task successfully completed | Green icon (download) |
error | Operation failed | Red icon (x) |
Sources: src/components/dropzone.tsx:14-55
Modal Systems
Modals in Vata are used for complex data-entry workflows. The ImportGedcomModal serves as a primary example of a multi-stage UI organism.
Entity Visualization & Tables
Vata uses a structured approach to displaying genealogical data, primarily through the EntityTable wrapper. This component manages loading states, errors, and empty results while providing a consistent layout for individuals, families, and events.
Individual Record Rendering
When displaying people (individuals), the system combines several UI elements:
- Avatars: Generated with initials derived from the primary name (Given + Surname) or nickname.
- Formatted Names: Utilizes a
formatNameutility to generatesurnameFirst(e.g., "Doe, John") orshort(e.g., "John Doe") strings. - Event Summaries: Extracts years from normalized ISO dates for birth and death events.
Sources: src/pages/IndividualsPage.tsx:23-88, src/db/trees/names.test.ts:211-255
Developer & Debug Tooling
The design system includes a developer-only DebugDrawer. This component is excluded from production builds and provides real-time insights into the internal state of the UI and databases.
| Tab | Functionality |
|---|---|
| System DB | Lists managed trees and global app settings. |
| Tree DB | Shows entity counts (individuals, families) for the active tree. |
| i18n | Displays current locale, resolved language, and loaded namespaces. |
| Theme | Shows the active theme state from the Zustand store. |
| Build | Displays the current application version from package.json. |
Sources: src/components/debug-drawer.tsx:32-150, CLAUDE.md:211-212
Component Implementation Standards
The repository enforces several code-level standards for UI development:
- Strict i18n: All user-facing strings must use the
useTranslation()hook. Literals are only permitted in tests or dev-only debug UIs. - Fragment Keys: When mapping over lists,
<React.Fragment key={...}>must be used instead of the shorthand<>to ensure stable reconciliation. - Path Aliases: Components must be imported using the
$componentsalias. - Controlled Components: Complex inputs like the
DropzoneorModalsshould have their state driven by parents or dedicated manager classes.
Sources: CLAUDE.md:120-135, CLAUDE.md:211-214
The Vata UI component system effectively balances the flexibility of React with the rigorous structure required for a local-first desktop application, ensuring data integrity and a cohesive user experience across all genealogy management workflows.