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

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:

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)

Domain-Specific Components (74)

New in v2.5 (1 component)

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

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

Bundle Size

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>

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>

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>

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

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>

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>

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>

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' },
  ]}
/>

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

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

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

Checkbox

Themed checkbox with indeterminate state support. Forwards ref.

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

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

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

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

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

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']} />

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

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')} />

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.' }}
/>

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

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()} />

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

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

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

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

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

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

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]}
/>

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

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

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)}
/>

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)}
/>

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)}
/>

SeverityTimeline

Horizontal scrollable event timeline with severity-colored dots.

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

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

TimeRangeSelector

Compact horizontal pill-group time range selector.

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

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

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

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

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()} />

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

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

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)}
/>

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..."
/>

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

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

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

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..." />

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 */}

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

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

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

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

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>
    </>
  )
}

SuccessCheckmark

Animated SVG checkmark with circle and path draw animations.

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

<SuccessCheckmark size={24} />

Utilities

Class Merging

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

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

Formatters

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

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

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

1. Create src/components/my-component.tsx with the 'use client' directive
2. Export from src/index.ts
3. Add to src/cli/registry.ts for CLI support
4. Add a Storybook story in src/components/my-component.stories.tsx
5. Add tests in src/__tests__/my-component.test.tsx
6. 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