@nebula-demo/ui

@nebula-demo/ui

React component library for the Nebula design system. Built on Radix UI primitives, styled with Tailwind CSS, and fully themed via @nebula-demo/tokens.

Install

npm install @nebula-demo/ui @nebula-demo/tokens
# or
pnpm add @nebula-demo/ui @nebula-demo/tokens

Peer dependencies

• react >= 18
• react-dom >= 18
• @nebula-demo/tokens ^0.2.0

Setup

1. Import the Nebula token stylesheet in your app entry:

@import '@nebula-demo/tokens/css';

1. If using Tailwind, add the Nebula preset to your config:

// tailwind.config.js
import nebulaPreset from '@nebula-demo/tokens/tailwind'

export default {
  presets: [nebulaPreset],
  content: ['./src/**/*.{ts,tsx}', './node_modules/@nebula-demo/ui/dist/**/*.{js,cjs}'],
}

The preset sets Tailwind's global prefix to cai- because the component bundle uses both token classes (cai-bg-primary) and prefixed core utilities (cai-flex, cai-rounded-md). That prefix applies to every utility generated by this Tailwind configuration. Do not override it. If your application must retain an existing unprefixed Tailwind build, compile the Nebula/UI entry separately with the Nebula preset and include both resulting stylesheets.

1. Use components:

import { Button, Badge, Tooltip, TooltipProvider } from '@nebula-demo/ui'

function App() {
  return (
    <TooltipProvider>
      <Button variant="primary" size="lg">
        Get started
      </Button>
      <Badge variant="success" size="md">
        Active
      </Badge>
    </TooltipProvider>
  )
}

Components

The package root exposes 45 component families and 147 runtime exports. Compound families include their related subcomponents, hooks, and helpers—for example, Table includes TableHead, TableCell, and useTableSelection.

Component	Description
Accordion	Expandable sections with accessible triggers and content panels
Alert Dialog	Modal confirmation flow with composable header, body, footer, and actions
Aspect Ratio	Responsive container that preserves a requested width-to-height ratio
Avatar	User image, initials, or icon avatar with size and status variants
Avatar Group	Overlapping avatar stack with overflow and optional add-person action
Avatar Label Group	Avatar paired with primary and supporting identity text
Badge	Compact semantic status label with optional icons
Badge Counter	Numeric count indicator with semantic variants
Button	Polymorphic action control with semantic variants, sizes, and icon support
Button Icon	Accessible icon-only action control with size and style variants
Calendar	Single-date or date-range calendar with optional input
Card	Composable content surface with header, body, and footer regions
Carousel	Accessible previous/next content carousel with composable items
Checkbox	Accessible binary selection control built on Radix UI
Context Menu	Right-click menu with items, groups, submenus, and selection controls
Date Picker	Date field and calendar popover for single-date selection
Drawer	Edge-mounted dialog with configurable direction and composable regions
Dropdown Menu	Triggered action menu with items, groups, submenus, and selection controls
Dropdown Select	Single, multi-select, or avatar-based option picker
File Status	File upload status row with progress, metadata, and actions
File Upload	Drag-and-drop or click-to-select file input with validation
Filter Chip	Compact selectable filter with optional dropdown behavior
Filter Chip Group	Coordinated single- or multi-select collection of filter chips
Icon	Nebula icon catalog renderer with semantic sizing
Inline Notification	Contextual feedback message with semantic status variants
Input	Text field with labels, supporting text, icons, and error states
Input Search	Searchable single- or multi-select input with rich option rows
Line	Horizontal separator with optional header or text label
Pagination	Composable page navigation with previous, next, and ellipsis controls
Progress Bar	Linear progress indicator for determinate or staged progress
Progress Circle	Circular progress indicator with semantic sizing
Radio Group	Accessible single-choice control built on Radix UI
Scroll Area	Styled scroll container with custom viewport behavior
Skeleton	Loading placeholder with pulse animation
Slider	Accessible range input for one or more numeric values
Switch	Accessible binary on/off control
Switch Group	Coordinated collection of single- or multi-select switches
Tab Navigation	Accessible tab list with triggers and content panels
Table	Composable data table with selection, status, empty, and caption helpers
Table Pagination	Page-size and navigation controls for tabular data
Tag	Removable or pinnable label with optional avatar and actions
Textarea	Multi-line text input with counters, tags, mentions, and error states
Toast	Imperative and composable transient notification system
Toggle	Pressable two-state control built on Radix UI
Tooltip	Accessible contextual tooltip with provider, trigger, and content

Utilities

cn(...inputs)

Merges class names using clsx + tailwind-merge. Useful for extending component styles:

import { Button, cn } from '@nebula-demo/ui'

function ExampleButton() {
  return <Button className={cn('my-custom-class', isActive && 'cai-opacity-100')} />
}

Theming

All components respond to the active theme automatically. Set data-theme="light" on a parent element for the Light theme (defaults to Midnight):

<html data-theme="light"></html>

Tree-shaking

Import named components from the package root. The ESM build is tree-shakeable, so bundlers can omit unused component modules:

import { Badge, Button } from '@nebula-demo/ui'

License

MIT