UI Component Library
Relevant source files
The following files were used as context for generating this wiki page:
The SoulSeer UI Component Library is a centralized collection of reusable React components and CSS design tokens designed to provide a consistent, mystical, and professional aesthetic across the platform. The library follows a "Celestial" design system characterized by dark mode defaults, glass morphism, and specific brand colors like Pink (#FF69B4) and Gold (#D4AF37).
The architecture relies on a structured export pattern where all core components are registered in a central entry point for ease of use throughout the client application. Styling is managed via a hierarchy of CSS files, starting with global tokens and extending to page-specific overrides.
Sources: client/src/components/ui/index.ts, client/src/styles/global.css:1-50, README.md:90-95
Design System & Tokens
The visual foundation of the library is defined through CSS Custom Properties (Design Tokens) located in the global stylesheet. These tokens govern colors, typography, spacing, and shadows to ensure architectural consistency.
Core Color Palette
| Category | Variable | Value | Description |
|---|---|---|---|
| Brand | --primary-pink | #FF69B4 | Primary action and heading color |
| Brand | --accent-gold | #D4AF37 | Secondary accent and rating color |
| Background | --bg-deep-black | #0A0A0F | Main application background |
| Surface | --surface-card | rgba(19, 17, 26, 0.55) | Translucent glass effect for containers |
| Status | --success | #22C55E | Online status and positive changes |
Sources: client/src/styles/global.css:8-50
Typography and Layout
The library utilizes two primary web fonts: Alex Brush for headings and Playfair Display for body text. Spacing follows a fixed scale (e.g., --space-1 at 4px up to --space-20 at 80px) to maintain rhythm across different screen sizes.
Sources: client/src/styles/global.css:1-5, client/src/styles/global.css:57-65, client/src/styles/global.css:108-120
Component Architecture
The library is organized into discrete functional units, exported through client/src/components/ui/index.ts. This allows developers to import multiple components from a single package.
The diagram above illustrates the logical grouping of exported UI components within the shared library.
Sources: client/src/components/ui/index.ts:1-45
Interactive Components
Buttons and Actions
Buttons are styled with various variants (primary, secondary, gold, ghost, danger) and sizes. The btn--glow class is used for high-priority calls to action, such as starting a reading session.
| Variant | Styling | Usage |
|---|---|---|
primary | Pink gradient with glow | Main path actions (e.g., Publish Post) |
gold | Solid gold background | Premium/Monetized actions (e.g., Top Up) |
danger | Red background/border | Destructive actions (e.g., End Session) |
ghost | Transparent with hover | Low-emphasis secondary actions |
Sources: client/src/styles/global.css:322-385, client/src/pages/reading/ReadingSessionPage.tsx:555-565
Modals and Dialogs
The library includes a Modal component for complex interactions and a ConfirmDialog for destructive confirmation. Modals utilize a backdrop filter (blur(8px)) and a slide-up animation for entry.
Sources: client/src/styles/global.css:603-655, client/src/pages/dashboard/AdminDashboard.tsx:640-660
Data Visualization Components
Specialized Indicators
- StatusBadge: Used to indicate reader availability. It features an "online" variant with a pulsing dot animation.
- StarRating: Displays numeric ratings as visual stars, supporting both read-only (Reader profile) and interactive (Session review) modes.
- AudioVisualization: A decorative component found in voice/video sessions that simulates audio frequency bars using CSS animations.
Sources: client/src/styles/global.css:530-545, client/src/pages/reading/ReadingSessionPage.tsx:44-52, client/src/pages/readers/ReaderProfilePage.tsx:125-135
Global vs. Page Styles
Styling logic is split between global.css (reusable components) and pages.css (unique page layouts).
The relationship between the global design system and specialized page layouts.
Sources: client/src/styles/global.css, client/src/styles/pages.css:1-20
Key Page-Specific Components
- SessionBar: A specialized sticky header used in
ReadingSessionPageto display real-time elapsed time, cost, and balance. - ChatBubble: Context-aware bubbles that differentiate between "sent" and "received" messages using distinct background colors (
primary-pinkvsaccent-goldvariations). - FilterBar: A grid-based container used on the readers and community pages to manage data sorting and filtering.
Sources: client/src/styles/pages.css:368-400, client/src/styles/pages.css:420-455, client/src/styles/pages.css:80-95
Implementation Example: Reading Session UI
The UI library components are composed in ReadingSessionPage.tsx to handle complex states.
Data and component flow during an active reading session.
Sources: client/src/pages/reading/ReadingSessionPage.tsx:500-600
Conclusion
The UI Component Library serves as the visual and interactive core of the SoulSeer platform. By centralizing common patterns like "Celestial" cards, themed buttons, and animated status badges, it ensures that the mystical brand identity is maintained across all user roles (Clients, Readers, and Admins).
Sources: client/src/styles/global.css:1-100, client/src/components/ui/index.ts