Shared UI Primitives Overview
Relevant source files
The following files were used as context for generating this wiki page:The shared/ui directory contains the foundational UI primitives for the application. Following the principles of Feature-Sliced Design (FSD), these components are low-level, reusable, and business-agnostic building blocks. They encapsulate complex behaviors, animations, and accessibility features, providing a consistent and stable base for higher-level widgets and features.
This system emphasizes headless accessibility, leveraging libraries like Radix UI, and a hybrid motion engine combining GSAP and Framer Motion. The primitives are styled using a theme-aware system powered by CSS variables and Tailwind CSS, ensuring visual consistency across the application in both light and dark modes.
Sources: README.md, src/app/index.css
Theming and Styling
The application employs a semantic theming system using CSS custom properties (variables) defined in src/app/index.css. This allows for robust light and dark mode support, controlled by the data-theme attribute on the <html> element.
Sources: src/app/index.css:4-67
Theme Architecture
The core of the theming system is a set of CSS variables that define the color palette for backgrounds, text, borders, and brand colors. Two main selectors, html[data-theme="light"] and html[data-theme="dark"], override the default values to apply the appropriate theme. Tailwind CSS is configured to use these variables, making utility classes like bg-bg-default and text-fg-primary theme-aware.
This diagram illustrates the flow from CSS variable definition to component styling.
Sources: src/app/index.css:12-67, 70-96
Key Theme Variables
The following table summarizes the primary CSS variables used for theming.
| Variable Name | Light Theme Value | Dark Theme Value | Description |
|---|---|---|---|
--bg-default | #ffffff | #121212 | Default background color for pages. |
--bg-paper | #f4f4f5 | #1e1e20 | Background for card-like elements. |
--fg-primary | #18181b | #f4f4f5 | Primary text color. |
--fg-secondary | #52525b | #a1a1aa | Secondary text color for subtext. |
--border-default | #e4e4e7 | #27272a | Default border color. |
--primary | #2563eb | #3b82f6 | Main brand/action color. |
--action-hover | #f4f4f5 | rgba(255, 255, 255, 0.05) | Background color for hover states on UI elements. |
Sources: src/app/index.css:15-40, 43-67
Core UI Components
The shared/ui directory contains several key components that are used throughout the application.
Tooltip
The Tooltip component provides a flexible, animated, and position-aware tooltip that can wrap any child element. It is used in the Hero widget to display detailed cards for the user's name and company.
Sources: src/shared/ui/Tooltip/Tooltip.tsx, src/widgets/Hero/Hero.tsx:100-125
Features
- Portal Rendering: Uses
createPortalto render the tooltip directly intodocument.body, avoiding z-index and overflow issues. - Dynamic Positioning: Automatically calculates its position to avoid clipping at the viewport edges. It adjusts from right to left and bottom to top based on available space.
- Animation: Uses
motion/reactfor a spring-based entrance and exit animation. - Event Handling: Responds to
onMouseEnter,onMouseMove,onMouseLeave,onTouchStart, andonClickto manage visibility across devices.
Sources: src/shared/ui/Tooltip/Tooltip.tsx:10-15, 40-79, 137-154
Interaction Flow
This sequence diagram shows how the Tooltip component responds to user interaction to manage its state and position.
Props
| Prop | Type | Optional | Description |
|---|---|---|---|
content | string | React.ReactNode | No | The content to display inside the tooltip. |
children | React.ReactNode | No | The element that triggers the tooltip. |
containerClassName | string | Yes | Additional classes for the wrapper div. |
unstyled | boolean | Yes | If true, removes default padding, background, and shadow. |
Sources: src/shared/ui/Tooltip/Tooltip.tsx:11-17
BentoGrid & BentoCard
The BentoGrid and BentoCard components work together to create the responsive, interactive bento-style layout seen on the home page. BentoGrid is a simple CSS Grid container, while BentoCard is a highly interactive and stateful component.
Sources: src/shared/ui/BentoGrid/BentoGrid.tsx, src/widgets/HomeBentoSection/HomeBentoSection.tsx
BentoCard Features
- Interactive Spotlight: A radial gradient follows the mouse cursor on hover, creating a spotlight effect. This is disabled on focus to not interfere with accessibility outlines.
- Conditional Rendering: Renders as a
react-router-dom<Link>for internal navigation and a standard<a>tag for external links or file downloads. - Responsive CTA: A call-to-action button is revealed on hover for devices with fine pointers (like a mouse). On touch devices, a static icon is always visible.
- Stateful Opacity: The spotlight's opacity is managed based on
mouseenter,mouseleave,focus, andblurevents.
Sources: src/shared/ui/BentoGrid/BentoGrid.tsx:56-82, 172-205
BentoCard State Machine
The visual state of the BentoCard's spotlight effect can be represented by the following state diagram.
BubbleMenu
The BubbleMenu is a mobile-first navigation component that provides a playful, animated menu experience. It is used in the main Navbar for screen sizes below 1024px.
Sources: src/shared/ui/BubbleMenu/BubbleMenu.tsx, src/widgets/Navbar/Navbar.tsx:103-112
Animation and Logic
- Animation Engine: Uses
gsap(GreenSock Animation Platform) for all animations, including the menu toggle and the staggered, scaling appearance of the menu items. - State Management: A combination of
useStateanduseEffecthooks manages the open/closed state and triggers the animations. - Outside Click Handling: Implements a
useOutsideClickhook to automatically close the menu when the user clicks outside of the menu item list.
Sources: src/shared/ui/BubbleMenu/BubbleMenu.tsx:81-131, 62-64
Menu Toggle Flow
The following flowchart describes the logic when the user toggles the bubble menu.
Summary
The shared UI primitives in this repository form a robust and well-architected foundation for the application's front end. By encapsulating logic, accessibility, and complex animations into small, reusable components, they enable rapid development of new features while maintaining a high standard of quality and consistency. The theming system ensures a cohesive look and feel that adapts to user preferences, and the choice of powerful libraries like GSAP, Framer Motion, and Radix UI demonstrates a commitment to a modern, high-performance user experience.
Sources: README.md, package.json