@zvn/ui

An AI-first component library for React with zero-runtime styling, type-safe APIs, and comprehensive accessibility.

Features

• Zero-Runtime Styling - Built on StyleX for optimal performance
• Type-Safe - Full TypeScript support with comprehensive prop types
• Accessible - Radix UI primitives with ARIA patterns baked in
• AI-Ready - Components tagged with @ai-* annotations for AI tooling
• Themeable - 7 built-in themes with full customization support
• Gesture Support - Touch gestures, swipe, drag, and more

Installation

npm install @zvn/ui react react-dom

Quick Start

import { Button, Input, Dialog } from '@zvn/ui'
import '@zvn/ui/styles.css'

function App() {
  return (
    <Dialog>
      <DialogTrigger asChild>
        <Button>Open Form</Button>
      </DialogTrigger>
      <DialogContent>
        <DialogTitle>Contact Us</DialogTitle>
        <Input placeholder="Your email" />
        <Button>Submit</Button>
      </DialogContent>
    </Dialog>
  )
}

Components

Primitives

• Button - Interactive button with variants, sizes, loading states
• Input - Text input with icons, error states, helper text
• Label - Accessible form labels
• Badge - Status indicators
• Textarea - Multi-line text input
• Checkbox - Toggle control
• RadioGroup - Single selection from options
• Select - Dropdown selection
• Switch - Toggle switch
• Slider - Range selection

Form

• Field - Form field wrapper with label/error handling
• InputGroup - Input with addons
• ButtonGroup - Grouped buttons
• TagsInput - Multi-value tag input
• FileUpload - File upload with drag-and-drop
• InputOTP - One-time password input

Overlay

• Dialog - Modal dialog
• Drawer - Slide-out panel
• Popover - Floating content
• Tooltip - Hover information
• DropdownMenu - Action menu
• AlertDialog - Confirmation dialog
• HoverCard - Rich hover previews

Layout

• Card - Content container
• Accordion - Collapsible sections
• Tabs - Tabbed navigation
• Collapsible - Expandable section
• Separator - Visual divider
• AspectRatio - Fixed aspect container
• Box, Flex, Stack, Grid - Layout primitives
• Container, Center, Spacer - Layout utilities

Navigation

• Breadcrumb - Navigation path
• NavigationMenu - Site navigation
• Pagination - Page navigation
• Menubar - Application menu
• ContextMenu - Right-click menu

Data Display

• Table - Data table
• Avatar - User avatar
• Calendar - Date picker
• Command - Command palette (cmdk)
• ScrollArea - Custom scrollbar

Feedback

• Alert - Inline messages
• Toast - Notifications (sonner)
• Progress - Progress indicator
• Skeleton - Loading placeholders
• Spinner - Loading spinner

Advanced

• Sheet - Slide-out panel
• Resizable - Resizable panels
• Carousel - Image carousel
• TreeView - Hierarchical data
• Timeline - Event timeline
• Stepper - Multi-step flow
• Rating - Star rating
• CodeBlock - Syntax highlighting
• Chat - Chat interface
• Combobox - Searchable select
• DataTable - Advanced data grid
• Sidebar - App navigation
• AppShell - App layout wrapper

Theming

Built-in Themes

import { darkTheme, indigoTheme, tealTheme, roseTheme } from '@zvn/ui'

// Apply via className
<div className={darkTheme}>
  <App />
</div>

Available Themes

• Default (Light)
• Dark
• Indigo
• Teal
• Rose
• Minimal
• Soft
• Brutalist

Custom Tokens

Override design tokens via StyleX:

import { colors, spacing } from '@zvn/ui'

Hooks

import {
  useMediaQuery,
  useIsMobile,
  useIsTablet,
  useIsDesktop,
  usePrefersDarkMode,
  usePrefersReducedMotion,
  useControllableState,
  useDebounce,
  useLocalStorage,
  useClickOutside,
  useKeyboardShortcut,
  useSwipe,
  useDrag,
  usePan,
  useLongPress,
  useDoubleTap,
} from '@zvn/ui'

Utility Functions

import {
  cn,           // Combine class names
  merge,        // Merge StyleX styles
  variant,      // Type-safe variant selector
  when,         // Conditional styling
  clamp,        // Number clamping
  debounce,     // Function debouncing
  throttle,     // Function throttling
  generateId,   // Unique ID generation
} from '@zvn/ui'

Accessibility

All components follow WAI-ARIA patterns:

• Keyboard navigation
• Screen reader support
• Reduced motion respect
• Focus management
• ARIA attributes

Browser Support

• Chrome 90+
• Firefox 90+
• Safari 14+
• Edge 90+

Development

# Install dependencies
npm install

# Start development server
npm run dev

# Run tests
npm test

# Build library
npm run build:lib

# Type check
npm run typecheck

# Lint
npm run lint

License

MIT