Primitive Components Base
Relevant source files
The following files were used as context for generating this wiki page:
Primitive components form the foundational layer of the HX-UI library, providing atomic UI elements built upon Radix UI. These components handle core behaviors, accessibility, and focus management while maintaining a strict separation between logic and visual appearance. The library follows a three-layer architecture: design tokens, a Tailwind bridge, and the primitive components themselves.
Sources: README.md:12-18, src/index.ts:7-12
System Architecture
The Primitive Components Base operates through a vertical stack that ensures design consistency without hardcoding values within the components.
This diagram illustrates how design tokens flow through the Tailwind bridge to style components built on Radix UI.
The Three-Layer Stack
| Layer | File/Directory | Description |
|---|---|---|
| Tokens | src/tokens.css | Defines CSS variables for colors, typography, shadows, and spacing. It has zero dependencies. |
| Bridge | src/styles.css | Maps CSS variables to Tailwind v4 @theme inline utility classes. |
| Components | src/primitives/ | React components combining Radix UI behavior with Tailwind styling. |
Sources: README.md:12-18, src/styles.css:26-55
Design Tokens (The Source of Truth)
The design system centralizes all visual parameters in src/tokens.css. This file defines the theme for both light and dark modes.
- Colors: Uses semantic naming such as
--primary,--background, and--muted. Dark mode is the default, while light mode is applied via the[data-mode="light"]attribute. - Typography: Defines font stacks for sans and mono, along with granular font size scales (e.g.,
--fs-sm,--fs-base). - Motion: Standardizes transition durations (
--dur-fast,--dur-base) and easing functions (--ease-out,--ease-in). - Shadows and Radius: Provides a consistent scale for elevation and corner roundness.
Sources: src/tokens.css:12-100, src/tokens.css:160-205
Core Primitive Implementations
Primitive components utilize class-variance-authority (CVA) to manage style variants and clsx for class merging.
Tabs
The Tabs component provides two distinct visual states managed through a shared React context:
- underline: The default view for object views (Overview, Logs, Config).
- pill: A compact toggle usually used in toolbars or settings.
Sources: src/primitives/tabs.tsx:8-25
Progress and Indicators
The Progress component prioritizes performance and accessibility:
- Performance: Updates the indicator via
transform: translateXinstead ofwidthto avoid layout thrashing during high-frequency updates. - Accessibility: Inherits
role="progressbar"and ARIA attributes from Radix UI to ensure screen reader compatibility. - ProgressMeter: A higher-level primitive that combines the progress bar with labels and percentage values.
Sources: src/primitives/progress.tsx:8-30, src/primitives/progress.tsx:64-75
Layout Control Primitives
Components like Separator and ScrollArea manage the visual rhythm and containment of the UI.
| Component | Logic Source | Key Behavior |
|---|---|---|
| Separator | radix-ui | 1px line that defaults to decorative={true} to avoid polluting accessibility trees. |
| ScrollArea | radix-ui | Provides custom scrollbars that avoid layout jumps and match the "overlay" style of macOS. |
| Switch | radix-ui | Supports two sizes (default, sm) and utilizes CSS variables for state-based coloring. |
Sources: src/primitives/separator.tsx:8-13, src/primitives/scroll-area.tsx:8-18, src/primitives/switch.tsx:10-20
Implementation Flow
HX-UI uses a standardized pattern for developing primitives to ensure they remain thin wrappers over Radix UI.
This sequence shows the interaction between the application code, HX-UI primitives, and the underlying Radix/CSS engine.
Sources: src/primitives/tabs.tsx:55-70, src/primitives/utils.ts
Summary
The Primitive Components Base is a decoupled system that separates design tokens from component logic. By building on Radix UI, the library ensures that all foundational elements are accessible and robust, while the CSS variable-driven styling allows for complete theme customization without modifying the component source code.