@annondeveloper/ui-kit v2

The first React component library built for AI agents. 147 zero-dependency components that AI assistants can discover, understand, and use via MCP.

How It Works

Step 1. Install the library

npm install @annondeveloper/ui-kit

Step 2. Connect your AI assistant (pick one)

# Zero setup — hosted MCP (works instantly, no install needed)
# Add to your MCP config: { "url": "https://ui-kit-mcp.annondeveloper.workers.dev/sse" }

# Or run locally
npx @annondeveloper/ui-kit mcp

Step 3. Ask your AI to build

"Build a dashboard with MetricCard, DataTable, and TimeSeriesChart using ui-kit"

Your AI generates production code directly:

import { UIProvider, MetricCard, DataTable, TimeSeriesChart } from '@annondeveloper/ui-kit'

function Dashboard({ metrics, tableData, series }) {
  return (
    <UIProvider>
      <div style={{ display: 'grid', gridTemplateColumns: 'repeat(3, 1fr)', gap: '1rem' }}>
        <MetricCard title="Requests" value="12.4K" trend="up" />
        <MetricCard title="Latency" value="42ms" trend="down" />
        <MetricCard title="Error Rate" value="0.12%" trend="down" />
      </div>
      <TimeSeriesChart series={series} height={300} />
      <DataTable columns={columns} data={tableData} searchPlaceholder="Search..." />
    </UIProvider>
  )
}

MCP Server

The built-in MCP server exposes 6 tools that give AI assistants structured access to the full component library:

| Tool | What it does | |------|-------------| | list_components | Browse all 147 components with descriptions, filterable by category or tier | | get_component | Get full API reference for any component — props, types, defaults, code examples | | search_components | Semantic search across components by use case (e.g., "data visualization", "form inputs") | | get_theme | Retrieve theme tokens, OKLCH color system details, and customization API | | generate_snippet | Generate working TSX code with correct imports for any component combination | | get_icons | Browse 50+ built-in SVG icons with search and usage examples |

Hosted (zero setup — just add the URL)

No install needed. Connect any MCP client to the hosted server:

{
  "mcpServers": {
    "ui-kit": {
      "url": "https://ui-kit-mcp.annondeveloper.workers.dev/sse"
    }
  }
}

Local (for offline use)

npx @annondeveloper/ui-kit mcp

Or add to your MCP config (claude_desktop_config.json, .cursor/mcp.json):

{
  "mcpServers": {
    "ui-kit": {
      "command": "npx",
      "args": ["@annondeveloper/ui-kit", "mcp"]
    }
  }
}

Try it

Ask your AI assistant:

• "Build a dashboard with MetricCard, DataTable, and TimeSeriesChart using ui-kit"
• "Create a multi-step form wizard with validation"
• "Add a real-time log viewer with severity filtering"

AI Integrations

Works with every major AI coding assistant. One URL, zero install:

| Assistant | Setup | Guide | |-----------|-------|-------| | Claude Code | Full plugin with 5 skills + 2 agents + hooks | plugins/claude-code | | Claude Desktop | Add MCP URL to claude_desktop_config.json | See MCP section above | | Cursor | Copy .cursor/mcp.json into your project | plugins/cursor | | VS Code / Copilot | Add to .vscode/mcp.json | plugins/vscode | | Windsurf | Add to MCP settings | plugins/windsurf | | Codex CLI | Add to ~/.codex/config.json | plugins/codex |

Claude Code plugin features:

• /ui-kit:component-finder — search 147 components by name or use case
• /ui-kit:generate-component — produce working TSX with correct imports
• /ui-kit:design-system — learn Aurora Fluid, OKLCH, motion levels
• /ui-kit:tier-guide — choose the right weight tier
• /ui-kit:audit-accessibility — check WCAG AA compliance
• component-architect agent — designs multi-component layouts
• accessibility-reviewer agent — deep a11y audit

Quick Start

For manual usage without an AI assistant:

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 (14) — optimize your bundle
• AI-native — Claude Code plugin, Cursor/VS Code/Windsurf/Codex integrations, hosted MCP server
• MCP server — 6 tools for component discovery, API reference, code generation, theme tokens
• 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
• 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.7

• AI DataTable -- AI-powered filter suggestions for DataTable
• RSC Support -- React Server Components compatibility
• Web Components -- Web Components wrapper for framework-agnostic usage
• MCP Server -- Model Context Protocol server for AI-assisted workflows

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
• Cursor MCP Setup -- Connect the MCP server to Cursor
• Figma Plugin -- Token sync between code and Figma Variables
• Performance Dashboard -- Bundle tracking, render profiler, Web Vitals

Next-Gen Features

AI DataTable Suggestions -- DataTable with AI-powered filter suggestions that analyze column data to surface outliers, patterns, and top-N values automatically.

RSC Support -- Full React Server Components compatibility. Components work in both client and server rendering contexts without extra configuration.

Web Components Wrapper -- Use ui-kit components in any framework (Vue, Svelte, vanilla JS) via custom elements. Import the wrapper and register components as <ui-button>, <ui-card>, etc.

MCP Server -- Built-in Model Context Protocol server that exposes component discovery, API reference, code generation, and theme tools to AI assistants.

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
npx @annondeveloper/ui-kit mcp                                     # Start MCP server for AI assistants

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 | 14 | Aurora glow, spring animations, shimmer effects |

Bundle Size

| Metric | Value | |--------|-------| | Total (gzipped) | ~384 KB | | Budget | 400 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

v2 has zero external dependencies -- only react ^19 and react-dom ^19 are required as peer dependencies.

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, ToastProvider, useToast } from '@annondeveloper/ui-kit'

function App() {
  return (
    <ToastProvider>
      <MetricCard label="CPU Usage" value={72.4} format={n => `${n.toFixed(1)}%`} status="warning" />
      <StatusBadge status="active" pulse />
      <DeployButton />
    </ToastProvider>
  )
}

function DeployButton() {
  const toast = useToast()
  return <Button variant="primary" onClick={() => toast.success('Deployed!')}>Deploy</Button>
}

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 semantic structure via children.

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

<Card variant="interactive" padding="lg">
  <h2>Server Health</h2>
  <p>All systems operational</p>
</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 |

Supports ref forwarding and all native HTML attributes.

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 |

Supports ref forwarding and all native input attributes.

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

Shimmer loading placeholder.

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

<Skeleton width={128} height={32} />
<Skeleton width="100%" height={16} />
<Skeleton variant="circle" width={40} height={40} />

| Prop | Type | Default | Description | |------|------|---------|-------------| | width | string \| number | '100%' | Skeleton width | | height | string \| number | '1em' | Skeleton height | | variant | 'rect' \| 'circle' | 'rect' | Shape variant |

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 } from '@annondeveloper/ui-kit'

<SortableList
  items={[
    { id: '1', content: <span>Rule 1</span> },
    { id: '2', content: <span>Rule 2</span> },
  ]}
  onChange={setRules}
/>

| Prop | Type | Default | Description | |------|------|---------|-------------| | items | SortableItem[] | -- | { id: string, content: ReactNode } | | onChange | (items: SortableItem[]) => void | -- | Reorder callback | | handle | boolean | -- | Show drag handle | | orientation | '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 |

ToastProvider / useToast

Toast notification system using ToastProvider and the useToast hook.

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

function App() {
  return (
    <ToastProvider position="bottom-right">
      <Content />
    </ToastProvider>
  )
}

function Content() {
  const toast = useToast()
  return (
    <>
      <Button onClick={() => toast.success('Deployment complete')}>Deploy</Button>
      <Button onClick={() => toast.error('Connection failed')}>Test Error</Button>
    </>
  )
}

| Prop | Type | Default | Description | |------|------|---------|-------------| | position | 'top-right' \| 'top-left' \| 'bottom-right' \| 'bottom-left' | '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 GB/s" | | fmtBytes(n) | fmtBytes(1_073_741_824) | "1.0 GB" | | fmtPct(n, d?) | fmtPct(95.6) | "95.6%" | | fmtUptime(ratio) | fmtUptime(0.999) | "99.90%" | | fmtRelative(timestamp) | fmtRelative(Date.now() - 3600000) | "1 hour ago" | | fmtCompact(n) | fmtCompact(480_933_305) | "480.9M" | | fmtDuration(secs) | fmtDuration(0.003) | "3ms" | | stripCidr(ip) | stripCidr('10.0.0.1/32') | "10.0.0.1" | | clamp(v, min, max) | clamp(150, 0, 100) | 100 |

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