UI Component Library
Relevant source files
The following files were used as context for generating this wiki page:
The UI Component Library in the DreamCats project is a collection of reusable, accessible, and themeable components built on top of Radix UI primitives and styled using Tailwind CSS v4. It follows the shadcn/ui pattern, where components are located in src/components/ui/ and emphasize composition and flexibility through utility-first styling.
The library serves as the visual foundation for the game, supporting a "dreamy" aesthetic characterized by soft gradients, mystical glows, and smooth transitions. It is designed to be responsive and mobile-friendly, incorporating specific touch-target optimizations and layout guardrails to ensure playability across various devices.
Sources: AGENTS.md:38-41, README.md:14-17, src/index.css:127-140
Architecture and Styling Foundation
The UI architecture leverages Tailwind CSS v4 for styling and class-variance-authority (CVA) to manage component variants. The system uses a CSS variable-based theming approach to support both Light and Dark modes.
Theme Configuration
The project defines two primary theme states:
- Light Mode: A "dreamy creamy off-white" theme using soft cherry blossom tints.
- Dark Mode: A "deep twilight" theme with mystical purple glows.
Sources: src/index.css:127-168, src/components/ui/sheet.tsx:32-52
Design System Constants
| Variable | Description | Source |
|---|---|---|
--primary | Main action color (Soft purple) | src/index.css:138 |
--accent | Highlight color (Cherry blossom pink) | src/index.css:147 |
--radius | Base border radius (0.75rem) | src/index.css:157 |
--font-heading | Display font (DM Serif Display/Lora) | src/index.css:26-204 |
Component Composition Flow
Most high-level UI components are composed using Radix UI primitives to ensure WAI-ARIA compliance.
The diagram shows how the UI components are built by combining low-level primitives with utility-based styling and variant management.
Sources: src/components/ui/sheet.tsx:7-14, src/components/ui/dialog.tsx:7-12, AGENTS.md:40
Core Component Modules
Dialog and Overlay Systems
The library provides several ways to handle overlays, primarily through Dialog and Sheet components. These use a shared Portal and Overlay logic to manage z-index and background dimming.
- Dialog: Used for modal interactions like settings, legal information, and tutorial steps.
- Sheet: Used for side-panels, often sliding in from the right or bottom.
- Portal: Ensures components are rendered at the root of the DOM to avoid stacking context issues.
Sources: src/components/ui/dialog.tsx:14-60, src/components/ui/sheet.tsx:16-86
This sequence illustrates the rendering lifecycle of an overlay component.
Sources: src/components/ui/dialog.tsx:33-52, src/components/ui/sheet.tsx:64-80
Interaction Elements: Buttons
The Button component is the primary interaction primitive, utilizing CVA to handle multiple visual states and sizes.
| Variant | Purpose |
|---|---|
default | Primary actions using --primary color. |
destructive | High-risk actions like "Start Fresh". |
outline | Secondary actions or borders. |
ghost | Low-emphasis buttons or icon-only actions. |
link | Text-based navigation. |
Sources: src/components/ui/button.tsx:10-25, src/components/LandingPage.tsx:142-155
Animation and Motion
The component library integrates with GSAP and Framer Motion for state transitions. It also adheres to system-level motion preferences.
Keyframe Animations
The system defines several global animations in index.css:
fly-in: Used for elements appearing with a subtle upward slide.float: A 6-second infinite loop for background decorative elements.card-pop: A 0.35s lift animation for card interactions.shimmer: A 2s infinite gradient movement for loading or high-tier elements.
Sources: src/index.css:48-78, src/index.css:268-281, src/index.css:322-340
Accessibility: Reduced Motion
The library explicitly honors user preferences for reduced motion. When prefers-reduced-motion: reduce is detected, animation durations are forced to 0.001ms to effectively disable them.
Sources: src/index.css:305-312, AGENTS.md:47
Layout and Responsive Guardrails
Touch Target Optimization
To support mobile gameplay, the library includes a .touch-target utility and global overrides for buttons on small screens.
- Minimum Target: 44px x 44px for buttons and clickable roles.
- Mobile Scaling: The library uses
100dvh(Dynamic Viewport Height) to prevent layout shifts on mobile browsers.
Sources: src/index.css:170-174, src/index.css:182-195, src/index.css:357-363
Scrolling and Containment
The ScrollArea component provides a custom-styled scrollbar that is consistent across platforms, replacing native scrollbars which might clash with the game's aesthetic.
Implementation Example: Modal Composition
The following snippet demonstrates how the Dialog components are composed to create high-level features like the LegalModal.
// src/components/LegalModal.tsx
<Dialog open={open} onOpenChange={onOpenChange}>
<DialogContent className="max-w-2xl max-h-[85vh]">
<DialogHeader>
<DialogTitle>{title}</DialogTitle>
<DialogDescription>{description}</DialogDescription>
</DialogHeader>
<ScrollArea className="h-[60vh] pr-4">
<div className="prose prose-sm dark:prose-invert">
{content}
</div>
</ScrollArea>
</DialogContent>
</Dialog>
Sources: src/components/LegalModal.tsx:28-44
Summary
The DreamCats UI Component Library combines the robust accessibility of Radix UI with the modern styling capabilities of Tailwind CSS v4. By centralizing variants in CVA and strictly following a design system defined in index.css, the project ensures visual consistency across its "dreamy" interface while maintaining high performance and mobile accessibility.