Quick Start & Installation
Relevant source files
The following files were used as context for generating this wiki page:
HX-UI is a React and TypeScript component library that adopts the open-vetta design language. It provides a three-tier architecture consisting of design tokens, a Tailwind CSS bridge, and a comprehensive set of React components built on Radix UI and Recharts.
The library emphasizes visual consistency through semantic CSS variables and offers an interactive documentation site with live examples for its 38 pages of components. It supports both Tailwind and non-Tailwind projects by decoupling design tokens from the framework.
Sources: README.md:1-12, src/index.ts:1-12
Project Architecture
The system organizes its functionality into three distinct layers, allowing users to adopt only the specific parts they require.
| Layer | Content | Dependencies |
|---|---|---|
| Tokens | src/tokens.css — Colors, radii, shadows, fonts. | None |
| Bridge | src/styles.css — Tailwind v4 @theme inline mapping. | Tailwind v4 |
| Components | src/primitives/, src/layout/, src/charts/ | React 19 + Radix UI |
Sources: README.md:14-20
Component Categories
HX-UI categorizes its exports into three primary groups:
- Primitives: Base components like
Button,Input, andDialogbuilt on Radix UI. - Layout: High-level structural components such as
AppFrame,DataTable, andStepperthat define page patterns. - Charts: Visualizations based on Recharts 3, including
HxLineChartandHxAreaChart.
Sources: src/index.ts:14-118, README.md:22-55
Installation & Setup
Requirements
The library requires React 19 and specifies Tailwind CSS v4 as a peer dependency for projects using the bridge layer.
"peerDependencies": {
"react": "^19.0.0",
"react-dom": "^19.0.0",
"tailwindcss": "^4.0.0"
}
Sources: package.json:54-58
Library Installation
To set up the library for development or local use, execute the following commands in the root directory:
- Install dependencies:
npm install - Build the library and run design audits:
npm run build - Perform a full verification (build + docs + smoke tests):
npm run verify
Sources: README.md:76-80, package.json:34-40
Documentation Site
The project includes a documentation site located in the docs directory. To run it:
- Navigate to the directory:
cd docs - Install dependencies:
npm install - Launch the development server:
npm run dev
Sources: README.md:88-92
Development Workflow
Synchronization with Upstream
HX-UI maintains visual parity with open-vetta by synchronizing source code rather than using a package manager. A shell script automates the retrieval of components, updating package references while leaving CSS class names untouched.
The diagram shows the automated workflow for updating HX-UI components from the open-vetta upstream repository.
Sources: scripts/sync-upstream.sh:1-68, README.md:112-118
Verification and Linting
The library uses scripts/check-ui-rules.mjs during the build process to enforce design constraints. This "design gate" prevents the use of:
- Hardcoded hex color values.
- Non-semantic color palettes.
- Borders that are not 1px.
- Native buttons missing the
typeattribute.
Sources: README.md:65-69, package.json:39
Styling and Theme Configuration
Design Tokens
src/tokens.css acts as the single source of truth for all visual styles. It defines CSS variables for dark (default) and light modes.
:root, [data-mode="dark"] {
--background: rgb(20, 22, 30);
--primary: rgb(99, 102, 241);
--radius: 0.5rem;
--fs-base: 13px;
}
Sources: src/tokens.css:12-65
Tailwind Bridge
src/styles.css maps the CSS tokens to Tailwind v4 theme variables. It also defines custom variants for Radix UI states and theme transitions.
The diagram illustrates how CSS tokens flow through the Tailwind bridge to style the React components, including state-based variants.
Sources: src/styles.css:1-55
Summary
Quick Start for HX-UI involves installing dependencies via npm, optionally configuring Tailwind v4 to bridge the provided CSS tokens, and utilizing the src/index.ts entry point to access the component library. The library ensures visual consistency through strict design gates and a centralized token system, while providing a synchronization script to remain updated with its upstream design source.
Sources: README.md:76-80, package.json:16-25