Three-Layer Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The HX-UI library implements a three-layer architecture to decouple design tokens, styling frameworks, and functional components. This structure allows developers to utilize specific layers independently, such as using design tokens without adopting Tailwind CSS or React components. The architecture ensures visual consistency by centralizing design constants while maintaining flexible integration paths for different project requirements.
Sources: README.md:1-16, src/index.ts:1-12
Architectural Layers
The system categorizes its codebase into three distinct tiers: Tokens, Bridge, and Components.
Layer Definitions
| Layer | Content | Purpose | Dependency |
|---|---|---|---|
| Tokens | src/tokens.css | Defines colors, radii, shadows, fonts, and chart color sequences. | Zero |
| Bridge | src/styles.css | Maps CSS variables to Tailwind v4 @theme inline definitions. | Tailwind v4 |
| Components | src/primitives/, src/layout/, src/charts/ | Implements functional UI elements using React 19 and Radix UI. | React 19 + Radix UI |
Sources: README.md:10-16
Data Flow and Dependency Structure
The architecture follows a strict downward dependency flow. Tokens serve as the "Single Source of Truth." The Bridge layer translates these tokens for the Tailwind engine, and Components consume the resulting utility classes or raw CSS variables.
The diagram illustrates how the library abstracts design values from implementation details.
Sources: README.md:10-16, src/styles.css:1-55
Tokens Layer (Design System)
The Tokens layer resides in src/tokens.css and contains zero external dependencies. It defines CSS custom properties for various design facets. This layer supports theme switching via [data-mode="dark"] and [data-mode="light"] attributes.
- Colors: Defines semantic keys like
--primary,--background, and--destructive. - Typography: Establishes
--font-sansand--font-monostacks, as well as font size scales (e.g.,--fs-sm,--fs-base). - Motion: Sets standard durations (
--dur-base) and easing functions (--ease-out). - Charts: Provides equal-luminance color sequences (
--segment-1to--segment-5) for data visualization.
Sources: src/tokens.css:1-68, src/tokens.css:143-186
Bridge Layer (Tailwind Integration)
The Bridge layer, located in src/styles.css, acts as the glue between the Design Tokens and Tailwind CSS. It uses the @theme inline directive to map CSS variables defined in the Tokens layer to Tailwind's utility system.
This mapping ensures that changing a single variable in tokens.css updates all components without requiring changes to individual React files. The Bridge layer also defines custom variants for theme switching and Radix UI states:
- Dark Mode:
@custom-variant dark (&:is([data-mode="dark"] *)) - State Variants: Maps Radix
data-stateto Tailwinddata-openanddata-closedvariants.
Sources: src/styles.css:12-45, src/tokens.css:1-10
Components Layer (Implementation)
The Components layer is organized into three sub-directories, each serving a different functional scope within the React environment.
Primitives
These are foundational elements built on Radix UI, focusing on accessibility and core behavior. Examples include Button, Input, Switch, Dialog, and Drawer.
Layout
Layout components define the visual structure and "look and feel" of the application. They include higher-order patterns such as AppFrame, SettingRow, DataTable, and PageHeader.
Charts
Built on Recharts 3, this sub-layer provides specialized wrappers like HxLineChart and HxAreaChart that automatically apply the project's design tokens to axes, grids, and tooltips.
Enforcement and Maintenance
The project uses automated scripts to maintain the integrity of the three-layer architecture.
- UI Rules Check: The
check-ui-rules.mjsscript (run duringnpm run build) prevents "leakage" between layers. It fails if components contain hard-coded hex colors, non-semantic palettes, or borders that deviate from the 1px standard. - Upstream Sync: The
scripts/sync-upstream.shscript facilitates pulling core primitives from theopen-vettadesign system while rewriting import paths to match the local three-layer structure.
Sources: README.md:65-72, package.json:20-28, scripts/sync-upstream.sh:1-25
Summary
The Three-Layer Architecture provides a robust framework for UI development by separating design concerns (Tokens) from integration tooling (Bridge) and functional implementation (Components). This separation ensures that the visual identity is preserved across different environments while allowing for granular adoption of the library's features.