Tailwind V4 Mapping

Relevant source files

The following files were used as context for generating this wiki page:

• src/styles.css
• src/tokens.css
• README.md
• package.json
• src/layout/DataTable.tsx
• src/layout/PageHeader.tsx
• src/primitives/tabs.tsx

The Tailwind V4 Mapping serves as the bridge layer in the HX-UI architecture, connecting low-level design tokens to high-level React components. This system utilizes Tailwind v4's @theme inline directive to map CSS custom properties (variables) defined in a central token file to Tailwind's utility classes. This architecture ensures that visual changes only require modifications to the token layer while maintaining strict design consistency across all components.

Sources: README.md:10-15, src/styles.css:1-5

Architectural Overview

The styling system divides into three distinct layers:

1. Tokens Layer (src/tokens.css): Contains raw CSS variables for colors, typography, shadows, and spacing. It functions independently of Tailwind.
2. Bridge Layer (src/styles.css): Implements the Tailwind v4 @theme inline mapping, converting tokens into Tailwind utilities.
3. Component Layer: Consumes the utilities via standard Tailwind class names or arbitrary value syntax.

Sources: README.md:10-15, src/tokens.css:1-10

Design Token Data Flow

The following diagram illustrates how styles flow from raw CSS variables into the final rendered components through the Tailwind V4 bridge.

The diagram shows the transition from raw tokens to the Tailwind engine.
Sources: src/styles.css:1-35, src/tokens.css:1-50

Theme Mapping Implementation

HX-UI defines the Tailwind theme within the @theme inline block in src/styles.css. This block overrides default Tailwind values with project-specific design tokens.

Color and Typography Mapping

The bridge maps semantic color tokens (e.g., --primary, --background) to Tailwind's color system. It also establishes the font stacks for sans-serif and monospace text.

Tailwind Theme Variable	Source CSS Variable	Description
--color-primary	var(--primary)	The main brand color
--color-background	var(--background)	The global background color
--font-sans	var(--font-sans)	Standard UI font stack
--font-mono	var(--font-mono)	Programming/code font stack
--color-border	var(--border)	Default border color for all elements

Sources: src/styles.css:32-60, src/tokens.css:16-56

Radius and Shadow Scaling

Radius values are derived from a single --radius token, ensuring proportional rounding across different scales (sm, md, lg, xl).

@theme inline {
  --radius-sm: calc(var(--radius) - 4px);
  --radius-md: calc(var(--radius) - 2px);
  --radius-lg: var(--radius);
  --radius-xl: calc(var(--radius) + 4px);
}

Sources: src/styles.css:66-70, src/tokens.css:86

Custom Variants and States

HX-UI implements custom Tailwind variants to handle theme switching and Radix UI component states.

Dark Mode Handling

Dark mode is bound to the data-mode="dark" attribute rather than the prefers-color-scheme media query. This allows explicit user control over the theme.
Sources: src/styles.css:21-22, src/tokens.css:12-14

Component State Mapping

The bridge maps Radix UI's data-state attributes to Tailwind variants like data-open and data-closed. This enables conditional styling for components like Dialogs and Accordions.

The diagram shows how Radix UI states trigger specific Tailwind variants for animations.
Sources: src/styles.css:24-29

Component Consumption Patterns

Components access tokens through two primary methods:

1. Mapped Utilities: Standard classes like text-primary or bg-card which are mapped in the @theme block.
2. Arbitrary Value Syntax: Direct access to specific tokens via text-[length:var(--fs-sm)]. This is used extensively for precise typography scales (e.g., half-pixel increments) defined in tokens.css.

Typography Scaling Examples

HX-UI defines a granular typography scale to avoid visual drift during theme migration.

Scale Token	Value	Component Usage Example
--fs-xs	11px	DataTable header labels
--fs-sm	12px	SettingRow descriptions
--fs-sm-half	12.5px	DataTable row content
--fs-2xl	20px	PageHeader titles

Sources: src/tokens.css:140-155, src/layout/DataTable.tsx:96, 137, src/layout/PageHeader.tsx:47

Conclusion

The Tailwind V4 Mapping architecture provides a strict decoupling between the design language (tokens) and the implementation (Tailwind). By centralizing these mappings in src/styles.css, HX-UI enables global visual updates through a single configuration point while leveraging the full utility-first power of Tailwind V4.