Documentation Site Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The HX-UI documentation site serves as an interactive component showcase consisting of 38 pages, each providing live instances and copyable code. The architecture focuses on visual fidelity, performance through caching, and high availability via smoke testing.
The documentation site relies on a three-tier architecture: design tokens for theming, a Tailwind v4 bridge for utility styles, and React 19 components built on Radix UI. It implements hash-based routing to allow direct access to specific component documentation.
Sources: README.md:1-12, README.md:95-97
Core Features and Capabilities
The documentation site provides several integrated tools to assist developers in exploring the UI library. These include a command-driven search interface, automated table of contents generation, and a robust theme switching system.
| Feature | Description |
|---|---|
| Search (⌘K / Ctrl+K) | Uses substring and subsequence matching to find components like DataTable. |
| In-page Navigation | A right-column directory that reads from the rendered DOM and highlights on scroll. |
| Anchor Links | Automatically derives id from H2 text for deep-linking. |
| Theme Toggle | Supports System, Light, and Dark modes with an inline script to prevent FOUC. |
| Navigation | Provides "Previous" and "Next" page links based on the nav.ts configuration. |
Sources: README.md:99-115
Build and Verification Pipeline
The project uses a strict verification pipeline to ensure the documentation site remains functional across updates. This pipeline includes design rule enforcement and browser-based smoke tests.
The check-smoke.mjs script verifies that every page listed in docs/src/nav.ts renders correctly in a real browser environment. This catches errors that TypeScript or Vite builds might miss, such as incorrect Radix Provider usage or component API mismatches that result in white pages.
Sources: README.md:85-93, package.json:28-29
Theming and Design Tokens
The site architecture enforces a strict separation between logic and appearance. Components do not contain hardcoded color values; instead, they reference CSS variables defined in src/tokens.css.
Theming Implementation
- Design Tokens:
tokens.cssacts as the single source of truth for colors, border-radii, shadows, and typography. It functions independently of Tailwind. - Tailwind Bridge:
styles.cssmaps these tokens to Tailwind v4 themes using the@theme inlinedirective. - Rule Enforcement: A build-time script (
check-ui-rules.mjs) validates that no hardcoded hex codes or non-standard border widths are used in the source code.
Sources: src/tokens.css:1-10, src/styles.css:17-40, README.md:73-77
Interactive Component Infrastructure
Specific modules within the documentation site architecture provide specialized functionality for code display and data visualization.
Syntax Highlighting Engine
The CodeBlock component uses the shiki engine to render code snippets. This ensures that the syntax highlighting in the documentation matches the visual output of VS Code. To optimize performance, the system implements a caching mechanism for highlighted HTML.
The cache uses a Map with a maximum of 128 entries and a total unit limit of 4,000,000 to manage memory usage while preventing layout shifts during list re-mounting.
Sources: src/layout/CodeBlock.tsx:1-55
Data and Logging Displays
For complex data, the site uses DataTable and LogViewer components. The LogViewer specifically implements a "sticky but not locked" scrolling logic, where the view follows new logs only if the user is already at the bottom of the container.
Sources: src/layout/DataTable.tsx:18-35, src/layout/LogViewer.tsx:12-25
Summary
The HX-UI Documentation Site Architecture is built to be a reliable, high-fidelity reference for developers. By combining design tokens, automated browser smoke tests, and optimized rendering components like the shiki-powered CodeBlock, the system ensures visual consistency and technical accuracy across all 38 documentation pages.