ui-kit

147 zero-dependency React components with Aurora Fluid design. 5 skills for component discovery, code generation, design system reference, t

Open source Open in the app JSON README (API)

About

147 zero-dependency React components with Aurora Fluid design. 5 skills for component discovery, code generation, design system reference, tier selection, and accessibility auditing. 2 agents for architecture and a11y review. Auto-connects to hosted MCP server.

Details

Kind

Plugins

Topic

Developer tools

Publisher

annondeveloper

Origin

marketplace

Category

ferramentas

Forks

2

Last push

2026-06-07T03:18:38Z

Repository state

ativo

Language

TypeScript

License

MIT

Added

2026-08-30 01:48:58

Updated

2026-08-30 01:48:58

Origin id

annondeveloper/ui-kit/ui-kit

README

[![Made for AI Assistants](https://img.shields.io/badge/Made_for-AI_Assistants-blueviolet?style=flat-square&logo=anthropic&logoColor=white)](https://modelcontextprotocol.io)
[![npm version](https://img.shields.io/npm/v/@annondeveloper/ui-kit)](https://www.npmjs.com/package/@annondeveloper/ui-kit)
[![bundle size](https://img.shields.io/bundlephobia/minzip/@annondeveloper/ui-kit)](https://bundlephobia.com/package/@annondeveloper/ui-kit)
[![license](https://img.shields.io/npm/l/@annondeveloper/ui-kit)](https://github.com/annondeveloper/ui-kit/blob/main/LICENSE)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue)](https://www.typescriptlang.org/)
[![JSR](https://jsr.io/badges/@annondeveloper/ui-kit)](https://jsr.io/@annondeveloper/ui-kit)

# @annondeveloper/ui-kit v2

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

## How It Works

**Step 1.** Install the library

```bash
npm install @annondeveloper/ui-kit
```

**Step 2.** Import CSS (required!)

```tsx
// Add to your root layout (app/layout.tsx, src/main.tsx, etc.)
import '@annondeveloper/ui-kit/css/theme.css'
import '@annondeveloper/ui-kit/css/all.css'
```

> **Without these imports, components render correct HTML but have no visual styling.**

**Step 3.** Connect your AI assistant (pick one)

```bash
# 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 4.** Ask your AI to build

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

Your AI generates production code directly:

```tsx
import '@annondeveloper/ui-kit/css/theme.css'
import '@annondeveloper/ui-kit/css/all.css'
import {
  UIProvider, PageShell, PageHeader, StatsGrid, MetricCard,
  SectionHeader, CardGrid, Card, Toolbar, SearchInput, Button
} from '@annondeveloper/ui-kit'

function Dashboard() {
  return (
    <UIProvider>
      <PageShell padding="lg" maxWidth="xl">
        <PageHeader title="Dashboard" description="System overview" />
        <StatsGrid columns={3}>
          <MetricCard label="Requests" value="12.4K" trend={12} status="ok" />
          <MetricCard label="Latency" value="42ms" trend={-5} status="ok" />
          <MetricCard label="Errors" value="0.12%" status="critical" />
        </StatsGrid>
        <Toolbar justify="between">
          <SearchInput placeholder="Search..." />
          <Button variant="primary">Export</Button>
        </Toolbar>
        <SectionHeader title="Services" action={<Button variant="ghost" size="sm">View All</Button>} />
        <CardGrid columns={3}>
          <Card padding="md"><h3>API Gateway</h3><p>Healthy</p></Card>
          <Card padding="md"><h3>Database</h3><p>Healthy</p></Card>
          <Card padding="md"><h3>Cache</h3><p>Warning</p></Card>
        </CardGrid>
      </PageShell>
    </UIProvider>
  )
}
```

## MCP Server

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

| Tool | What it does |
|------|-------------|
| `list_components` | Browse all 159 components with descriptions, filterable by category or tier |
| `get_component` | Get full API reference for any component — props, types, defaults, code examples, design guide |
| `search_components` | Semantic search across components by use case (e.g., "data visualization", "form inputs") |
| `generate_snippet` | Generate working TSX code with correct imports for any component combination |
| `get_theme` | Retrieve theme tokens, OKLCH color system details, and customization API |
| `get_icons` | Browse 50+ built-in SVG icons with search and usage examples |
| `get_started` | Complete setup guide for new projects — framework-aware (Next.js, Vite, Remix) |
| `get_page_template` | Full page scaffolds: dashboard, settings, list, detail, empty, auth, landing |

### Hosted (zero setup — just add the URL)

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

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

### Local (for offline use)

```bash
npx @annondeveloper/ui-kit mcp
```

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

```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](plugins/claude-code/README.md) |
| **Claude Desktop** | Add MCP URL to `claude_desktop_config.json` | See MCP section above |
| **Cursor** | Copy `.cursor/mcp.json` into your project | [plugins/cursor](plugins/cursor/README.md) |
| **VS Code / Copilot** | Add to `.vscode/mcp.json` | [plugins/vscode](plugins/vscode/README.md) |
| **Windsurf** | Add to MCP settings | [plugins/windsurf](plugins/windsurf/README.md) |
| **Codex CLI** | Add to `~/.codex/config.json` | [plugins/codex](plugins/codex/README.md) |

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

```bash
npm install @annondeveloper/ui-kit
```

```tsx
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](docs/migration-v2.md) -- Upgrading from v1 to v2
- [Theming](docs/theming.md) -- OKLCH colors, theme generation, customization
- [Form Engine](docs/forms.md) -- Built-in form state, validators, auto-wiring
- [Animation](docs/animation.md) -- Physics springs, timeline, stagger, scroll
- [Design Spec](docs/superpowers/specs/2026-03-20-ui-kit-v2-design.md) -- Full architecture document

### New in v2.7

- [AI DataTable](docs/ai-datatable.md) -- AI-powered filter suggestions for DataTable
- [RSC Support](docs/rsc.md) -- React Server Components compatibility
- [Web Components](docs/web-components.md) -- Web Components wrapper for framework-agnostic usage
- [MCP Server](docs/mcp-server.md) -- Model Context Protocol server for AI-assisted workflows

### New in v2.5

- [Motion Choreography](docs/choreography.md) -- Sequenced multi-step animations with 5 presets
- [Container Queries](docs/container-queries.md) -- Container-responsive design tokens and components
- [View Transitions](docs/view-transitions.md) -- Native View Transitions API with 6 presets
- [Theme Editor](docs/theme-editor.md) -- Color harmony, contrast audit, multi-format export
- [AI Generator](docs/ai-generator.md) -- Template gallery, custom composition, 5 framework output
- [CLI Scaffolding](docs/cli-scaffolding.md) -- Project templates, component add, Figma export
- [Cursor MCP Setup](docs/guides/cursor-mcp-setup.md) -- Connect the MCP server to Cursor
- [Figma Plugin](docs/figma-plugin.md) -- Token sync between code and Figma Variables
- [Performance Dashboard](docs/performance-dashboard.md) -- 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

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

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

```tsx
<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 &bull; Dark/Light theme &bull; Accessible &bull; AI-ready &bull; Real-time primitives &bull; Tree-shakeable

[![npm](https://img.shields.io/npm/v/@annondeveloper/ui-kit)](https://www.npmjs.com/package/@annondeveloper/ui-kit)
&nbsp;
[GitHub](https://github.com/annondeveloper/ui-kit)
&nbsp;&bull;&nbsp;
[JSR](https://jsr.io/@annondeveloper/ui-kit)
&nbsp;&bull;&nbsp;
[Demo](https://annondeveloper.github.io/ui-kit)

---

## Quick Start

### Install

```bash
# 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

```bash
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:

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

Or copy the CSS custom properties into your own stylesheet. See [Theme System](#theme-system) below.

### Minimal Example

```tsx
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.

```tsx
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.

```tsx
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:

```tsx
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.

```tsx
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.

```tsx
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.

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

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

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

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

---

#### Tooltip

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

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

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

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

---

#### Popover

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

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

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

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

---

#### DropdownMenu

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

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

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

More

• More plugins on Developer tools
• Everything published by annondeveloper
• Browse the whole catalog