Which integrations are available for this server?

Enables bidirectional sync of design tokens between code and Figma, allowing export of theme tokens (colors, typography, spacing) as Figma Variables and import via the Aurora UI Kit Token Sync plugin to maintain consistency between design and development.

Made for AI Assistants npm version bundle size license TypeScript JSR

@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

npm 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.

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 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

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	`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 Engine

The built-in form engine requires no external dependencies. Import from the dedicated entry point:

import { createForm, useForm, Form, v } from '@annondeveloper/ui-kit/form'

Example with Validation

import { createForm, useForm, Form } from '@annondeveloper/ui-kit/form'
import { Button } from '@annondeveloper/ui-kit'

const credentialForm = createForm({
  hostname: { initial: '', validator: v.required('Hostname is required') },
  protocol: { initial: '', validator: v.required('Select a protocol') },
})

function CredentialForm() {
  const form = useForm(credentialForm)

  return (
    <Form form={form} onSubmit={(values) => console.log(values)}>
      <input name="hostname" placeholder="10.0.0.1" />
      <select name="protocol">
        <option value="snmp">SNMP</option>
        <option value="ssh">SSH</option>
      </select>
      <Button type="submit" variant="primary">Save</Button>
    </Form>
  )
}

The form engine includes createForm, useForm, Form, FieldArray, and validators (v).

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