CSS & Animation Strategy
Relevant source files
The following files were used as context for generating this wiki page:
The HX-UI CSS and animation strategy establishes a tiered architecture that separates design tokens from framework-specific implementation. It ensures visual consistency, high performance for real-time data, and framework independence for its core design definitions.
Design Token Architecture
The system organizes styling into three distinct layers to provide flexibility and strict enforcement of design rules.
| Layer | Description | Dependencies |
|---|---|---|
| Tokens | src/tokens.css — Defines colors, radii, shadows, fonts, and chart sequences. | None |
| Bridge | src/styles.css — Maps tokens to Tailwind CSS v4 @theme inline variables. | Tailwind CSS v4 |
| Components | src/primitives/, src/layout/, src/charts/ — Functional UI elements. | React 19 + Radix UI |
Sources: README.md:10-15, src/tokens.css:1-10
Design Token Management
Design tokens serve as the "single source of truth." Components avoid hard-coded color values, ensuring that changing tokens.css updates the entire site. The system uses OKLCH color spaces for chart segments to maintain equal brightness and saturation, preventing readers from misinterpreting brightness differences as data magnitude.
Sources: src/tokens.css:32-38, README.md:58-61
Animation and Motion Strategy
The project employs specific animation techniques tailored to different UI requirements, prioritizing performance and reliability over purely visual effects.
CSS Keyframe Animations
The system uses CSS keyframes rather than JS-driven transitions for critical layout components like accordions and collapsible panels. This approach ensures that Radix UI's Presence detection identifies the animation correctly, preventing the component from unmounting prematurely during the "closing" phase.
The diagram shows the relationship between CSS keyframe definitions and the components that trigger them.
Sources: src/motion.css:1-15, src/primitives/accordion.tsx:10-17
Chart Animation Strategy
HX-UI distinguishes between "first load" and "incremental update" animations for charts. Standard Recharts animations often re-calculate the entire dataset, causing "shaking" in real-time data streams. HX-UI uses specific matching modes to keep existing data points stationary while new points fade in.
| Mode | Behavior | Use Case |
|---|---|---|
index | Matches by array index and stretches proportionally. | Initial load or full batch replacement. |
append | Matches sequentially; new items fade in while old ones stay in place. | Log streams, second-level monitoring. |
dataKey | Matches by a specific business ID (e.g., id). | Sliding windows where data moves to new positions. |
Sources: src/charts/animation.ts:1-20, README.md:63-68
Theme and Visual Consistency
Theme Switching
The system supports three theme modes: Follow System, Light, and Dark. Theme transitions are restricted to color-based properties (background-color, color, border-color, box-shadow) to avoid interfering with functional animations like transforms or opacity.
Sources: src/tokens.css:112-117, README.md:100-103
Specialized Spin Animations
The Spin component utilizes 41 distinct shapes from the LDRS library. It supports a "rotate" mode that cycles through shapes using cross-fading. To prevent visual stuttering, the system uses two layers:
- Fade-in Layer: Participates in layout to determine container size.
- Fade-out Layer: Absolutely positioned to overlay the new shape without expanding the root node.
Sources: src/primitives/spin.tsx:23-33, src/spin-variants.css:55-75
Performance Optimization
- Budgeting: The
CodeBlockcomponent checks code size before applying Shiki highlighting. If a code snippet exceeds 30,000 characters or 1,000 lines, it reverts to plain text to prevent main-thread blocking. Sources: src/layout/CodeBlock.tsx:90-105 - Chart Point Limits: Chart animations are automatically disabled if the data exceeds 800 points to prevent frame drops on low-end devices. Sources: src/charts/animation.ts:46-52
- Idle Unmounting: The
CollapsePanelcomponent moves heavy React unmounting tasks (e.g., clearing a large DOM sub-tree) to the browser's idle period usingrequestIdleCallback, ensuring the final frame of a "collapse" animation remains smooth. Sources: src/layout/CollapsePanel.tsx:18-28