@annondeveloper/ui-kit v2

Zero-dependency React component library with 147 components, physics-based animations, OKLCH color system, and Aurora Fluid design.

Quick Start

npm install @annondeveloper/ui-kit

import { UIProvider, Button, Card, MetricCard } from '@annondeveloper/ui-kit'

function App() {
  return (
    <UIProvider>
      <Card>
        <Button variant="primary">Deploy</Button>
        <MetricCard title="CPU" value="87.4%" trend="up" />
      </Card>
    </UIProvider>
  )
}

Features

Zero dependencies — only react and react-dom peer deps
147 components — 73 general-purpose + 74 domain-specific across 3 weight tiers
3 weight tiers — Lite (144), Standard (147), Premium (145) — optimize your bundle
Aurora Fluid design — deep atmospheric surfaces, ambient glows, OKLCH colors
Physics animations — real spring solver, configurable motion levels (0-3)
Built-in form engine — createForm, useForm, validators, zero external deps
15 pre-built themes — including 5 new themes added in v2.4
MCP server — Model Context Protocol integration for AI-assisted workflows
classNames prop — deep customization of internal component elements
Accessibility — WAI-ARIA patterns, keyboard navigation, screen reader support
Responsive — container queries, fluid typography, touch/mouse/gamepad support
Theme generator — generate complete theme from single brand color

Documentation

Migration Guide -- Upgrading from v1 to v2
Theming -- OKLCH colors, theme generation, customization
Form Engine -- Built-in form state, validators, auto-wiring
Animation -- Physics springs, timeline, stagger, scroll
Design Spec -- Full architecture document

New in v2.5

Motion Choreography -- Sequenced multi-step animations with 5 presets
Container Queries -- Container-responsive design tokens and components
View Transitions -- Native View Transitions API with 6 presets
Theme Editor -- Color harmony, contrast audit, multi-format export
AI Generator -- Template gallery, custom composition, 5 framework output
CLI Scaffolding -- Project templates, component add, Figma export
Figma Plugin -- Token sync between code and Figma Variables
Performance Dashboard -- Bundle tracking, render profiler, Web Vitals

Next-Gen Features

Motion Choreography -- Orchestrate multi-step animation sequences with Choreography class, 5 presets (cascade, stagger-grid, wave, spiral, focus-in), and scroll-triggered choreography via useScrollChoreography.

Container Query Design Tokens -- <ContainerQuery> component, useContainerSize() hook, resolveResponsive() utility, and CONTAINER_BREAKPOINTS for building components that adapt to their container.

View Transitions API -- useViewTransition() hook with 6 presets (morph, crossfade, slide-left, slide-right, slide-up, zoom) and assignTransitionName() for element morphing.

Theme Editor -- Color harmony engine (5 types), WCAG contrast audit, export to CSS/Tailwind/Figma/CSS-in-JS, and shareable URL scheme.

AI Component Generator -- Template gallery (dashboard, form, marketing, saas, docs), custom composition builder, and code output for React, Vue, Svelte, and HTML.

CLI Scaffolding -- add copies components, create scaffolds full projects from 5 templates, figma-export generates Figma Variables JSON.

Figma Plugin -- Export theme tokens as Figma Variables and import them via the Aurora UI Kit Token Sync plugin.

Performance Dashboard -- Bundle size tracking with budget gauge, runtime render profiler, Web Vitals integration, and CI regression detection.

CLI Commands

npx @annondeveloper/ui-kit init                                    # Copy theme + setup
npx @annondeveloper/ui-kit add <component> [--tier] [--out-dir]    # Copy component source
npx @annondeveloper/ui-kit create <name> --template <template>     # Scaffold project
npx @annondeveloper/ui-kit list                                    # List all 147 components
npx @annondeveloper/ui-kit theme <color>                           # Generate theme CSS
npx @annondeveloper/ui-kit figma-export --theme <name> --output <file>  # Export Figma tokens

Component List

General-Purpose Components (73)

Component	Description
`ActionIcon`	Icon-only button with tooltip
`Accordion`	Collapsible sections with single/multiple mode
`Affix`	Fixed-position wrapper for floating elements
`Alert`	Inline status messages with variants
`AnimatedCounter`	Smooth number animation with easing
`AppShell`	Full application layout scaffold
`Avatar`	Image/initials avatar with status dot
`AvatarUpload`	Avatar with upload/crop functionality
`BackToTop`	Scroll-to-top floating button
`Badge`	Pill-shaped label with color presets
`Breadcrumbs`	Hierarchical navigation trail
`Button`	Primary action with variants and loading
`ButtonGroup`	Grouped button container
`Calendar`	Standalone calendar display
`Card`	Styled container with subcomponents
`Carousel`	Image/content carousel with navigation
`Checkbox`	Themed checkbox with indeterminate state
`Chip`	Compact interactive tag element
`ColorInput`	Color picker with hue/saturation panel
`Combobox`	Searchable select with async loading
`CommandBar`	Universal command palette (Cmd+K)
`ConfirmDialog`	Confirmation modal with danger variant
`CopyButton`	One-click copy to clipboard
`DatePicker`	Calendar-based date selection
`DateRangePicker`	Date range selection with presets
`Dialog`	Native dialog with animated entry/exit
`Divider`	Horizontal/vertical separator
`Drawer`	Slide-out panel from any edge
`DropdownMenu`	Action menu with submenus and shortcuts
`EmptyState`	Decorative placeholder with icon and actions
`FileUpload`	Drag-and-drop file upload with preview
`FilterPill`	Rounded filter toggle with count
`FormInput`	Themed input with label and validation
`Highlight`	Text highlighting with search match
`Indicator`	Dot/badge indicator overlay
`InlineEdit`	Click-to-edit text field
`Kbd`	Keyboard shortcut display
`Link`	Styled anchor with underline animation
`MultiSelect`	Multi-value select dropdown
`Navbar`	Top-level application navigation bar
`NativeTooltip`	Lightweight tooltip using title attribute
`NotificationStack`	Toast notification cards with auto-dismiss
`NumberInput`	Numeric input with increment/decrement
`OtpInput`	One-time password code entry
`Pagination`	Page navigation with controls
`PasswordInput`	Password field with visibility toggle
`PinInput`	PIN code entry with auto-advance
`Popover`	Anchored popover with arrow and focus management
`Progress`	Progress bar with indeterminate mode
`RadioGroup`	Radio button group with descriptions
`Rating`	Star rating input with half-star support
`ScrollReveal`	Scroll-triggered reveal animation
`SearchInput`	Search field with debounce and clear
`SegmentedControl`	Segmented toggle selector
`Select`	Themed dropdown select
`Sheet`	Slide-over drawer with swipe dismiss
`Sidebar`	Collapsible side navigation
`Skeleton`	Shimmer loading placeholder
`Slider`	Range slider with keyboard support
`Spoiler`	Collapsible content with show more/less
`Spotlight`	Spotlight search overlay
`StatusBadge`	Status indicator with colored dot
`StatusPulse`	Animated status dot with pulse ring
`Stepper`	Step indicator with progress
`SuccessCheckmark`	Animated SVG checkmark
`Tabs`	Tabbed interface with animated indicator
`TagInput`	Multi-value input with tag chips
`Textarea`	Auto-growing text area
`Toast`	Pre-themed toast notifications
`ToggleSwitch`	Boolean toggle switch
`Tooltip`	Popover-based tooltip with positioning
`Typography`	Semantic text with fluid sizing
`UIProvider`	Theme, motion, and density provider

Domain-Specific Components (74)

Component	Description
`BackgroundBeams`	Animated sweeping light beams
`BackgroundBoxes`	Floating animated grid boxes
`BorderBeam`	Animated conic-gradient border
`Card3D`	3D perspective tilt with glare
`CodeEditor`	Code editor with syntax highlighting
`ConfidenceBar`	Probability bar with threshold zones
`ConnectionTestPanel`	Step-by-step connectivity test UI
`CopyBlock`	Code display with one-click copy
`CoreChart`	CPU core utilization grid
`Cropper`	Image cropping tool
`CSVExportButton`	One-click CSV generation and download
`ColumnVisibilityToggle`	Column show/hide dropdown
`DashboardGrid`	Draggable dashboard layout
`DataTable`	Full-featured data grid with search, sort, filter
`DensitySelector`	Compact/comfortable/spacious control
`DiffViewer`	Side-by-side/inline diff viewer
`DiskMountBar`	Disk mount utilization bars
`EncryptedText`	Matrix-style character scramble/reveal
`EntityCard`	Infrastructure resource card
`EvervaultCard`	Matrix-style encrypted card
`FlipWords`	Rotating word animation
`GeoMap`	SVG geographic visualization
`GlowCard`	Mouse-tracking radial glow card
`HeatmapCalendar`	GitHub-style contribution heatmap
`HeroHighlight`	Gradient text highlight effect
`InfiniteScroll`	Virtualized infinite-scroll list
`JsonViewer`	Interactive JSON tree viewer
`KanbanColumn`	Kanban board column with cards
`LiveFeed`	Real-time event feed with auto-scroll
`LogViewer`	Log stream viewer with severity colors
`MeteorShower`	Falling meteor streak animation
`MetricCard`	Dashboard stat tile with sparkline
`NetworkTrafficCard`	Network throughput display
`NumberTicker`	Rolling digit counter
`OrbitingCircles`	Orbiting icon animation
`PipelineStage`	Horizontal pipeline visualization
`PortStatusGrid`	Network port status indicator grid
`PropertyList`	Key-value detail panel
`RackDiagram`	Data center rack visualization
`RealtimeValue`	Live data display with freshness tracking
`ResponsiveCard`	Container-query adaptive card
`RichTextEditor`	WYSIWYG rich text editor
`RingChart`	SVG donut chart with center label
`Ripple`	Click ripple effect
`SeverityTimeline`	Event timeline with severity dots
`ServiceStrip`	Horizontal service badge strip
`ShimmerButton`	Shimmering gradient button
`SmartTable`	DataTable with auto-generated filter suggestions
`SortableList`	Drag-and-drop reorderable list
`Sparkline`	Inline SVG sparkline chart
`SpotlightCard`	Spotlight hover effect card
`StepWizard`	Multi-step form wizard
`StorageBar`	Segmented horizontal bar
`StreamingText`	AI/LLM streaming text with cursor
`SwitchFaceplate`	Network switch port grid
`TableOfContents`	Auto-generated page navigation
`TextReveal`	Scroll-triggered character-by-character unveil
`ThresholdGauge`	Semicircular gauge with threshold zones
`TimePicker`	Time selection input
`TimeRangeSelector`	Compact time range pill selector
`Timeline`	Vertical event timeline
`TimeSeriesChart`	Full SVG line chart with multi-series
`Tour`	Guided product tour with step highlights
`TracingBeam`	Scroll-tracing side beam
`TransferList`	Dual-list item transfer
`TreeView`	Hierarchical tree with expand/collapse
`TruncatedText`	Auto-truncating text with tooltip
`TypingIndicator`	"Someone is typing" animation
`UpstreamDashboard`	Service monitoring layout
`UptimeTracker`	Daily uptime bar strip
`UtilizationBar`	Horizontal bar with threshold colors
`ViewTransitionLink`	View Transitions API integration
`WavyBackground`	Animated SVG sine waves

New in v2.5 (1 component)

Component	Description
`ContainerQuery`	Container query wrapper with render-prop size info

New in v2.4 (30 components)

The following components were added in the v2.4 release:

General-purpose: ActionIcon, Affix, AvatarUpload, BackToTop, ButtonGroup, Calendar, Carousel, Chip, CopyButton, DateRangePicker, Highlight, Indicator, MultiSelect, NumberInput, PasswordInput, PinInput, SegmentedControl, Spoiler, Spotlight, Stepper, TableOfContents, Textarea, TimePicker, Timeline, TransferList

Domain-specific: CodeEditor, Cropper, JsonViewer, RichTextEditor, Tour

Core Engine Modules

Module	Size	Description
`core/styles`	~1KB	useStyles(), css tag, adoptedStyleSheets, SSR
`core/motion`	~3.5KB	Spring solver, WAAPI, timeline, stagger, scroll, FLIP
`core/input`	~2.4KB	Unified pointer, gestures, focus, gamepad, multitouch
`core/tokens`	~1.5KB	OKLCH theme, generateTheme(), applyTheme()
`core/a11y`	~1KB	Focus trap, roving tabindex, live region, stable ID
`core/icons`	~2KB	50+ built-in SVG icons, all overridable
`core/forms`	~2KB	createForm, useForm, validators, Form, FieldArray
`core/utils`	~0.5KB	cn(), formatting, sanitize, clamp

Entry Points

import { Button, Dialog, DataTable } from '@annondeveloper/ui-kit'
import { Button as LiteButton } from '@annondeveloper/ui-kit/lite'
import { Button as PremiumButton } from '@annondeveloper/ui-kit/premium'
import { createForm, useForm, v } from '@annondeveloper/ui-kit/form'
import { generateTheme, themeToCSS } from '@annondeveloper/ui-kit/theme'
import '@annondeveloper/ui-kit/css/theme.css'  // Standalone CSS (optional)

Weight Tiers

Tier	Components	Description
Standard	147	Full-featured with motion, theming, a11y
Lite	144	Minimal wrappers, no motion (~0.3-1.2 KB each)
Premium	145	Aurora glow, spring animations, shimmer effects

Bundle Size

Metric	Value
Total (gzipped)	332.1 KB
Budget	350 KB
Tree-shaking	Full ESM — import only what you use

Typical app importing ~20 components: ~15-25 KB gzipped after tree-shaking.

Motion Levels

<UIProvider motion={2}>  {/* 0=none, 1=subtle, 2=expressive, 3=cinematic */}

v1 Documentation

The React component library for monitoring dashboards, infrastructure tools, and professional applications.

53 components • Dark/Light theme • Accessible • AI-ready • Real-time primitives • Tree-shakeable

GitHub • JSR • Demo

Quick Start

Install

# npm
npm install @annondeveloper/ui-kit

# pnpm
pnpm add @annondeveloper/ui-kit

# yarn
yarn add @annondeveloper/ui-kit

# bun
bun add @annondeveloper/ui-kit

# jsr
npx jsr add @annondeveloper/ui-kit

Peer Dependencies

npm install react react-dom framer-motion lucide-react clsx tailwind-merge sonner \
  @radix-ui/react-select @radix-ui/react-alert-dialog @radix-ui/react-tooltip \
  @radix-ui/react-popover @radix-ui/react-dropdown-menu

react-hook-form is an optional peer dependency -- only needed if you use the @annondeveloper/ui-kit/form entry point.

Theme Setup

Import the theme CSS once in your app's root layout:

import '@annondeveloper/ui-kit/theme.css'

Or copy the CSS custom properties into your own stylesheet. See Theme System below.

Minimal Example

import { Button, MetricCard, StatusBadge, Toaster } from '@annondeveloper/ui-kit'
import { Activity } from 'lucide-react'

function App() {
  return (
    <>
      <MetricCard label="CPU Usage" value={72.4} format={n => `${n.toFixed(1)}%`} icon={Activity} status="warning" />
      <StatusBadge status="active" pulse />
      <Button variant="primary" loading={isPending}>Deploy</Button>
      <Toaster />
    </>
  )
}

Why This Library?

Most component libraries are built for CRUD apps. This one is built for ops dashboards, infrastructure tools, and AI-powered interfaces -- where data density, real-time updates, and status visualization are first-class concerns.

Smart Components -- SmartTable auto-generates filter suggestions (outliers, top-N, patterns). CommandBar provides fuzzy search with recent history.
AI-Ready -- StreamingText renders LLM output with a blinking cursor. TypingIndicator, ConfidenceBar, and copy-on-complete are built in.
Real-Time -- RealtimeValue tracks data freshness with connection state indicators and stale-data dimming. LiveFeed auto-scrolls with pause controls. NotificationStack supports auto-dismiss with progress bars.
Monitoring -- MetricCard with trend arrows and sparklines. ThresholdGauge with color-coded zones. UtilizationBar, UptimeTracker, PortStatusGrid, and PipelineStage for infrastructure dashboards.
Data-Dense -- DataTable with 10+ features in one import (search, column filters, sort, pagination, density control, column picker, CSV export, row animations). HeatmapCalendar, SeverityTimeline, LogViewer for high-density displays.
Developer Experience -- CLI for scaffolding (npx @annondeveloper/ui-kit add button). react-hook-form adapters. Zero config theming. Full TypeScript coverage with exported types.

Component Reference

Core

Button

A themed button with variant, size, and loading support.

import { Button } from '@annondeveloper/ui-kit'

<Button variant="primary" size="md" loading={isPending}>Save</Button>

Prop	Type	Default	Description
`variant`	`'primary' \| 'secondary' \| 'danger' \| 'outline' \| 'ghost'`	`'primary'`	Visual variant
`size`	`'sm' \| 'md' \| 'lg' \| 'icon'`	`'md'`	Size preset
`loading`	`boolean`	`false`	Show spinner and disable interaction

Extends all native <button> attributes. Supports ref forwarding.

Badge

A pill-shaped label with 10 color presets and optional icon.

import { Badge, createBadgeVariant } from '@annondeveloper/ui-kit'
import { Shield } from 'lucide-react'

<Badge color="green" icon={Shield} size="sm">Secure</Badge>

Prop	Type	Default	Description
`children`	`ReactNode`	--	Badge content
`color`	`'brand' \| 'blue' \| 'green' \| 'yellow' \| 'red' \| 'orange' \| 'purple' \| 'pink' \| 'teal' \| 'gray'`	`'gray'`	Color preset
`icon`	`LucideIcon`	--	Optional icon before the label
`size`	`'xs' \| 'sm' \| 'md'`	`'sm'`	Size variant

Badge Factory

Create domain-specific badge components without modifying the library:

const SeverityBadge = createBadgeVariant({
  colorMap: { critical: 'red', warning: 'yellow', info: 'blue' },
  labelMap: { critical: 'Critical', warning: 'Warning', info: 'Info' },
})

<SeverityBadge value="critical" />

Card

A styled card container with subcomponents for semantic structure.

import { Card, CardHeader, CardTitle, CardContent } from '@annondeveloper/ui-kit'

<Card variant="interactive" padding="lg">
  <CardHeader><CardTitle>Server Health</CardTitle></CardHeader>
  <CardContent>...</CardContent>
</Card>

Prop	Type	Default	Description
`variant`	`'default' \| 'elevated' \| 'outlined' \| 'interactive'`	`'default'`	Visual variant (`interactive` adds hover effect)
`padding`	`'none' \| 'sm' \| 'md' \| 'lg'`	`'md'`	Padding preset

Subcomponents: CardHeader, CardTitle, CardDescription, CardContent, CardFooter. All support ref forwarding.

Tabs

Accessible tabbed interface with three visual variants and animated indicator.

import { Tabs } from '@annondeveloper/ui-kit'

<Tabs tabs={[{ value: 'metrics', label: 'Metrics' }, { value: 'logs', label: 'Logs' }]}
      value={tab} onChange={setTab} variant="pills" />

Prop	Type	Default	Description
`tabs`	`Tab[]`	--	Array of `{ value, label, icon?, disabled? }`
`value`	`string`	--	Currently selected tab value
`onChange`	`(value: string) => void`	--	Selection callback
`variant`	`'underline' \| 'pills' \| 'enclosed'`	`'underline'`	Visual variant
`size`	`'sm' \| 'md'`	`'md'`	Size preset

Supports keyboard navigation (arrow keys, Home, End) and ARIA roles. Animated indicator uses Framer Motion layoutId.

Sheet

A slide-over drawer panel from any screen edge.

import { Sheet } from '@annondeveloper/ui-kit'

<Sheet open={isOpen} onClose={() => setOpen(false)} title="Settings" side="right" width="max-w-lg">
  {children}
</Sheet>

Prop	Type	Default	Description
`open`	`boolean`	--	Whether the sheet is open
`onClose`	`() => void`	--	Close callback
`side`	`'right' \| 'left' \| 'top' \| 'bottom'`	`'right'`	Slide-in edge
`title`	`string`	--	Header title
`description`	`string`	--	Header description
`width`	`string`	`'max-w-md'`	Width/height class

Features: backdrop blur, spring animation, Escape to close, body scroll lock, auto-focus.

Tooltip

Simple tooltip wrapper built on Radix UI with theme-styled content and arrow pointer.

import { Tooltip } from '@annondeveloper/ui-kit'

<Tooltip content="Copy to clipboard" side="top"><button>...</button></Tooltip>

Prop	Type	Default	Description
`content`	`ReactNode`	--	Tooltip content
`children`	`ReactNode`	--	Trigger element
`side`	`'top' \| 'right' \| 'bottom' \| 'left'`	`'top'`	Display side
`delay`	`number`	`200`	Delay in ms

Popover

Popover wrapper built on Radix Popover with Framer Motion entry animation.

import { Popover } from '@annondeveloper/ui-kit'

<Popover trigger={<button>Options</button>} side="bottom" align="end">
  <p>Popover content</p>
</Popover>

Prop	Type	Default	Description
`trigger`	`ReactNode`	--	Element that opens the popover
`children`	`ReactNode`	--	Popover content
`side`	`'top' \| 'right' \| 'bottom' \| 'left'`	`'bottom'`	Display side
`align`	`'start' \| 'center' \| 'end'`	`'center'`	Alignment

DropdownMenu

Action/context dropdown menu built on Radix DropdownMenu with danger variant support.

import { DropdownMenu } from '@annondeveloper/ui-kit'
import { Edit, Trash2 } from 'lucide-react'

<DropdownMenu
  trigger={<button>Actions</button>}
  items={[
    { label: 'Edit', icon: Edit, onClick: handleEdit },
    { label: 'Delete', icon: Trash2, onClick: handleDelete, variant: 'danger' },
  ]}
/>

Prop	Type	Default	Description
`trigger`	`ReactNode`	--	Element that opens the menu
`items`	`MenuItem[]`	--	`{ label, icon?, onClick, variant?, disabled? }`
`align`	`'start' \| 'center' \| 'end'`	`'end'`	Menu alignment

ConfirmDialog

Confirmation modal built on Radix AlertDialog with animated enter/exit.

import { ConfirmDialog } from '@annondeveloper/ui-kit'

<ConfirmDialog
  open={showDelete} onOpenChange={setShowDelete}
  title="Delete server?" description="This action cannot be undone."
  variant="danger" confirmLabel="Delete" loading={isDeleting}
  onConfirm={handleDelete}
/>

Prop	Type	Default	Description
`open`	`boolean`	--	Control open state
`onOpenChange`	`(open: boolean) => void`	--	Open state callback
`title`	`string`	--	Dialog title
`description`	`string`	--	Dialog description
`confirmLabel`	`string`	`'Confirm'`	Confirm button text
`cancelLabel`	`string`	`'Cancel'`	Cancel button text
`variant`	`'danger' \| 'warning' \| 'default'`	`'danger'`	Icon and button color
`loading`	`boolean`	`false`	Show spinner on confirm button
`onConfirm`	`() => void`	--	Confirm callback

Forms

FormInput

Themed form input with label, required indicator, and optional hint text.

import { FormInput } from '@annondeveloper/ui-kit'

<FormInput label="Hostname" value={host} onChange={setHost} placeholder="10.0.0.1" required hint="IPv4 or FQDN" />

Prop	Type	Default	Description
`label`	`string`	--	Label text
`value`	`string`	--	Input value
`onChange`	`(value: string) => void`	--	Value change callback
`type`	`string`	`'text'`	HTML input type
`placeholder`	`string`	--	Placeholder text
`required`	`boolean`	--	Show required indicator
`disabled`	`boolean`	--	Disable input
`hint`	`string`	--	Help text below input
`autoComplete`	`string`	--	Autocomplete attribute

Also exports INPUT_CLS, LABEL_CLS, and TEXTAREA_CLS constants for building custom inputs with consistent styling.

Select

Themed dropdown built on Radix UI Select.

import { Select } from '@annondeveloper/ui-kit'

<Select value={protocol} onValueChange={setProtocol}
        options={[{ value: 'snmp', label: 'SNMP' }, { value: 'ssh', label: 'SSH' }]}
        placeholder="Select protocol" />

Prop	Type	Default	Description
`value`	`string`	--	Selected value
`onValueChange`	`(v: string) => void`	--	Selection callback
`options`	`SelectOption[]`	--	`{ value, label }`
`placeholder`	`string`	--	Placeholder text
`disabled`	`boolean`	--	Disable select

Checkbox

Themed checkbox with indeterminate state support. Forwards ref.

import { Checkbox } from '@annondeveloper/ui-kit'

<Checkbox checked={selected} onChange={handleChange} indeterminate={isPartial} size="sm" />

Prop	Type	Default	Description
`indeterminate`	`boolean`	--	Show minus indicator
`size`	`'sm' \| 'md'`	`'md'`	Size variant

Extends native <input> attributes (except type and size).

ToggleSwitch

Icon-based boolean toggle using lucide icons.

import { ToggleSwitch } from '@annondeveloper/ui-kit'

<ToggleSwitch enabled={isActive} onChange={setIsActive} label="Auto-refresh" />

Prop	Type	Default	Description
`enabled`	`boolean`	--	Toggle state
`onChange`	`(enabled: boolean) => void`	--	Change callback
`size`	`'sm' \| 'md'`	`'md'`	Size variant
`disabled`	`boolean`	--	Disable toggle
`label`	`string`	--	Accessible label

RadioGroup

Custom-styled radio button group with animated selection indicator.

import { RadioGroup } from '@annondeveloper/ui-kit'

<RadioGroup
  options={[
    { value: 'v2c', label: 'SNMPv2c' },
    { value: 'v3', label: 'SNMPv3', description: 'Recommended for production' },
  ]}
  value={version} onChange={setVersion} orientation="vertical"
/>

Prop	Type	Default	Description
`options`	`RadioOption[]`	--	`{ value, label, description?, disabled? }`
`value`	`string`	--	Selected value
`onChange`	`(value: string) => void`	--	Selection callback
`orientation`	`'horizontal' \| 'vertical'`	`'vertical'`	Layout direction

Supports keyboard navigation (arrow keys, Home, End) and ARIA roles.

Slider

Custom range slider with keyboard accessibility and hover tooltip.

import { Slider } from '@annondeveloper/ui-kit'

<Slider value={threshold} onChange={setThreshold} min={0} max={100} step={5} label="Alert threshold" showValue />

Prop	Type	Default	Description
`value`	`number`	--	Current value
`onChange`	`(value: number) => void`	--	Change callback
`min`	`number`	`0`	Minimum value
`max`	`number`	`100`	Maximum value
`step`	`number`	`1`	Step increment
`label`	`string`	--	Label text
`showValue`	`boolean`	`false`	Show value display

Supports keyboard (arrow keys, Home, End), mouse drag, and touch.

ColorInput

Compact color picker with expandable panel, hue/saturation area, format switching, and presets.

import { ColorInput } from '@annondeveloper/ui-kit'

<ColorInput value={color} onChange={setColor} label="Accent" format="hex"
            presets={['#3b82f6', '#10b981', '#f59e0b', '#ef4444']} />

Prop	Type	Default	Description
`value`	`string`	--	Hex color string
`onChange`	`(color: string) => void`	--	Change callback
`label`	`string`	--	Optional label
`presets`	`string[]`	--	Preset color swatches
`showAlpha`	`boolean`	`false`	Show alpha slider
`format`	`'hex' \| 'rgb' \| 'hsl'`	`'hex'`	Display format

Features: HSL picker area, hue slider, format switching, clipboard copy, recent color history (localStorage).

StepWizard

Multi-step form wizard with animated slide transitions and per-step validation.

import { StepWizard } from '@annondeveloper/ui-kit'

<StepWizard
  steps={[
    { id: 'creds', title: 'Credentials', content: <CredentialsForm /> },
    { id: 'targets', title: 'Targets', content: <TargetForm />, validate: () => targets.length > 0 },
    { id: 'review', title: 'Review', content: <ReviewSummary /> },
  ]}
  onComplete={handleDeploy} showSummary
/>

Prop	Type	Default	Description
`steps`	`WizardStep[]`	--	`{ id, title, description?, icon?, content, validate? }`
`onComplete`	`() => void`	--	Final step completion callback
`onStepChange`	`(step: number) => void`	--	Step change callback
`orientation`	`'horizontal' \| 'vertical'`	`'horizontal'`	Step indicator layout
`allowSkip`	`boolean`	`false`	Allow skipping to uncompleted steps
`showSummary`	`boolean`	`false`	Show completion state after last step

Features: animated step transitions, progress bar, keyboard navigation (Enter to advance), session storage auto-save, async validation.

FilterPill

Rounded pill-style filter toggle with optional count.

import { FilterPill } from '@annondeveloper/ui-kit'

<FilterPill label="Critical" count={12} active={filter === 'critical'} onClick={() => setFilter('critical')} />

Prop	Type	Default	Description
`label`	`string`	--	Pill text
`count`	`number`	--	Optional count badge
`active`	`boolean`	--	Active/selected state
`onClick`	`() => void`	--	Click handler

Data Display

DataTable

Full-featured data grid built on TanStack Table v8.

import { DataTable } from '@annondeveloper/ui-kit'

<DataTable
  columns={columns} data={devices} isLoading={isLoading}
  searchPlaceholder="Search devices..."
  defaultPageSize={25} exportFilename="devices"
  onRowClick={(row) => router.push(`/devices/${row.id}`)}
  emptyState={{ icon: Server, title: 'No devices', description: 'Run a discovery scan to get started.' }}
/>

Prop	Type	Default	Description
`columns`	`ColumnDef<T>[]`	--	TanStack column definitions
`data`	`T[]`	--	Row data
`isLoading`	`boolean`	`false`	Show loading skeleton
`emptyState`	`{ icon, title, description }`	--	Custom empty state
`searchPlaceholder`	`string`	`'Search...'`	Search input placeholder
`onRowClick`	`(row: T) => void`	--	Row click handler
`defaultSort`	`{ id, desc }`	--	Initial sort configuration
`defaultPageSize`	`number`	`25`	Rows per page
`exportFilename`	`string`	--	Enables CSV export button
`stickyFirstColumn`	`boolean`	`false`	Sticky first column on scroll
`density`	`'compact' \| 'comfortable' \| 'spacious'`	`'comfortable'`	Row density

Built-in features: global search, auto-detected column filters (text/enum/number range), multi-column sort, pagination, density control (persisted to localStorage), column visibility picker with drag reorder, CSV export, row click, loading skeleton, empty state, Framer Motion row animations.

SmartTable

Enhanced DataTable that auto-generates filter suggestions by analyzing column data.

import { SmartTable } from '@annondeveloper/ui-kit'

<SmartTable columns={columns} data={data} maxSuggestions={4} onFilterSuggestion={console.log} />

Prop	Type	Default	Description
...all DataTable props			Inherits all DataTable props
`onFilterSuggestion`	`(suggestion: FilterSuggestion) => void`	--	Suggestion click callback
`maxSuggestions`	`number`	`6`	Max visible suggestions

Auto-detects: statistical outliers (>2 std dev), top-N frequent values, dominant pattern detection, minority value highlighting.

AnimatedCounter

Smooth number animation using requestAnimationFrame with cubic easing.

import { AnimatedCounter } from '@annondeveloper/ui-kit'

<AnimatedCounter value={deviceCount} duration={400} format={n => n.toLocaleString()} />

Prop	Type	Default	Description
`value`	`number`	--	Target value
`duration`	`number`	`400`	Animation duration (ms)
`format`	`(n: number) => string`	--	Custom number formatter

Sparkline

Tiny inline SVG sparkline chart with gradient fill.

import { Sparkline } from '@annondeveloper/ui-kit'

<Sparkline data={[10, 25, 18, 30, 22]} width={80} height={24} showDots />

Prop	Type	Default	Description
`data`	`number[]`	--	Values to plot (min 2)
`width`	`number`	`80`	SVG width
`height`	`number`	`24`	SVG height
`color`	`string`	`'hsl(var(--brand-primary))'`	Line color
`fillOpacity`	`number`	`0.1`	Gradient fill opacity (0 to disable)
`showDots`	`boolean`	`false`	Dots on first/last points

TruncatedText

Auto-truncating text with tooltip and copy-to-clipboard on hover.

import { TruncatedText } from '@annondeveloper/ui-kit'

<TruncatedText text="very-long-hostname-that-overflows.example.com" maxWidth={200} />

Prop	Type	Default	Description
`text`	`string`	--	Full text content
`maxWidth`	`string \| number`	`'100%'`	Max width for truncation

CopyBlock

Monospace code/text display with one-click copy and collapsible overflow.

import { CopyBlock } from '@annondeveloper/ui-kit'

<CopyBlock content="curl -X GET https://api.example.com/health" language="bash" label="Health check" />

Prop	Type	Default	Description
`content`	`string`	--	Text content
`language`	`string`	--	Language hint (e.g. "json", "bash")
`showLineNumbers`	`boolean`	`false`	Show line number gutter
`maxHeight`	`number`	--	Max height before "Show more" toggle
`label`	`string`	--	Label above the block

DiffViewer

Line-by-line diff viewer using LCS algorithm with collapsible unchanged sections.

import { DiffViewer } from '@annondeveloper/ui-kit'

<DiffViewer oldValue={previousConfig} newValue={currentConfig} mode="side-by-side" showLineNumbers />

Prop	Type	Default	Description
`oldValue`	`string`	--	Original text
`newValue`	`string`	--	Modified text
`mode`	`'inline' \| 'side-by-side'`	`'inline'`	Display mode
`language`	`string`	--	Language hint
`showLineNumbers`	`boolean`	`true`	Show line numbers

Status & Monitoring

StatusBadge

Configurable status indicator with colored dot and label.

import { StatusBadge, defaultStatusMap } from '@annondeveloper/ui-kit'

<StatusBadge status="active" pulse />
<StatusBadge status="healthy" statusMap={myCustomStatuses} />

Prop	Type	Default	Description
`status`	`string`	--	Status key
`label`	`string`	--	Override display label
`size`	`'sm' \| 'md'`	`'md'`	Size variant
`pulse`	`boolean`	`false`	Pulse animation on the dot
`statusMap`	`Record<string, StatusConfig>`	`defaultStatusMap`	Custom status definitions

Built-in statuses: ok, active, warning, critical, unknown, maintenance, stale, inactive, decommissioned, pending.

StatusPulse

Animated status dot with optional pulse ring and label.

import { StatusPulse } from '@annondeveloper/ui-kit'

<StatusPulse status="online" />
<StatusPulse status="degraded" label={false} />

Prop	Type	Default	Description
`status`	`string`	--	Status key
`label`	`boolean`	`true`	Show status text
`configMap`	`Record<string, PulseConfig>`	`defaultPulseConfigMap`	Custom pulse configs

Built-in statuses: online (green pulse), degraded (yellow fast pulse), offline (red, no pulse), unknown (gray, no pulse).

MetricCard

Dashboard stat tile with animated counter, trend indicator, and optional sparkline.

import { MetricCard } from '@annondeveloper/ui-kit'
import { HardDrive } from 'lucide-react'

<MetricCard
  label="Disk Usage" value={78.3} format={n => `${n.toFixed(1)}%`}
  previousValue={72.1} trendDirection="up-bad"
  icon={HardDrive} status="warning"
  sparklineData={[65, 68, 70, 72, 75, 78]}
/>

Prop	Type	Default	Description
`label`	`string`	--	Metric name
`value`	`number`	--	Current value
`format`	`(n: number) => string`	--	Custom formatter
`previousValue`	`number`	--	Previous value for trend
`trendDirection`	`'up-good' \| 'up-bad' \| 'down-good' \| 'down-bad'`	--	Color interpretation
`icon`	`ElementType`	--	Lucide icon component
`status`	`'ok' \| 'warning' \| 'critical'`	--	Left border accent color
`sparklineData`	`number[]`	--	Recent values for inline chart

ThresholdGauge

Semicircular SVG gauge with color-coded threshold zones.

import { ThresholdGauge } from '@annondeveloper/ui-kit'

<ThresholdGauge value={85} label="CPU" thresholds={{ warning: 70, critical: 90 }} size={120} />

Prop	Type	Default	Description
`value`	`number`	--	Gauge value (0-100)
`label`	`string`	--	Label below gauge
`thresholds`	`{ warning, critical }`	`{ warning: 70, critical: 90 }`	Color zone boundaries
`size`	`number`	`120`	Diameter in pixels
`showValue`	`boolean`	`true`	Show value in center
`format`	`(n: number) => string`	--	Custom value formatter

UtilizationBar

Horizontal bar with color-coded thresholds. Animates fill on mount.

import { UtilizationBar } from '@annondeveloper/ui-kit'

<UtilizationBar value={92} label="Memory" thresholds={{ warning: 70, critical: 90 }} size="md" />

Prop	Type	Default	Description
`value`	`number`	--	Utilization percentage (0-100)
`thresholds`	`{ warning, critical }`	`{ warning: 70, critical: 90 }`	Color zone boundaries
`label`	`string`	--	Label to the left
`showValue`	`boolean`	`true`	Show percentage text
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Bar height
`animated`	`boolean`	`true`	Animate fill width

UptimeTracker

GitHub/Statuspage-style daily uptime bar strip.

import { UptimeTracker } from '@annondeveloper/ui-kit'

<UptimeTracker
  days={last90Days} label="API Server" showPercentage
  onDayClick={(day) => showIncidents(day.date)}
/>

Prop	Type	Default	Description
`days`	`DayStatus[]`	--	`{ date, status: 'ok'\|'degraded'\|'outage'\|'no-data', uptime? }`
`showPercentage`	`boolean`	`true`	Show overall uptime %
`label`	`string`	--	Header label
`onDayClick`	`(day: DayStatus) => void`	--	Day click callback

PortStatusGrid

Grid of colored indicators for network ports/interfaces.

import { PortStatusGrid } from '@annondeveloper/ui-kit'

<PortStatusGrid
  ports={switchPorts} columns={24} size="md"
  onPortClick={(port) => showPortDetail(port.id)}
/>

Prop	Type	Default	Description
`ports`	`PortStatus[]`	--	`{ id, label, status: 'up'\|'down'\|'disabled'\|'error', speed?, utilization? }`
`columns`	`number`	auto-fit	Grid columns
`size`	`'sm' \| 'md'`	`'sm'`	Indicator size
`onPortClick`	`(port: PortStatus) => void`	--	Port click callback

PipelineStage

Horizontal data pipeline visualization with status dots and chevron connectors.

import { PipelineStage } from '@annondeveloper/ui-kit'

<PipelineStage
  stages={[
    { name: 'Collector', status: 'active', metric: { label: 'msg/s', value: '1.2K' } },
    { name: 'Normalizer', status: 'active' },
    { name: 'Writer', status: 'error' },
  ]}
  onStageClick={(stage) => showStageDetail(stage)}
/>

Prop	Type	Default	Description
`stages`	`StageInfo[]`	--	`{ name, status: 'active'\|'idle'\|'error'\|'disabled', metric?, icon? }`
`onStageClick`	`(stage, index) => void`	--	Stage click callback

SeverityTimeline

Horizontal scrollable event timeline with severity-colored dots.

import { SeverityTimeline } from '@annondeveloper/ui-kit'

<SeverityTimeline events={recentAlerts} maxVisible={20} onEventClick={showAlertDetail} />

Prop	Type	Default	Description
`events`	`TimelineEvent[]`	--	`{ time, label, severity: 'critical'\|'warning'\|'info'\|'ok', detail? }`
`maxVisible`	`number`	`20`	Max visible events
`onEventClick`	`(event) => void`	--	Event click callback

TimeRangeSelector

Compact horizontal pill-group time range selector.

import { TimeRangeSelector } from '@annondeveloper/ui-kit'

<TimeRangeSelector value={range} onChange={(v, r) => setRange(v)} />

Prop	Type	Default	Description
`value`	`string`	--	Selected range value
`onChange`	`(value, range) => void`	--	Selection callback
`ranges`	`TimeRange[]`	`[1h, 6h, 24h, 7d, 30d]`	Custom range options (each `{ label, value, seconds }`)

LogViewer

Real-time log stream viewer with severity-colored borders and auto-scroll.

import { LogViewer } from '@annondeveloper/ui-kit'

<LogViewer entries={logs} maxHeight={400} autoScroll showTimestamps onEntryClick={showDetail} />

Prop	Type	Default	Description
`entries`	`LogEntry[]`	--	`{ time, level: 'error'\|'warn'\|'info'\|'debug'\|'trace', message, source? }`
`maxHeight`	`number`	`400`	Container max height
`autoScroll`	`boolean`	`true`	Auto-scroll on new entries
`showTimestamps`	`boolean`	`true`	Show timestamps column
`showLevel`	`boolean`	`true`	Show level badge
`onEntryClick`	`(entry) => void`	--	Entry click callback

Features: search filtering, "N new entries" floating badge when scrolled up.

Real-Time & AI

RealtimeValue

Live data display with freshness tracking, connection state, and delta arrows.

import { RealtimeValue } from '@annondeveloper/ui-kit'
import { fmtBps } from '@annondeveloper/ui-kit'

<RealtimeValue
  value={throughput} format={fmtBps}
  previousValue={prevThroughput} lastUpdated={lastTs}
  staleAfterMs={30000} connectionState="connected" size="lg"
/>

Prop	Type	Default	Description
`value`	`number \| string`	--	Current value
`label`	`string`	--	Label text
`format`	`(v: number) => string`	--	Custom formatter
`lastUpdated`	`string \| Date`	--	Last data timestamp
`staleAfterMs`	`number`	`30000`	Staleness threshold (ms)
`connectionState`	`'connected' \| 'reconnecting' \| 'disconnected'`	`'connected'`	Connection indicator
`previousValue`	`number`	--	Previous value for delta
`animate`	`boolean`	`true`	Animate value changes
`size`	`'sm' \| 'md' \| 'lg' \| 'xl'`	`'md'`	Display size

Features: animated number transitions, freshness dot (green/yellow/red), ping animation when fresh, connection state icon (reconnecting spinner, disconnected icon), auto-updating relative timestamp.

StreamingText

AI/LLM streaming text display with blinking cursor and inline markdown formatting.

import { StreamingText } from '@annondeveloper/ui-kit'

<StreamingText text={response} isStreaming={isGenerating} onComplete={() => logCompletion()} />

Prop	Type	Default	Description
`text`	`string`	--	Text content (grows as tokens arrive)
`isStreaming`	`boolean`	--	Whether tokens are still arriving
`speed`	`number`	`500`	Cursor blink speed (ms)
`showCursor`	`boolean`	`true`	Show blinking cursor
`onComplete`	`() => void`	--	Streaming complete callback

Features: auto-scroll during streaming, inline **bold** and `code` formatting, copy button appears on completion.

TypingIndicator

"Someone is typing" indicator with three animation variants.

import { TypingIndicator } from '@annondeveloper/ui-kit'

<TypingIndicator variant="dots" label="AI is thinking" size="md" />

Prop	Type	Default	Description
`label`	`string`	--	Status text
`variant`	`'dots' \| 'pulse' \| 'text'`	`'dots'`	Animation variant
`size`	`'sm' \| 'md'`	`'md'`	Size preset

ConfidenceBar

Horizontal probability bar with color-coded threshold zones.

import { ConfidenceBar } from '@annondeveloper/ui-kit'

<ConfidenceBar value={0.87} label="Match confidence" thresholds={{ low: 0.3, medium: 0.7 }} />

Prop	Type	Default	Description
`value`	`number`	--	Confidence (0-1)
`label`	`string`	--	Label text
`showPercentage`	`boolean`	`true`	Show percentage
`thresholds`	`{ low, medium }`	`{ low: 0.3, medium: 0.7 }`	Color zone boundaries
`size`	`'sm' \| 'md'`	`'md'`	Bar height

CommandBar

Universal command palette activated by Cmd+K / Ctrl+K.

import { CommandBar } from '@annondeveloper/ui-kit'

<CommandBar
  items={[
    { id: 'devices', label: 'Go to Devices', shortcut: 'G D', onSelect: () => navigate('/devices') },
    { id: 'search', label: 'Search entities', icon: Search, onSelect: openSearch, keywords: ['find'] },
  ]}
  placeholder="Type a command..."
  onSearch={async (q) => fetchResults(q)}
/>

Prop	Type	Default	Description
`items`	`CommandItem[]`	--	`{ id, label, description?, icon?, shortcut?, group?, onSelect, keywords? }`
`placeholder`	`string`	`'Type a command...'`	Search placeholder
`hotkey`	`string`	`'k'`	Hotkey letter (Cmd/Ctrl+key)
`onSearch`	`(query) => Promise<CommandItem[]>`	--	Async search function
`recentKey`	`string`	`'ui-kit-command-recent'`	localStorage key for recents
`maxRecent`	`number`	`5`	Max recent items

Features: fuzzy search scoring, grouped sections, recent selections (localStorage), async search with debounce, keyboard navigation (arrows + Enter), keyboard shortcut hints in footer.

LiveFeed

Real-time event feed with animated entry, pause/resume, and type-colored borders.

import { LiveFeed } from '@annondeveloper/ui-kit'

<LiveFeed
  items={events} maxVisible={50} showTimestamps autoScroll
  onItemClick={(item) => showDetail(item.id)}
  emptyMessage="Waiting for events..."
/>

Prop	Type	Default	Description
`items`	`FeedItem[]`	--	`{ id, content: ReactNode, timestamp, type?: 'info'\|'success'\|'warning'\|'error' }`
`maxVisible`	`number`	`50`	Max visible items
`showTimestamps`	`boolean`	`true`	Show relative timestamps
`autoScroll`	`boolean`	`true`	Auto-scroll to newest
`onItemClick`	`(item) => void`	--	Item click callback
`emptyMessage`	`string`	`'No events yet'`	Empty state text

Features: pause/resume button, "N new items" floating badge when scrolled, auto-updating relative timestamps.

NotificationStack

Fixed-position notification cards with auto-dismiss progress bars.

import { NotificationStack } from '@annondeveloper/ui-kit'

<NotificationStack
  notifications={notifications}
  onDismiss={(id) => removeNotification(id)}
  position="top-right" maxVisible={5}
/>

Prop	Type	Default	Description
`notifications`	`Notification[]`	--	`{ id, title, message?, type, action?, dismissible?, duration? }`
`onDismiss`	`(id: string) => void`	--	Dismiss callback
`position`	`'top-right' \| 'top-left' \| 'bottom-right' \| 'bottom-left'`	`'top-right'`	Screen position
`maxVisible`	`number`	`5`	Max visible before stacking

Features: type-specific icons and colors, action buttons, auto-dismiss with progress bar, overflow indicator, spring entry/exit animations.

Layout & Feedback

EmptyState

Decorative placeholder with icon, title, description, and optional actions.

import { EmptyState, Button } from '@annondeveloper/ui-kit'
import { Inbox } from 'lucide-react'

<EmptyState icon={Inbox} title="No alerts" description="Your infrastructure is healthy."
            actions={<Button size="sm">Configure Rules</Button>} />

Prop	Type	Default	Description
`icon`	`LucideIcon`	--	Center icon
`title`	`string`	--	Title text
`description`	`string`	--	Description text
`actions`	`ReactNode`	--	Action buttons

Skeleton / SkeletonText / SkeletonCard

Shimmer loading placeholders.

import { Skeleton, SkeletonText, SkeletonCard } from '@annondeveloper/ui-kit'

<Skeleton className="h-8 w-32" />
<SkeletonText lines={3} />
<SkeletonCard />

SkeletonText props: lines?: number (default 1).

Progress

Progress bar with optional label, animated fill, and indeterminate mode.

import { Progress } from '@annondeveloper/ui-kit'

<Progress value={65} max={100} label="Upload" showValue variant="success" />
<Progress indeterminate label="Processing..." />

Prop	Type	Default	Description
`value`	`number`	--	Current value
`max`	`number`	`100`	Maximum value
`label`	`string`	--	Label text
`showValue`	`boolean`	`false`	Show percentage
`variant`	`'default' \| 'success' \| 'warning' \| 'danger'`	`'default'`	Color variant
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Bar height
`animated`	`boolean`	`true`	Animate fill changes
`indeterminate`	`boolean`	`false`	Shimmer animation

Avatar

User/entity avatar with image support, initials fallback, and status dot.

import { Avatar } from '@annondeveloper/ui-kit'

<Avatar src="/avatar.jpg" alt="Jane Doe" size="md" status="online" />
<Avatar alt="John Smith" size="sm" />  {/* Shows "JS" initials */}

Prop	Type	Default	Description
`src`	`string`	--	Image URL
`alt`	`string`	--	Alt text (used for initials derivation)
`fallback`	`string`	--	Override initials
`size`	`'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`	`'md'`	Size preset
`status`	`'online' \| 'offline' \| 'busy' \| 'away'`	--	Status dot overlay

InfiniteScroll

Virtualized infinite-scroll list using IntersectionObserver.

import { InfiniteScroll } from '@annondeveloper/ui-kit'

<InfiniteScroll
  items={logs} hasMore={hasNextPage} isLoading={isFetching}
  loadMore={fetchNextPage} itemHeight={48}
  renderItem={(item, i) => <LogRow key={item.id} entry={item} />}
/>

Prop	Type	Default	Description
`items`	`T[]`	--	Loaded items
`renderItem`	`(item, index) => JSX.Element`	--	Item renderer
`loadMore`	`() => void \| Promise<void>`	--	Load more callback
`hasMore`	`boolean`	--	Whether more items exist
`isLoading`	`boolean`	`false`	Loading state
`threshold`	`number`	`200`	Trigger distance from bottom (px)
`itemHeight`	`number`	--	Fixed height for virtualization
`emptyState`	`ReactNode`	--	Empty content

Features: optional height-based virtualization, scroll-to-top button, skeleton placeholders.

SortableList

Drag-and-drop reorderable list with smooth layout animations.

import { SortableList, DragHandle } from '@annondeveloper/ui-kit'

<SortableList
  items={rules} onReorder={setRules}
  renderItem={(item, i, dragProps) => (
    <div className="flex items-center gap-2 p-3">
      <DragHandle {...dragProps} />
      <span>{item.name}</span>
    </div>
  )}
/>

Prop	Type	Default	Description
`items`	`T[]` (each needs `id: string`)	--	Items to display
`onReorder`	`(items: T[]) => void`	--	Reorder callback
`renderItem`	`(item, index, dragHandleProps) => JSX.Element`	--	Item renderer
`direction`	`'vertical' \| 'horizontal'`	`'vertical'`	Layout direction

Features: pointer-based drag (no external DnD library), keyboard reordering (Space to pick, arrows to move, Enter to drop), touch support, drop indicator line.

KanbanColumn

Kanban board column with title, count badge, and scrollable card list.

import { KanbanColumn } from '@annondeveloper/ui-kit'

<KanbanColumn
  title="In Progress" color="hsl(var(--status-warning))"
  items={tasks} onItemClick={showTask} onAddItem={createTask}
/>

Prop	Type	Default	Description
`title`	`string`	--	Column title
`items`	`KanbanItem[]`	--	`{ id, title, description?, tags?, assignee? }`
`count`	`number`	--	Override count badge
`color`	`string`	--	Header accent color
`onItemClick`	`(item) => void`	--	Card click callback
`onAddItem`	`() => void`	--	Add button callback

HeatmapCalendar

GitHub-style contribution heatmap calendar with configurable color scale.

import { HeatmapCalendar } from '@annondeveloper/ui-kit'

<HeatmapCalendar data={dailyMetrics} onDayClick={(d) => showDayDetail(d.date)} showMonthLabels showDayLabels />

Prop	Type	Default	Description
`data`	`DayValue[]`	--	`{ date: 'YYYY-MM-DD', value: number }`
`startDate`	`string`	365 days ago	Start date
`endDate`	`string`	Today	End date
`colorScale`	`string[]`	Green 5-step scale	5 colors lightest to darkest
`onDayClick`	`(day) => void`	--	Day click callback
`showMonthLabels`	`boolean`	`true`	Month labels at top
`showDayLabels`	`boolean`	`true`	Day-of-week labels
`tooltipFormat`	`(day) => string`	--	Custom tooltip format

Toaster / toast

Pre-themed Sonner toast container. Import once, use toast() anywhere.

// In layout:
import { Toaster } from '@annondeveloper/ui-kit'
<Toaster theme="dark" position="bottom-right" />

// Anywhere:
import { toast } from '@annondeveloper/ui-kit'
toast.success('Deployment complete')
toast.error('Connection failed')

Prop	Type	Default	Description
`theme`	`'dark' \| 'light'`	`'dark'`	Toast theme
`position`	Sonner positions	`'bottom-right'`	Screen position
`duration`	`number`	`4000`	Auto-dismiss (ms)

SuccessCheckmark

Animated SVG checkmark with circle and path draw animations.

import { SuccessCheckmark } from '@annondeveloper/ui-kit'

<SuccessCheckmark size={24} />

Prop	Type	Default	Description
`size`	`number`	`20`	SVG size in pixels

Utilities

Class Merging

import { cn } from '@annondeveloper/ui-kit'

cn('px-4 py-2', isActive && 'bg-blue-500', className)

Formatters

Function	Example	Output
`fmtBps(n)`	`fmtBps(1_000_000_000)`	`"1.0 Gbps"`
`fmtSpeed(n)`	`fmtSpeed(10_000_000_000)`	`"10G"`
`fmtBytes(n)`	`fmtBytes(1_073_741_824)`	`"1.0 GB"`
`fmtPct(n, d?)`	`fmtPct(95.6)`	`"95.6%"`
`fmtUptime(secs)`	`fmtUptime(90061)`	`"1d 1h"`
`fmtRelative(iso)`	`fmtRelative('2024-01-01')`	`"3d ago"`
`fmtCompact(n)`	`fmtCompact(480_933_305)`	`"480.9M"`
`fmtDuration(secs)`	`fmtDuration(0.003)`	`"3ms"`
`fmtUtil(bps, speed)`	`fmtUtil(500_000_000, 1_000_000_000)`	`"50%"`
`stripCidr(ip)`	`stripCidr('10.0.0.1/32')`	`"10.0.0.1"`
`clamp(v, min, max)`	`clamp(150, 0, 100)`	`100`

utilColor

Returns a Tailwind class based on utilization percentage:

import { utilColor, defaultUtilColorMap } from '@annondeveloper/ui-kit'

utilColor(85)                        // "text-[hsl(var(--status-critical))]"
utilColor(45)                        // "text-[hsl(var(--status-ok))]"
utilColor(75, customColorMap)        // uses your thresholds

The defaultUtilColorMap thresholds: >= 80% critical (red), >= 60% warning (yellow), < 60% ok (green).

createBadgeVariant

Factory for domain-specific badge components. See Badge section above.

Theme System

The library uses CSS custom properties for theming. Dark mode is the default; add the light class to <html> for light mode.

Token Reference

Token	Purpose	Dark Default	Light Default
`--bg-base`	Page background	`222 47% 7%`	`210 40% 98%`
`--bg-surface`	Card/panel background	`222 40% 10%`	`0 0% 100%`
`--bg-elevated`	Elevated surface (dropdowns, popovers)	`222 35% 14%`	`210 40% 96%`
`--bg-overlay`	Overlay/hover background	`222 30% 18%`	`210 30% 92%`
`--border-subtle`	Subtle borders	`222 30% 20%`	`210 20% 88%`
`--border-default`	Default borders	`222 25% 25%`	`210 20% 80%`
`--border-strong`	Strong/focus borders	`222 20% 35%`	`210 20% 65%`
`--text-primary`	Primary text	`210 40% 95%`	`222 47% 11%`
`--text-secondary`	Secondary text	`210 20% 70%`	`222 25% 35%`
`--text-tertiary`	Tertiary text	`210 15% 50%`	`222 15% 55%`
`--text-disabled`	Disabled text	`210 10% 35%`	`222 10% 75%`
`--brand-primary`	Brand/accent color	`217 91% 60%`	`217 91% 50%`
`--brand-secondary`	Secondary accent	`258 80% 65%`	`258 80% 58%`
`--text-on-brand`	Text on brand backgrounds	`0 0% 100%`	`0 0% 100%`
`--status-ok`	Success/online	`142 71% 45%`	`142 71% 38%`
`--status-warning`	Warning/degraded	`38 92% 50%`	`38 92% 42%`
`--status-critical`	Critical/error	`0 84% 60%`	`0 84% 52%`
`--status-unknown`	Unknown status	`220 15% 50%`	`220 15% 55%`
`--status-maintenance`	Maintenance mode	`258 60% 65%`	`258 60% 58%`
`--chart-1` through `--chart-8`	Chart color series	Various	Various

Customization

Override any token in your own CSS:

:root {
  --brand-primary: 160 84% 39%;    /* teal accent */
  --status-ok: 160 84% 39%;
}

Theme Toggle

function ThemeToggle() {
  const toggle = () => document.documentElement.classList.toggle('light')
  return <button onClick={toggle}>Toggle theme</button>
}

Typography Scale

The theme CSS includes utility classes: .text-display, .text-heading-1, .text-heading-2, .text-heading-3, .text-body, .text-small, .text-label.

CLI

Scaffold components directly into your project -- shadcn/ui-style.

Initialize

npx @annondeveloper/ui-kit init

Copies theme.css and utils.ts into your target directory (default ./components/ui).

Add a Component

npx @annondeveloper/ui-kit add button
npx @annondeveloper/ui-kit add data-table
npx @annondeveloper/ui-kit add metric-card

Copies the component source file and resolves internal dependencies automatically.

List Available Components

npx @annondeveloper/ui-kit list

Options

Flag	Description
`--dir <path>`	Target directory (default `./components/ui`)
`--overwrite`	Overwrite existing files

Form Integration

Install the optional peer dependency:

npm install react-hook-form

Import from the dedicated entry point:

import { RHFFormInput, RHFSelect, RHFCheckbox, RHFToggleSwitch } from '@annondeveloper/ui-kit/form'

Example with Validation

import { useForm } from 'react-hook-form'
import { RHFFormInput, RHFSelect } from '@annondeveloper/ui-kit/form'
import { Button } from '@annondeveloper/ui-kit'

function CredentialForm() {
  const { control, handleSubmit } = useForm({
    defaultValues: { hostname: '', protocol: '' },
  })

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <RHFFormInput
        control={control} name="hostname" label="Hostname"
        rules={{ required: 'Hostname is required' }} placeholder="10.0.0.1"
      />
      <RHFSelect
        control={control} name="protocol" label="Protocol"
        options={[{ value: 'snmp', label: 'SNMP' }, { value: 'ssh', label: 'SSH' }]}
        rules={{ required: 'Select a protocol' }}
      />
      <Button type="submit" variant="primary">Save</Button>
    </form>
  )
}

All RHF wrappers automatically display validation errors from fieldState.error.

Contributing

Development Setup

git clone https://github.com/annondeveloper/ui-kit.git
cd ui-kit
npm install
npm run storybook     # Component explorer at localhost:6006
npm run test:watch    # Vitest in watch mode
npm run typecheck     # TypeScript check

Running Tests

npm test              # Run all tests once
npm run test:watch    # Watch mode

Tests use Vitest + Testing Library + jest-axe for accessibility.

Adding a Component

Create src/components/my-component.tsx with the 'use client' directive
Export from src/index.ts
Add to src/cli/registry.ts for CLI support
Add a Storybook story in src/components/my-component.stories.tsx
Add tests in src/__tests__/my-component.test.tsx
Run npm run typecheck && npm test to verify

Conventions

All colors use hsl(var(--token)) syntax -- never hardcoded hex values
All animations respect useReducedMotion() from Framer Motion
Components use 'use client' directive for React Server Component compatibility
Types are exported alongside components for consumer use

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 353 Commits
.github		.github
.storybook		.storybook
demo		demo
docs		docs
figma-plugin		figma-plugin
scripts		scripts
src		src
.gitignore		.gitignore
.npmrc		.npmrc
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
changes.md		changes.md
jsr.json		jsr.json
mcp_readme.md		mcp_readme.md
package-lock.json		package-lock.json
package.json		package.json
playwright.config.ts		playwright.config.ts
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
tsup.cli.config.ts		tsup.cli.config.ts
tsup.config.ts		tsup.config.ts
tsup.mcp.config.ts		tsup.mcp.config.ts
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

@annondeveloper/ui-kit v2

Quick Start

Features

Documentation

New in v2.5

Next-Gen Features

CLI Commands

Component List

General-Purpose Components (73)

Domain-Specific Components (74)

New in v2.5 (1 component)

New in v2.4 (30 components)

Core Engine Modules

Entry Points

Weight Tiers

Bundle Size

Motion Levels

v1 Documentation

Quick Start

Install

Peer Dependencies

Theme Setup

Minimal Example

Why This Library?

Component Reference

Core

Button

Badge

Badge Factory

Card

Tabs

Sheet

Tooltip

Popover

DropdownMenu

ConfirmDialog

Forms

FormInput

Select

Checkbox

ToggleSwitch

RadioGroup

Slider

ColorInput

StepWizard

FilterPill

Data Display

DataTable

SmartTable

AnimatedCounter

Sparkline

TruncatedText

CopyBlock

DiffViewer

Status & Monitoring

StatusBadge

StatusPulse

MetricCard

ThresholdGauge

UtilizationBar

UptimeTracker

PortStatusGrid

PipelineStage

SeverityTimeline

TimeRangeSelector

LogViewer

Real-Time & AI

RealtimeValue

StreamingText

TypingIndicator

ConfidenceBar

CommandBar

LiveFeed

NotificationStack

Layout & Feedback

EmptyState

Packages