Building and Packaging

Relevant source files

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

• package.json
• README.md
• scripts/sync-upstream.sh
• src/index.ts
• src/styles.css
• src/tokens.css

HX-UI utilizes a multi-layered build and verification process to ensure visual consistency and code quality. The system relies on TypeScript for type checking and custom Node.js scripts to enforce design token rules and browser-based smoke tests.

The packaging strategy exports the library as a modern ES module, providing direct access to TypeScript source files and design tokens. This allows consumers to integrate components while maintaining the ability to customize visual styles through CSS variables defined in Design Tokens.

Sources: package.json:7-25, README.md:9-15

Build Workflow and Automation

The build process executes in stages, moving from static analysis to runtime verification. It combines standard TypeScript compilation with custom gatekeepers that validate adherence to the design system.

Build Scripts

The project defines several npm scripts to manage the lifecycle of the library:

Script	Command	Purpose
typecheck	tsc --noEmit	Validates TypeScript types across the project.
check:ui	node scripts/check-ui-rules.mjs src	Enforces design rules (e.g., no hardcoded hex colors).
build	tsc --noEmit && node scripts/check-ui-rules.mjs src	Combined type check and UI rule validation.
verify	npm run build && ... && npm run check:smoke	Full validation including documentation build and smoke tests.
sync-upstream	bash scripts/sync-upstream.sh	Synchronizes component source code from the upstream repository.

Sources: package.json:28-36, README.md:107-111

Execution Flow

The following diagram illustrates the verification pipeline triggered by npm run verify:

The UI Rule Gatekeeper specifically prevents the use of hardcoded hex values, non-semantic palettes, or buttons missing the type attribute.

Sources: README.md:73-77, package.json:36

Packaging and Exports

HX-UI is packaged as the @hx/ui module. It exports both TypeScript logic and CSS assets directly to allow for maximum flexibility in consumer build pipelines.

Module Structure

The package.json configuration defines the following entry points:

• Main/Types: ./src/index.ts serves as the primary entry point for both logic and type definitions.
• Styles: ./src/styles.css provides the Tailwind v4 bridge.
• Tokens: ./src/tokens.css contains the core design variables.
• Motion/Variants: Specific CSS for animations and spin variants.

Sources: package.json:11-25

Dependency Architecture

The library is built upon a specific stack of peer and runtime dependencies:

Upstream Synchronization

Because the upstream open-vetta project does not publish packages to NPM, HX-UI uses a source-copying strategy via scripts/sync-upstream.sh.

Synchronization Logic

The script performs the following actions:

1. Preservation: Backs up local hand-written components (e.g., Card.tsx, Badge.tsx) to /tmp.
2. Cleanup: Removes the existing src directory.
3. Copying: Pulls source files from the upstream packages/ui and packages/theme-ui directories.
4. Transformation: Uses sed and perl to rewrite internal imports from @vetta-org/ui to local relative paths (e.g., ../primitives/utils).
5. Metadata: Records the upstream commit hash in UPSTREAM_COMMIT.

Sources: scripts/sync-upstream.sh:16-72, README.md:124-129

Verification and Smoke Testing

A critical part of the build process is the browser-based smoke test implemented in scripts/check-smoke.mjs. This script opens the documentation site in a headless browser to ensure that components render correctly.

• Purpose: To catch rendering failures (e.g., React Provider errors) that pass tsc and vite build.
• Mechanism: Automatically extracts a list of pages from docs/src/nav.ts and inspects the DOM for each.
• Strict Mode: Uses the --strict flag in CI environments to force a build failure if Chromium is missing or tests fail.

Sources: README.md:113-119, package.json:31-32

Summary

The HX-UI build system prioritizes technical accuracy and design consistency through a rigorous automated pipeline. By combining TypeScript, automated UI linting, and browser smoke tests, the project ensures that component source code remains synchronized with upstream changes while strictly adhering to the local design token system.