Theming Engine via CSS Tokens
Relevant source files
The following files were used as context for generating this wiki page:
The HX-UI theming engine manages visual styles through a three-layer architecture centered on CSS custom properties (tokens). This system separates design definitions from component logic, ensuring that visual changes only require modifications to the token layer. The engine supports dark and light modes, semantic color mapping, and standardized typography and spacing scales.
Sources: README.md:10-15, src/tokens.css:1-10
Architecture Overview
The theming engine operates in three distinct layers to provide maximum flexibility and compatibility:
- Token Layer (
src/tokens.css): Defines the "Single Source of Truth" using pure CSS custom properties for colors, typography, shadows, and spacing. It has zero dependencies. - Bridge Layer (
src/styles.css): Maps CSS tokens to Tailwind v4@theme inlineutilities. - Component Layer: Consists of primitives and layout components that consume the mapped styles.
Sources: README.md:12-16, src/styles.css:26-55
Data Flow and Mapping
The following diagram illustrates how raw CSS tokens flow from definition to component usage via the Tailwind bridge.
Visual styles originate in tokens.css and are bridged in styles.css for component consumption.
Sources: src/tokens.css:14-149, src/styles.css:26-55
Design Tokens
Color System
The engine defines a semantic color palette that adapts to data-mode="dark" (default) and data-mode="light". Dark mode uses high-contrast accessibility standards, while light mode shifts primary values (e.g., darkening --primary from rgb(99, 102, 241) to rgb(79, 70, 229)) to maintain legibility on white backgrounds.
| Token Group | Purpose | Key Variables |
|---|---|---|
| Surface | Backgrounds for pages and containers | --background, --card, --popover |
| Foreground | Text colors corresponding to surfaces | --foreground, --card-foreground, --muted-foreground |
| Action | Brand and functional states | --primary, --secondary, --accent, --destructive |
| Input | Form and structural elements | --border, --input, --ring |
| Charts | Data visualization color sequences | --segment-1 through --segment-5 |
Sources: src/tokens.css:14-72, src/tokens.css:76-96
Typography and Scaling
The engine provides granular scales for font sizes, including half-pixel values to ensure visual precision in dense interfaces.
- Font Stacks: Provides
--font-sansfor standard UI and a comprehensive--font-monostack prioritizing professional coding fonts like JetBrains Mono and Fira Code. - Font Sizes: Ranges from
--fs-3xs(9px) to--fs-4xl(26px). - Z-Index: Standardizes layering from
--z-base(0) to--z-tooltip(70).
Sources: src/tokens.css:48-60, src/tokens.css:149-166, src/tokens.css:175-183
Theme Implementation
Theme Switching
Themes are toggled using the data-mode attribute on the root or container elements. The system includes a transition mechanism that limits animations to color-related properties (background, border, box-shadow) while excluding transforms and opacity to avoid performance lag.
The application of the data-mode attribute triggers a scoped variable swap defined in the token layer.
Sources: src/tokens.css:14, src/tokens.css:118-124, src/styles.css:14-15
Component Integration
Components consume tokens primarily through Tailwind utility classes or direct CSS variable references.
- Tailwind Bridge: In
src/styles.css, variables are registered under@theme inlineusing the--color-*prefix, allowing usage liketext-primary. - Direct Variable Usage: Primitives such as
TabsandPageHeaderreference tokens directly for layout-critical values, such astext-[length:var(--fs-lg)]. - Rounding Logic: Corner radii are derived from a single
--radiustoken via CSScalc()in the bridge layer.
Sources: src/styles.css:27-55, src/primitives/tabs.tsx:43, src/layout/PageHeader.tsx:46
Enforcement and Validation
The project employs a "design-by-gate" approach. The npm run build command executes a custom script (check-ui-rules.mjs) that validates component code against the theming rules.
- Hardcoded Colors: The build fails if hex codes or raw RGB values appear in component source files.
- Semantic Consistency: Only semantic tokens (e.g.,
text-primary) are permitted. - Structural Rules: Enforces 1px border standards and specific HTML attributes (e.g.,
typeon native buttons).
Sources: README.md:43-47, package.json:28-35
Summary
The HX-UI theming engine provides a robust framework for consistent visual design. By centralizing all visual variables in src/tokens.css and bridging them to Tailwind v4, the system allows for site-wide skinning without modifying component logic. The use of semantic naming, granular scaling, and automated build-time validation ensures that the UI remains accessible, professional, and maintainable across dark and light modes.