Introduction to HX-UI

Relevant source files

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

• README.md
• src/index.ts
• src/tokens.css
• src/styles.css
• package.json
• scripts/sync-upstream.sh
• src/charts/ChartFrame.tsx
• src/layout/DataTable.tsx

HX-UI is a UI component library built with React 19 and TypeScript. It adopts the design language of open-vetta and organizes its architecture into three distinct layers: Design Tokens, Tailwind Bridge, and UI Components. This structure allows developers to use the library at different levels of abstraction, from raw CSS variables to high-level layout components.

The project emphasizes a strict separation between visual styles and logic. Visual class names remain identical to the upstream open-vetta source to ensure visual consistency, while the internal architecture facilitates easy theme customization through CSS variables. It includes an interactive documentation site with 38 pages featuring live examples and copyable code.

Sources: README.md:1-12, package.json:49-59, src/index.ts:1-13

Project Architecture

The library organizes code into three layers to support both Tailwind and non-Tailwind environments.

Layer	Content	Dependencies
Tokens	src/tokens.css — Colors, radii, shadows, fonts	None
Bridge	src/styles.css — Tailwind v4 @theme inline mappings	Tailwind v4
Components	src/primitives/, src/layout/, src/charts/	React 19 + Radix UI

Sources: README.md:14-20, src/styles.css:26-55

Component Categorization

Components are divided into three functional groups:

1. Primitives: Built on Radix UI, covering basic interactive elements like Button, Dialog, and Select.
2. Layout: High-level structures like AppFrame, DataTable, and PageHeader that define page patterns.
3. Charts: Based on Recharts 3, providing specialized handling for animations and consistent theming.

Sources: src/index.ts:15-115, README.md:22-55

System Data Flow

The following diagram illustrates how visual tokens propagate from the base CSS variables through the Tailwind bridge to the React components.

Design Tokens and Theming

The theme system resides entirely in src/tokens.css using CSS custom properties. The library prohibits hardcoded color values in component code.

Core Token Categories

• Colors: Includes semantic variables like --primary, --background, and --destructive. It also defines chart color sequences (--segment-1 through --segment-5).
• Typography: Defines standard font stacks for sans-serif and monospace, alongside font size scales from --fs-3xs (9px) to --fs-4xl (26px).
• Motion: Sets durations for fast (100ms), base (200ms), and slow (300ms) animations.
• Z-Index: Centralizes depth management (e.g., --z-toast: 60, --z-tooltip: 70).

Sources: src/tokens.css:12-192, README.md:65-70

Theme Implementation

The system supports light and dark modes via the data-mode attribute. Dark mode is the default.

:root, [data-mode="dark"] {
  color-scheme: dark;
  --background: rgb(20, 22, 30);
  --primary: rgb(99, 102, 241);
}

[data-mode="light"] {
  color-scheme: light;
  --background: rgb(255, 255, 255);
  --primary: rgb(79, 70, 229);
}

Sources: src/tokens.css:12-70, src/styles.css:10-12

Data Presentation and Charts

DataTable

The DataTable component provides a structured view for data without taking over data fetching logic. It handles sticky headers, row hovering, and empty/loading states internally.

Key features include:

• Decoupled Fetching: Users provide rows and columns; the component renders them.
• Sticky Headers: Uses sticky positioning with backdrop-blur for visibility during scrolling.
• Skeleton Loading: Generates placeholder rows when the loading prop is active.

Sources: src/layout/DataTable.tsx:30-80, src/layout/DataTable.tsx:173-186

Charts System

Charts are built on Recharts 3 but wrapped to ensure responsiveness and consistent visual styles.

Synchronization with Upstream

HX-UI maintains visual parity with open-vetta by copying source files rather than using a package dependency. A bash script, scripts/sync-upstream.sh, automates this process.

Synchronization Logic

1. Preparation: Backs up local handwritten components (Card.tsx, Badge.tsx).
2. Cleanup: Removes existing src directories to ensure a clean slate.
3. Copying: Pulls primitive components from the upstream packages/ui and layout components from packages/theme-ui.
4. Refactoring: Automatically updates internal imports from @vetta-org/ui to local relative paths using sed and perl.

Sources: scripts/sync-upstream.sh:1-70, README.md:120-130

Development and Verification

The project uses specialized scripts to ensure code quality and adherence to design rules.

Script	Purpose
npm run build	Runs tsc and a design rule gatekeeper (check-ui-rules.mjs)
npm run check:ui	Validates design rules (e.g., no hardcoded hex colors, 1px borders)
npm run verify	Performs full build, doc site build, and browser smoke tests

The smoke test (scripts/check-smoke.mjs) is critical because it verifies DOM rendering in a real browser to catch issues that tsc or vite build might miss, such as Radix Provider misconfigurations.

Sources: package.json:28-36, README.md:78-95

Conclusion

HX-UI provides a robust framework for building React applications with a cohesive visual identity. By layering design tokens, Tailwind integration, and high-level components, it balances flexibility for simple styling with the power of pre-built complex layouts. Its reliance on upstream synchronization ensures it benefits from established design patterns while maintaining local extensibility.