Lux Docs
Lux Skills Reference

Lux UI

Multi-Framework Component Library

Overview

Lux UI (@luxfi/ui) is a comprehensive design system and component library for the Lux ecosystem. It is a pnpm monorepo built on top of shadcn/ui, extended with domain-specific packages for commerce, web3, finance, 3D, animation, and agent UI. Supports React, Vue, Svelte, and React Native via multi-framework registry system. Published to npm as @luxfi/ui at version 5.3.37.

Repository

ItemValue
Repogithub.com/luxfi/ui
Local~/work/lux/ui/
Package@luxfi/ui v5.3.37
LicenseMIT
Homepagehttps://ui.lux.finance
Package Managerpnpm 9.0.6
Build OrchestratorTurborepo 2.x
Node22+

Tech Stack

TechnologyVersionPurpose
React19.2.xPrimary rendering framework
Next.js14-16App framework for demo sites
Tailwind CSS4.1.xUtility-first styling
TypeScript5.9.xType safety
Radix UILatestAccessible primitives
Vitest4.0.xUnit testing
Playwright1.56.xE2E and visual regression testing
tsup8.5.xLibrary bundling
Changeset2.29.xVersion management and changelogs
motion (Framer)12.12.xAnimation library
Recharts3.3.xChart components
dnd-kit6.xDrag and drop
Lucide0.544.xIcon system

Project Structure

~/work/lux/ui/
  package.json          # Root workspace (@luxfi/ui v0.1.0)
  pnpm-workspace.yaml   # app, apps/*, packages/*, pkg/*
  brand.config.ts       # Theme: pure black/white monochrome
  components.json       # shadcn/ui component registry config
  playwright.config.ts  # E2E test configuration

  app/                  # Main docs/registry app (@luxfi/ui-web)
    components/         # 60+ component implementations
    registry/           # Component registry system
    hooks/              # 13 React hooks
    lib/                # Utilities
    scripts/            # Build scripts
    __registry__/       # Auto-generated registry data
    __tests__/          # Test suites

  apps/
    v4/                 # v4 preview app (port 4000, Turbopack)
    www/                # Marketing site

  packages/
    shadcn/             # shadcn CLI fork (v3.8.4) -- component installer
    og/                 # Open Graph image generation
    tests/              # Shared test utilities

  pkg/                  # Domain-specific packages
    ui/                 # Core component library (@luxfi/ui v5.3.37)
    brand/              # Brand assets and tokens
    commerce/           # E-commerce components
    checkout/           # Checkout flow components
    shop/               # Shop/storefront components
    web3/               # Web3/wallet components
    react/              # React-specific utilities
    data/               # Data display components
    agent-ui/           # AI agent interface components
    menu-icons/         # Menu icon set
    ui-templates/       # Page templates

Core Component Library (pkg/ui/)

Published as @luxfi/ui v5.3.37 to npm. Source in pkg/ui/src/:

Component Categories

CategoryPathContents
ui/Core UIannouncement, avatar-group, banner, cursor, marquee, pill, spinner, tags, ticker
3d/3D renderingThree.js/Spline integrations
animation/MotionFramer Motion wrappers and presets
auth/AuthenticationLogin/signup forms
billing/BillingSubscription and payment UI
calendar-ext/CalendarExtended calendar components
charts/Data vizChart wrappers (Recharts)
code/Code displaySyntax highlighting, code blocks
desktop/DesktopDesktop app chrome components
device/Device framesPhone/tablet/desktop device frames
dock/App dockmacOS-style dock component
form/Form elementsInput, select, checkbox, radio, etc.
hooks/React hooksShared hook utilities
kanban/Kanban boardDrag-and-drop board (dnd-kit)
mcp/MCP UIModel Context Protocol interfaces
mermaid/DiagramsMermaid.js diagram rendering
models/Data modelsTypeScript model definitions
navigation/Nav componentsSidebar, breadcrumbs, tabs
pattern/BackgroundDecorative background patterns
project/Project mgmtProject management components
registry/Registry systemComponent registry infrastructure
spline/Spline 3DSpline.design integrations
primitives-export.tsPrimitivesContainer, Box, Heading, Text, Button, Link, Stack, Grid

Domain Packages

PackagePathPurpose
@luxfi/uipkg/ui/Core library (5.3.37)
Brandpkg/brand/Brand tokens, logos, colors
Commercepkg/commerce/Product cards, cart, pricing
Checkoutpkg/checkout/Payment flow, address, summary
Shoppkg/shop/Storefront layouts
Web3pkg/web3/Wallet connect, chain selector, tx status
Agent UIpkg/agent-ui/Chat bubbles, tool calls, agent status
Reactpkg/react/React-specific wrappers
Datapkg/data/Data tables, lists, grids

Brand Configuration

Defined in brand.config.ts:

{
  name: "Lux UI",
  siteUrl: "https://ui.lux.network",
  company: "Lux Partners Limited",
  github: { org: "luxfi", repo: "ui" },
  theme: {
    primary: "#1a1a1a",        // Near black
    darkBackground: "#000000", // Pure black
    darkForeground: "#fafafa"  // Near white
  }
}

Pure black/white monochrome design language.

Development

cd ~/work/lux/ui

# Install dependencies
pnpm install

# Start all apps in parallel
pnpm dev

# Start specific apps
pnpm v4:dev          # v4 preview (port 4000)
pnpm www:dev         # Marketing site
pnpm hanzo-ui:dev    # Hanzo UI variant

# Build
pnpm build           # Build all
pnpm v4:build        # Build v4 app
pnpm cli:build       # Build CLI

# Testing
pnpm test            # Unit tests (Vitest)
pnpm test:e2e        # E2E tests (Playwright)
pnpm test:visual     # Visual regression tests
pnpm health-check    # Component health validation

# Registry
pnpm build:registry  # Build component registry
pnpm registry:build  # Alternative registry build
pnpm registry:capture # Capture component screenshots

# Code quality
pnpm lint            # ESLint
pnpm lint:fix        # Auto-fix lint issues
pnpm format:write    # Prettier formatting
pnpm typecheck       # TypeScript type checking
pnpm check           # lint + typecheck + format:check

# Publishing
pnpm pub:beta        # Publish beta to npm
pnpm pub:release     # Publish release to npm
pnpm release         # Changeset version bump

shadcn CLI (packages/shadcn/)

Forked shadcn CLI (v3.8.4) for component installation:

  • Adds components from the Lux UI registry
  • Supports multiple frameworks (React, Vue, Svelte, React Native)
  • Handles Tailwind CSS 4 configuration
  • Includes tests (Vitest)

Testing Strategy

TypeToolCommand
UnitVitest 4.0.6pnpm test
E2EPlaywright 1.56pnpm test:e2e
VisualPlaywrightpnpm test:visual
Accessibilityjest-axe / vitest-axeIntegrated in unit tests
HealthCustom scriptpnpm health-check
RegistryCustom validatorpnpm validate:registries

Key Patterns

  • Components follow shadcn/ui patterns: copy-paste, customizable, no runtime dependency lock-in
  • Registry system auto-generates component metadata for the CLI installer
  • Multi-framework support via separate registry entries per framework
  • All components use Tailwind CSS with the monochrome theme tokens
  • Domain packages (commerce, web3, agent-ui) extend the core primitives
  • Changeset-based versioning with GitHub changelog generation
RepoPurpose
github.com/luxfi/marketNFT marketplace using these components
github.com/luxfi/docsDocumentation site using these components
github.com/luxfi/explorerBlock explorer using these components
github.com/luxfi/bridgeBridge UI using these components

On this page