UI Rules and Build Gates
Relevant source files
The following files were used as context for generating this wiki page:
The UI Rules and Build Gates system enforces design consistency and technical standards across the HX-UI repository. It ensures that components adhere to specific visual guidelines and prevents code that violates the design system from entering the production build.
This system operates through a multi-layered validation pipeline, including static analysis of CSS tokens, design rule linting, and browser-based smoke tests.
Sources: README.md:95-103, package.json:28-34
Design Token Architecture
The project centralizes all visual attributes into a "Single Source of Truth" located in src/tokens.css. This file defines the core design tokens without dependencies on external frameworks like Tailwind.
Token Layering
- Tokens (
src/tokens.css): Defines raw CSS variables for colors, border radius, shadows, and typography. - Bridge (
src/styles.css): Maps these CSS variables to Tailwind v4@theme inlineutilities. - Components: Reference semantic variables (e.g.,
var(--primary)) instead of hardcoded values.
Sources: README.md:14-22, src/tokens.css:1-12
Design Rule Constraints
The build gate enforces the following specific visual rules:
- Banned Values: No hardcoded HEX color codes are permitted in component source files.
- Semantic Colors: All styling must use semantic color tokens from the design palette.
- Border Consistency: Borders must strictly follow the 1px standard defined in the rules.
- Button Attributes: Every native
<button>element must include atypeattribute.
Sources: README.md:97-101, package.json:32
Automated Build Gates
Automated gates prevent regressions by running specific checks during the build and verification process.
The diagram shows the sequence of validation steps executed during the project verification phase.
Key Validation Scripts
| Script | Command | Purpose |
|---|---|---|
check:ui | node scripts/check-ui-rules.mjs src | Scans source files for hardcoded colors and non-standard borders. |
check:smoke | node scripts/check-smoke.mjs | Performs browser-based rendering checks for component pages. |
build | tsc --noEmit && npm run check:ui | Combines TypeScript validation with UI rule enforcement. |
verify | npm run build && ... && npm run check:smoke | The final gate ensuring all rules, types, and visual renders are valid. |
Sources: package.json:28-34, README.md:110-120
Visual Rule Enforcement
The check-ui-rules.mjs script acts as a static analysis tool that parses the src directory. If it detects a violation—such as a developer using #ffffff instead of var(--background)—it returns a non-zero exit code, causing the build to fail.
Browser Smoke Testing
The project uses Chromium to perform "Smoke Tests" via scripts/check-smoke.mjs. This gate catches runtime rendering failures, such as a white-screen error caused by incorrect Radix Provider usage, which static analysis tools like tsc or vite build cannot detect.
- Extraction: The script automatically extracts the list of pages from
docs/src/nav.ts. - Validation: It opens every documentation page and verifies the DOM structure.
- Strict Mode: CI environments use the
--strictflag to ensure any failure blocks the merge.
Sources: README.md:113-120, package.json:30-31
Upstream Synchronization Rules
Components sourced from open-vetta follow a specific synchronization protocol managed by scripts/sync-upstream.sh.
- Visual Preservation: The script copies source files but forbids modification of visual class names to maintain design language alignment.
- Import Mapping: It automatically updates internal
@vetta-org/uireferences to local relative paths (e.g.,../primitives/utils). - Dependency Handling: Since upstream packages are not published to NPM, the build gate relies on direct source copying and automated path rewriting.
The sequence diagram illustrates how components are pulled from upstream while maintaining the visual rules of the design system.
Sources: scripts/sync-upstream.sh:1-40, README.md:144-149
Summary
The UI Rules and Build Gates system protects the design integrity of HX-UI. By combining static design token enforcement via check-ui-rules.mjs and dynamic visual validation through check-smoke.mjs, the project ensures that all components remain themeable and functionally sound without manual inspection for every change.
Sources: README.md:95-120