{
  "markdown": "[![Made for AI Assistants](https://img.shields.io/badge/Made_for-AI_Assistants-blueviolet?style=flat-square&logo=anthropic&logoColor=white)](https://modelcontextprotocol.io)\n[![npm version](https://img.shields.io/npm/v/@annondeveloper/ui-kit)](https://www.npmjs.com/package/@annondeveloper/ui-kit)\n[![bundle size](https://img.shields.io/bundlephobia/minzip/@annondeveloper/ui-kit)](https://bundlephobia.com/package/@annondeveloper/ui-kit)\n[![license](https://img.shields.io/npm/l/@annondeveloper/ui-kit)](https://github.com/annondeveloper/ui-kit/blob/main/LICENSE)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue)](https://www.typescriptlang.org/)\n[![JSR](https://jsr.io/badges/@annondeveloper/ui-kit)](https://jsr.io/@annondeveloper/ui-kit)\n\n# @annondeveloper/ui-kit v2\n\n> The first React component library built for AI agents. 159 zero-dependency components that AI assistants can discover, understand, and use via MCP.\n\n## How It Works\n\n**Step 1.** Install the library\n\n```bash\nnpm install @annondeveloper/ui-kit\n```\n\n**Step 2.** Import CSS (required!)\n\n```tsx\n// Add to your root layout (app/layout.tsx, src/main.tsx, etc.)\nimport '@annondeveloper/ui-kit/css/theme.css'\nimport '@annondeveloper/ui-kit/css/all.css'\n```\n\n> **Without these imports, components render correct HTML but have no visual styling.**\n\n**Step 3.** Connect your AI assistant (pick one)\n\n```bash\n# Zero setup — hosted MCP (works instantly, no install needed)\n# Add to your MCP config: { \"url\": \"https://ui-kit-mcp.annondeveloper.workers.dev/sse\" }\n\n# Or run locally\nnpx @annondeveloper/ui-kit mcp\n```\n\n**Step 4.** Ask your AI to build\n\n> \"Build a dashboard with MetricCard, DataTable, and TimeSeriesChart using ui-kit\"\n\nYour AI generates production code directly:\n\n```tsx\nimport '@annondeveloper/ui-kit/css/theme.css'\nimport '@annondeveloper/ui-kit/css/all.css'\nimport {\n  UIProvider, PageShell, PageHeader, StatsGrid, MetricCard,\n  SectionHeader, CardGrid, Card, Toolbar, SearchInput, Button\n} from '@annondeveloper/ui-kit'\n\nfunction Dashboard() {\n  return (\n    <UIProvider>\n      <PageShell padding=\"lg\" maxWidth=\"xl\">\n        <PageHeader title=\"Dashboard\" description=\"System overview\" />\n        <StatsGrid columns={3}>\n          <MetricCard label=\"Requests\" value=\"12.4K\" trend={12} status=\"ok\" />\n          <MetricCard label=\"Latency\" value=\"42ms\" trend={-5} status=\"ok\" />\n          <MetricCard label=\"Errors\" value=\"0.12%\" status=\"critical\" />\n        </StatsGrid>\n        <Toolbar justify=\"between\">\n          <SearchInput placeholder=\"Search...\" />\n          <Button variant=\"primary\">Export</Button>\n        </Toolbar>\n        <SectionHeader title=\"Services\" action={<Button variant=\"ghost\" size=\"sm\">View All</Button>} />\n        <CardGrid columns={3}>\n          <Card padding=\"md\"><h3>API Gateway</h3><p>Healthy</p></Card>\n          <Card padding=\"md\"><h3>Database</h3><p>Healthy</p></Card>\n          <Card padding=\"md\"><h3>Cache</h3><p>Warning</p></Card>\n        </CardGrid>\n      </PageShell>\n    </UIProvider>\n  )\n}\n```\n\n## MCP Server\n\nThe built-in MCP server exposes 8 tools that give AI assistants structured access to the full component library:\n\n| Tool | What it does |\n|------|-------------|\n| `list_components` | Browse all 159 components with descriptions, filterable by category or tier |\n| `get_component` | Get full API reference for any component — props, types, defaults, code examples, design guide |\n| `search_components` | Semantic search across components by use case (e.g., \"data visualization\", \"form inputs\") |\n| `generate_snippet` | Generate working TSX code with correct imports for any component combination |\n| `get_theme` | Retrieve theme tokens, OKLCH color system details, and customization API |\n| `get_icons` | Browse 50+ built-in SVG icons with search and usage examples |\n| `get_started` | Complete setup guide for new projects — framework-aware (Next.js, Vite, Remix) |\n| `get_page_template` | Full page scaffolds: dashboard, settings, list, detail, empty, auth, landing |\n\n### Hosted (zero setup — just add the URL)\n\nNo install needed. Connect any MCP client to the hosted server:\n\n```json\n{\n  \"mcpServers\": {\n    \"ui-kit\": {\n      \"url\": \"https://ui-kit-mcp.annondeveloper.workers.dev/sse\"\n    }\n  }\n}\n```\n\n### Local (for offline use)\n\n```bash\nnpx @annondeveloper/ui-kit mcp\n```\n\nOr add to your MCP config (`claude_desktop_config.json`, `.cursor/mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"ui-kit\": {\n      \"command\": \"npx\",\n      \"args\": [\"@annondeveloper/ui-kit\", \"mcp\"]\n    }\n  }\n}\n```\n\n### Try it\n\nAsk your AI assistant:\n- \"Build a dashboard with MetricCard, DataTable, and TimeSeriesChart using ui-kit\"\n- \"Create a multi-step form wizard with validation\"\n- \"Add a real-time log viewer with severity filtering\"\n\n## AI Integrations\n\nWorks with every major AI coding assistant. One URL, zero install:\n\n| Assistant | Setup | Guide |\n|-----------|-------|-------|\n| **Claude Code** | Full plugin with 5 skills + 2 agents + hooks | [plugins/claude-code](plugins/claude-code/README.md) |\n| **Claude Desktop** | Add MCP URL to `claude_desktop_config.json` | See MCP section above |\n| **Cursor** | Copy `.cursor/mcp.json` into your project | [plugins/cursor](plugins/cursor/README.md) |\n| **VS Code / Copilot** | Add to `.vscode/mcp.json` | [plugins/vscode](plugins/vscode/README.md) |\n| **Windsurf** | Add to MCP settings | [plugins/windsurf](plugins/windsurf/README.md) |\n| **Codex CLI** | Add to `~/.codex/config.json` | [plugins/codex](plugins/codex/README.md) |\n\n**Claude Code plugin features:**\n- `/ui-kit:component-finder` — search 147 components by name or use case\n- `/ui-kit:generate-component` — produce working TSX with correct imports\n- `/ui-kit:design-system` — learn Aurora Fluid, OKLCH, motion levels\n- `/ui-kit:tier-guide` — choose the right weight tier\n- `/ui-kit:audit-accessibility` — check WCAG AA compliance\n- `component-architect` agent — designs multi-component layouts\n- `accessibility-reviewer` agent — deep a11y audit\n\n## Quick Start\n\nFor manual usage without an AI assistant:\n\n```bash\nnpm install @annondeveloper/ui-kit\n```\n\n```tsx\nimport { UIProvider, Button, Card, MetricCard } from '@annondeveloper/ui-kit'\n\nfunction App() {\n  return (\n    <UIProvider>\n      <Card>\n        <Button variant=\"primary\">Deploy</Button>\n        <MetricCard title=\"CPU\" value=\"87.4%\" trend=\"up\" />\n      </Card>\n    </UIProvider>\n  )\n}\n```\n\n## Features\n\n- **Zero dependencies** — only `react` and `react-dom` peer deps\n- **147 components** — 73 general-purpose + 74 domain-specific across 3 weight tiers\n- **3 weight tiers** — Lite (144), Standard (147), Premium (14) — optimize your bundle\n- **AI-native** — Claude Code plugin, Cursor/VS Code/Windsurf/Codex integrations, hosted MCP server\n- **MCP server** — 6 tools for component discovery, API reference, code generation, theme tokens\n- **Aurora Fluid design** — deep atmospheric surfaces, ambient glows, OKLCH colors\n- **Physics animations** — real spring solver, configurable motion levels (0-3)\n- **Built-in form engine** — `createForm`, `useForm`, validators, zero external deps\n- **15 pre-built themes** — including 5 new themes added in v2.4\n- **`classNames` prop** — deep customization of internal component elements\n- **Accessibility** — WAI-ARIA patterns, keyboard navigation, screen reader support\n- **Responsive** — container queries, fluid typography, touch/mouse/gamepad support\n- **Theme generator** — generate complete theme from single brand color\n\n## Documentation\n\n- [Migration Guide](docs/migration-v2.md) -- Upgrading from v1 to v2\n- [Theming](docs/theming.md) -- OKLCH colors, theme generation, customization\n- [Form Engine](docs/forms.md) -- Built-in form state, validators, auto-wiring\n- [Animation](docs/animation.md) -- Physics springs, timeline, stagger, scroll\n- [Design Spec](docs/superpowers/specs/2026-03-20-ui-kit-v2-design.md) -- Full architecture document\n\n### New in v2.7\n\n- [AI DataTable](docs/ai-datatable.md) -- AI-powered filter suggestions for DataTable\n- [RSC Support](docs/rsc.md) -- React Server Components compatibility\n- [Web Components](docs/web-components.md) -- Web Components wrapper for framework-agnostic usage\n- [MCP Server](docs/mcp-server.md) -- Model Context Protocol server for AI-assisted workflows\n\n### New in v2.5\n\n- [Motion Choreography](docs/choreography.md) -- Sequenced multi-step animations with 5 presets\n- [Container Queries](docs/container-queries.md) -- Container-responsive design tokens and components\n- [View Transitions](docs/view-transitions.md) -- Native View Transitions API with 6 presets\n- [Theme Editor](docs/theme-editor.md) -- Color harmony, contrast audit, multi-format export\n- [AI Generator](docs/ai-generator.md) -- Template gallery, custom composition, 5 framework output\n- [CLI Scaffolding](docs/cli-scaffolding.md) -- Project templates, component add, Figma export\n- [Cursor MCP Setup](docs/guides/cursor-mcp-setup.md) -- Connect the MCP server to Cursor\n- [Figma Plugin](docs/figma-plugin.md) -- Token sync between code and Figma Variables\n- [Performance Dashboard](docs/performance-dashboard.md) -- Bundle tracking, render profiler, Web Vitals\n\n## Next-Gen Features\n\n**AI DataTable Suggestions** -- DataTable with AI-powered filter suggestions that analyze column data to surface outliers, patterns, and top-N values automatically.\n\n**RSC Support** -- Full React Server Components compatibility. Components work in both client and server rendering contexts without extra configuration.\n\n**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.\n\n**MCP Server** -- Built-in Model Context Protocol server that exposes component discovery, API reference, code generation, and theme tools to AI assistants.\n\n**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`.\n\n**Container Query Design Tokens** -- `<ContainerQuery>` component, `useContainerSize()` hook, `resolveResponsive()` utility, and `CONTAINER_BREAKPOINTS` for building components that adapt to their container.\n\n**View Transitions API** -- `useViewTransition()` hook with 6 presets (morph, crossfade, slide-left, slide-right, slide-up, zoom) and `assignTransitionName()` for element morphing.\n\n**Theme Editor** -- Color harmony engine (5 types), WCAG contrast audit, export to CSS/Tailwind/Figma/CSS-in-JS, and shareable URL scheme.\n\n**AI Component Generator** -- Template gallery (dashboard, form, marketing, saas, docs), custom composition builder, and code output for React, Vue, Svelte, and HTML.\n\n**CLI Scaffolding** -- `add` copies components, `create` scaffolds full projects from 5 templates, `figma-export` generates Figma Variables JSON.\n\n**Figma Plugin** -- Export theme tokens as Figma Variables and import them via the Aurora UI Kit Token Sync plugin.\n\n**Performance Dashboard** -- Bundle size tracking with budget gauge, runtime render profiler, Web Vitals integration, and CI regression detection.\n\n## CLI Commands\n\n```bash\nnpx @annondeveloper/ui-kit init                                    # Copy theme + setup\nnpx @annondeveloper/ui-kit add <component> [--tier] [--out-dir]    # Copy component source\nnpx @annondeveloper/ui-kit create <name> --template <template>     # Scaffold project\nnpx @annondeveloper/ui-kit list                                    # List all 147 components\nnpx @annondeveloper/ui-kit theme <color>                           # Generate theme CSS\nnpx @annondeveloper/ui-kit figma-export --theme <name> --output <file>  # Export Figma tokens\nnpx @annondeveloper/ui-kit mcp                                     # Start MCP server for AI assistants\n```\n\n## Component List\n\n### General-Purpose Components (73)\n\n| Component | Description |\n|-----------|-------------|\n| `ActionIcon` | Icon-only button with tooltip |\n| `Accordion` | Collapsible sections with single/multiple mode |\n| `Affix` | Fixed-position wrapper for floating elements |\n| `Alert` | Inline status messages with variants |\n| `AnimatedCounter` | Smooth number animation with easing |\n| `AppShell` | Full application layout scaffold |\n| `Avatar` | Image/initials avatar with status dot |\n| `AvatarUpload` | Avatar with upload/crop functionality |\n| `BackToTop` | Scroll-to-top floating button |\n| `Badge` | Pill-shaped label with color presets |\n| `Breadcrumbs` | Hierarchical navigation trail |\n| `Button` | Primary action with variants and loading |\n| `ButtonGroup` | Grouped button container |\n| `Calendar` | Standalone calendar display |\n| `Card` | Styled container with subcomponents |\n| `Carousel` | Image/content carousel with navigation |\n| `Checkbox` | Themed checkbox with indeterminate state |\n| `Chip` | Compact interactive tag element |\n| `ColorInput` | Color picker with hue/saturation panel |\n| `Combobox` | Searchable select with async loading |\n| `CommandBar` | Universal command palette (Cmd+K) |\n| `ConfirmDialog` | Confirmation modal with danger variant |\n| `CopyButton` | One-click copy to clipboard |\n| `DatePicker` | Calendar-based date selection |\n| `DateRangePicker` | Date range selection with presets |\n| `Dialog` | Native dialog with animated entry/exit |\n| `Divider` | Horizontal/vertical separator |\n| `Drawer` | Slide-out panel from any edge |\n| `DropdownMenu` | Action menu with submenus and shortcuts |\n| `EmptyState` | Decorative placeholder with icon and actions |\n| `FileUpload` | Drag-and-drop file upload with preview |\n| `FilterPill` | Rounded filter toggle with count |\n| `FormInput` | Themed input with label and validation |\n| `Highlight` | Text highlighting with search match |\n| `Indicator` | Dot/badge indicator overlay |\n| `InlineEdit` | Click-to-edit text field |\n| `Kbd` | Keyboard shortcut display |\n| `Link` | Styled anchor with underline animation |\n| `MultiSelect` | Multi-value select dropdown |\n| `Navbar` | Top-level application navigation bar |\n| `NativeTooltip` | Lightweight tooltip using title attribute |\n| `NotificationStack` | Toast notification cards with auto-dismiss |\n| `NumberInput` | Numeric input with increment/decrement |\n| `OtpInput` | One-time password code entry |\n| `Pagination` | Page navigation with controls |\n| `PasswordInput` | Password field with visibility toggle |\n| `PinInput` | PIN code entry with auto-advance |\n| `Popover` | Anchored popover with arrow and focus management |\n| `Progress` | Progress bar with indeterminate mode |\n| `RadioGroup` | Radio button group with descriptions |\n| `Rating` | Star rating input with half-star support |\n| `ScrollReveal` | Scroll-triggered reveal animation |\n| `SearchInput` | Search field with debounce and clear |\n| `SegmentedControl` | Segmented toggle selector |\n| `Select` | Themed dropdown select |\n| `Sheet` | Slide-over drawer with swipe dismiss |\n| `Sidebar` | Collapsible side navigation |\n| `Skeleton` | Shimmer loading placeholder |\n| `Slider` | Range slider with keyboard support |\n| `Spoiler` | Collapsible content with show more/less |\n| `Spotlight` | Spotlight search overlay |\n| `StatusBadge` | Status indicator with colored dot |\n| `StatusPulse` | Animated status dot with pulse ring |\n| `Stepper` | Step indicator with progress |\n| `SuccessCheckmark` | Animated SVG checkmark |\n| `Tabs` | Tabbed interface with animated indicator |\n| `TagInput` | Multi-value input with tag chips |\n| `Textarea` | Auto-growing text area |\n| `Toast` | Pre-themed toast notifications |\n| `ToggleSwitch` | Boolean toggle switch |\n| `Tooltip` | Popover-based tooltip with positioning |\n| `Typography` | Semantic text with fluid sizing |\n| `UIProvider` | Theme, motion, and density provider |\n\n### Domain-Specific Components (74)\n\n| Component | Description |\n|-----------|-------------|\n| `BackgroundBeams` | Animated sweeping light beams |\n| `BackgroundBoxes` | Floating animated grid boxes |\n| `BorderBeam` | Animated conic-gradient border |\n| `Card3D` | 3D perspective tilt with glare |\n| `CodeEditor` | Code editor with syntax highlighting |\n| `ConfidenceBar` | Probability bar with threshold zones |\n| `ConnectionTestPanel` | Step-by-step connectivity test UI |\n| `CopyBlock` | Code display with one-click copy |\n| `CoreChart` | CPU core utilization grid |\n| `Cropper` | Image cropping tool |\n| `CSVExportButton` | One-click CSV generation and download |\n| `ColumnVisibilityToggle` | Column show/hide dropdown |\n| `DashboardGrid` | Draggable dashboard layout |\n| `DataTable` | Full-featured data grid with search, sort, filter |\n| `DensitySelector` | Compact/comfortable/spacious control |\n| `DiffViewer` | Side-by-side/inline diff viewer |\n| `DiskMountBar` | Disk mount utilization bars |\n| `EncryptedText` | Matrix-style character scramble/reveal |\n| `EntityCard` | Infrastructure resource card |\n| `EvervaultCard` | Matrix-style encrypted card |\n| `FlipWords` | Rotating word animation |\n| `GeoMap` | SVG geographic visualization |\n| `GlowCard` | Mouse-tracking radial glow card |\n| `HeatmapCalendar` | GitHub-style contribution heatmap |\n| `HeroHighlight` | Gradient text highlight effect |\n| `InfiniteScroll` | Virtualized infinite-scroll list |\n| `JsonViewer` | Interactive JSON tree viewer |\n| `KanbanColumn` | Kanban board column with cards |\n| `LiveFeed` | Real-time event feed with auto-scroll |\n| `LogViewer` | Log stream viewer with severity colors |\n| `MeteorShower` | Falling meteor streak animation |\n| `MetricCard` | Dashboard stat tile with sparkline |\n| `NetworkTrafficCard` | Network throughput display |\n| `NumberTicker` | Rolling digit counter |\n| `OrbitingCircles` | Orbiting icon animation |\n| `PipelineStage` | Horizontal pipeline visualization |\n| `PortStatusGrid` | Network port status indicator grid |\n| `PropertyList` | Key-value detail panel |\n| `RackDiagram` | Data center rack visualization |\n| `RealtimeValue` | Live data display with freshness tracking |\n| `ResponsiveCard` | Container-query adaptive card |\n| `RichTextEditor` | WYSIWYG rich text editor |\n| `RingChart` | SVG donut chart with center label |\n| `Ripple` | Click ripple effect |\n| `SeverityTimeline` | Event timeline with severity dots |\n| `ServiceStrip` | Horizontal service badge strip |\n| `ShimmerButton` | Shimmering gradient button |\n| `SmartTable` | DataTable with auto-generated filter suggestions |\n| `SortableList` | Drag-and-drop reorderable list |\n| `Sparkline` | Inline SVG sparkline chart |\n| `SpotlightCard` | Spotlight hover effect card |\n| `StepWizard` | Multi-step form wizard |\n| `StorageBar` | Segmented horizontal bar |\n| `StreamingText` | AI/LLM streaming text with cursor |\n| `SwitchFaceplate` | Network switch port grid |\n| `TableOfContents` | Auto-generated page navigation |\n| `TextReveal` | Scroll-triggered character-by-character unveil |\n| `ThresholdGauge` | Semicircular gauge with threshold zones |\n| `TimePicker` | Time selection input |\n| `TimeRangeSelector` | Compact time range pill selector |\n| `Timeline` | Vertical event timeline |\n| `TimeSeriesChart` | Full SVG line chart with multi-series |\n| `Tour` | Guided product tour with step highlights |\n| `TracingBeam` | Scroll-tracing side beam |\n| `TransferList` | Dual-list item transfer |\n| `TreeView` | Hierarchical tree with expand/collapse |\n| `TruncatedText` | Auto-truncating text with tooltip |\n| `TypingIndicator` | \"Someone is typing\" animation |\n| `UpstreamDashboard` | Service monitoring layout |\n| `UptimeTracker` | Daily uptime bar strip |\n| `UtilizationBar` | Horizontal bar with threshold colors |\n| `ViewTransitionLink` | View Transitions API integration |\n| `WavyBackground` | Animated SVG sine waves |\n\n### New in v2.5 (1 component)\n\n| Component | Description |\n|-----------|-------------|\n| `ContainerQuery` | Container query wrapper with render-prop size info |\n\n### New in v2.4 (30 components)\n\nThe following components were added in the v2.4 release:\n\n**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\n\n**Domain-specific:** CodeEditor, Cropper, JsonViewer, RichTextEditor, Tour\n\n### Core Engine Modules\n\n| Module | Size | Description |\n|--------|------|-------------|\n| `core/styles` | ~1KB | useStyles(), css tag, adoptedStyleSheets, SSR |\n| `core/motion` | ~3.5KB | Spring solver, WAAPI, timeline, stagger, scroll, FLIP |\n| `core/input` | ~2.4KB | Unified pointer, gestures, focus, gamepad, multitouch |\n| `core/tokens` | ~1.5KB | OKLCH theme, generateTheme(), applyTheme() |\n| `core/a11y` | ~1KB | Focus trap, roving tabindex, live region, stable ID |\n| `core/icons` | ~2KB | 50+ built-in SVG icons, all overridable |\n| `core/forms` | ~2KB | createForm, useForm, validators, Form, FieldArray |\n| `core/utils` | ~0.5KB | cn(), formatting, sanitize, clamp |\n\n## Entry Points\n\n```typescript\nimport { Button, Dialog, DataTable } from '@annondeveloper/ui-kit'\nimport { Button as LiteButton } from '@annondeveloper/ui-kit/lite'\nimport { Button as PremiumButton } from '@annondeveloper/ui-kit/premium'\nimport { createForm, useForm, v } from '@annondeveloper/ui-kit/form'\nimport { generateTheme, themeToCSS } from '@annondeveloper/ui-kit/theme'\nimport '@annondeveloper/ui-kit/css/theme.css'  // Standalone CSS (optional)\n```\n\n## Weight Tiers\n\n| Tier | Components | Description |\n|------|-----------|-------------|\n| Standard | 147 | Full-featured with motion, theming, a11y |\n| Lite | 144 | Minimal wrappers, no motion (~0.3-1.2 KB each) |\n| Premium | 14 | Aurora glow, spring animations, shimmer effects |\n\n## Bundle Size\n\n| Metric | Value |\n|--------|-------|\n| Total (gzipped) | ~384 KB |\n| Budget | 400 KB |\n| Tree-shaking | Full ESM — import only what you use |\n\nTypical app importing ~20 components: **~15-25 KB gzipped** after tree-shaking.\n\n## Motion Levels\n\n```tsx\n<UIProvider motion={2}>  {/* 0=none, 1=subtle, 2=expressive, 3=cinematic */}\n```\n\n---\n\n## v1 Documentation\n\n> The React component library for monitoring dashboards, infrastructure tools, and professional applications.\n\n53 components &bull; Dark/Light theme &bull; Accessible &bull; AI-ready &bull; Real-time primitives &bull; Tree-shakeable\n\n[![npm](https://img.shields.io/npm/v/@annondeveloper/ui-kit)](https://www.npmjs.com/package/@annondeveloper/ui-kit)\n&nbsp;\n[GitHub](https://github.com/annondeveloper/ui-kit)\n&nbsp;&bull;&nbsp;\n[JSR](https://jsr.io/@annondeveloper/ui-kit)\n&nbsp;&bull;&nbsp;\n[Demo](https://annondeveloper.github.io/ui-kit)\n\n---\n\n## Quick Start\n\n### Install\n\n```bash\n# npm\nnpm install @annondeveloper/ui-kit\n\n# pnpm\npnpm add @annondeveloper/ui-kit\n\n# yarn\nyarn add @annondeveloper/ui-kit\n\n# bun\nbun add @annondeveloper/ui-kit\n\n# jsr\nnpx jsr add @annondeveloper/ui-kit\n```\n\n### Peer Dependencies\n\n```bash\nnpm install react react-dom\n```\n\nv2 has zero external dependencies -- only `react` ^19 and `react-dom` ^19 are required as peer dependencies.\n\n### Theme Setup\n\nImport the theme CSS once in your app's root layout:\n\n```tsx\nimport '@annondeveloper/ui-kit/theme.css'\n```\n\nOr copy the CSS custom properties into your own stylesheet. See [Theme System](#theme-system) below.\n\n### Minimal Example\n\n```tsx\nimport { Button, MetricCard, StatusBadge, ToastProvider, useToast } from '@annondeveloper/ui-kit'\n\nfunction App() {\n  return (\n    <ToastProvider>\n      <MetricCard label=\"CPU Usage\" value={72.4} format={n => `${n.toFixed(1)}%`} status=\"warning\" />\n      <StatusBadge status=\"active\" pulse />\n      <DeployButton />\n    </ToastProvider>\n  )\n}\n\nfunction DeployButton() {\n  const toast = useToast()\n  return <Button variant=\"primary\" onClick={() => toast.success('Deployed!')}>Deploy</Button>\n}\n```\n\n---\n\n## Why This Library?\n\nMost 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.\n\n- **Smart Components** -- SmartTable auto-generates filter suggestions (outliers, top-N, patterns). CommandBar provides fuzzy search with recent history.\n- **AI-Ready** -- StreamingText renders LLM output with a blinking cursor. TypingIndicator, ConfidenceBar, and copy-on-complete are built in.\n- **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.\n- **Monitoring** -- MetricCard with trend arrows and sparklines. ThresholdGauge with color-coded zones. UtilizationBar, UptimeTracker, PortStatusGrid, and PipelineStage for infrastructure dashboards.\n- **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.\n- **Developer Experience** -- CLI for scaffolding (`npx @annondeveloper/ui-kit add button`). react-hook-form adapters. Zero config theming. Full TypeScript coverage with exported types.\n\n---\n\n## Component Reference\n\n### Core\n\n#### Button\n\nA themed button with variant, size, and loading support.\n\n```tsx\nimport { Button } from '@annondeveloper/ui-kit'\n\n<Button variant=\"primary\" size=\"md\" loading={isPending}>Save</Button>\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `variant` | `'primary' \\| 'secondary' \\| 'danger' \\| 'outline' \\| 'ghost'` | `'primary'` | Visual variant |\n| `size` | `'sm' \\| 'md' \\| 'lg' \\| 'icon'` | `'md'` | Size preset |\n| `loading` | `boolean` | `false` | Show spinner and disable interaction |\n\nExtends all native `<button>` attributes. Supports `ref` forwarding.\n\n---\n\n#### Badge\n\nA pill-shaped label with 10 color presets and optional icon.\n\n```tsx\nimport { Badge, createBadgeVariant } from '@annondeveloper/ui-kit'\nimport { Shield } from 'lucide-react'\n\n<Badge color=\"green\" icon={Shield} size=\"sm\">Secure</Badge>\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `children` | `ReactNode` | -- | Badge content |\n| `color` | `'brand' \\| 'blue' \\| 'green' \\| 'yellow' \\| 'red' \\| 'orange' \\| 'purple' \\| 'pink' \\| 'teal' \\| 'gray'` | `'gray'` | Color preset |\n| `icon` | `LucideIcon` | -- | Optional icon before the label |\n| `size` | `'xs' \\| 'sm' \\| 'md'` | `'sm'` | Size variant |\n\n##### Badge Factory\n\nCreate domain-specific badge components without modifying the library:\n\n```tsx\nconst SeverityBadge = createBadgeVariant({\n  colorMap: { critical: 'red', warning: 'yellow', info: 'blue' },\n  labelMap: { critical: 'Critical', warning: 'Warning', info: 'Info' },\n})\n\n<SeverityBadge value=\"critical\" />\n```\n\n---\n\n#### Card\n\nA styled card container with semantic structure via children.\n\n```tsx\nimport { Card } from '@annondeveloper/ui-kit'\n\n<Card variant=\"interactive\" padding=\"lg\">\n  <h2>Server Health</h2>\n  <p>All systems operational</p>\n</Card>\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `variant` | `'default' \\| 'elevated' \\| 'outlined' \\| 'interactive'` | `'default'` | Visual variant (`interactive` adds hover effect) |\n| `padding` | `'none' \\| 'sm' \\| 'md' \\| 'lg'` | `'md'` | Padding preset |\n\nSupports `ref` forwarding and all native HTML attributes.\n\n---\n\n#### Tabs\n\nAccessible tabbed interface with three visual variants and animated indicator.\n\n```tsx\nimport { Tabs } from '@annondeveloper/ui-kit'\n\n<Tabs tabs={[{ value: 'metrics', label: 'Metrics' }, { value: 'logs', label: 'Logs' }]}\n      value={tab} onChange={setTab} variant=\"pills\" />\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `tabs` | `Tab[]` | -- | Array of `{ value, label, icon?, disabled? }` |\n| `value` | `string` | -- | Currently selected tab value |\n| `onChange` | `(value: string) => void` | -- | Selection callback |\n| `variant` | `'underline' \\| 'pills' \\| 'enclosed'` | `'underline'` | Visual variant |\n| `size` | `'sm' \\| 'md'` | `'md'` | Size preset |\n\nSupports keyboard navigation (arrow keys, Home, End) and ARIA roles. Animated indicator uses Framer Motion `layoutId`.\n\n---\n\n#### Sheet\n\nA slide-over drawer panel from any screen edge.\n\n```tsx\nimport { Sheet } from '@annondeveloper/ui-kit'\n\n<Sheet open={isOpen} onClose={() => setOpen(false)} title=\"Settings\" side=\"right\" width=\"max-w-lg\">\n  {children}\n</Sheet>\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `open` | `boolean` | -- | Whether the sheet is open |\n| `onClose` | `() => void` | -- | Close callback |\n| `side` | `'right' \\| 'left' \\| 'top' \\| 'bottom'` | `'right'` | Slide-in edge |\n| `title` | `string` | -- | Header title |\n| `description` | `string` | -- | Header description |\n| `width` | `string` | `'max-w-md'` | Width/height class |\n\nFeatures: backdrop blur, spring animation, Escape to close, body scroll lock, auto-focus.\n\n---\n\n#### Tooltip\n\nSimple tooltip wrapper built on Radix UI with theme-styled content and arrow pointer.\n\n```tsx\nimport { Tooltip } from '@annondeveloper/ui-kit'\n\n<Tooltip content=\"Copy to clipboard\" side=\"top\"><button>...</button></Tooltip>\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `content` | `ReactNode` | -- | Tooltip content |\n| `children` | `ReactNode` | -- | Trigger element |\n| `side` | `'top' \\| 'right' \\| 'bottom' \\| 'left'` | `'top'` | Display side |\n| `delay` | `number` | `200` | Delay in ms |\n\n---\n\n#### Popover\n\nPopover wrapper built on Radix Popover with Framer Motion entry animation.\n\n```tsx\nimport { Popover } from '@annondeveloper/ui-kit'\n\n<Popover trigger={<button>Options</button>} side=\"bottom\" align=\"end\">\n  <p>Popover content</p>\n</Popover>\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `trigger` | `ReactNode` | -- | Element that opens the popover |\n| `children` | `ReactNode` | -- | Popover content |\n| `side` | `'top' \\| 'right' \\| 'bottom' \\| 'left'` | `'bottom'` | Display side |\n| `align` | `'start' \\| 'center' \\| 'end'` | `'center'` | Alignment |\n\n---\n\n#### DropdownMenu\n\nAction/context dropdown menu built on Radix DropdownMenu with danger variant support.\n\n```tsx\nimport { DropdownMenu } from '@annondeveloper/ui-kit'\nimport { Edit, Trash2 } from 'lucide-react'\n\n<DropdownMenu\n  trigger={<button>Actions</button>}\n  items={[\n    { label: 'Edit', icon: Edit, onClick: handleEdit },\n    { label: 'Delete', icon: Trash2, onClick: handleDelete, variant: 'danger' },\n  ]}\n/>\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `trigger` | `ReactNode` | -- | Element that opens the menu |\n| `items` | `MenuItem[]` | -- | `{ label, icon?, onClick, variant?, disabled? }` |\n| `align` | `'start' \\| 'center' \\| 'end'` | `'end'` | Menu alignment |\n\n---\n\n#### ConfirmDialog\n\nConfirmation modal built on Radix AlertDialog with animated enter/exit.\n\n```tsx\nimport { ConfirmDialog } from '@annondeveloper/ui-kit'\n\n<ConfirmDialog\n  open={showDelete} onOpenChange={setShowDelete}\n  title=\"Delete server?\" description=\"This action cannot be undone.\"\n  variant=\"danger\" confirmLabel=\"Delete\" loading={isDeleting}\n  onConfirm={handleDelete}\n/>\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `open` | `boolean` | -- | Control open state |\n| `onOpenChange` | `(open: boolean) => void` | -- | Open state callback |\n| `title` | `string` | -- | Dialog title |\n| `description` | `string` | -- | Dialog description |\n| `confirmLabel` | `string` | `'Confirm'` | Confirm button text |\n| `cancelLabel` | `string` | `'Cancel'` | Cancel button text |\n| `variant` | `'danger' \\| 'warning' \\| 'default'` | `'danger'` | Icon and button color |\n| `loading` | `boolean` | `false` | Show spinner on confirm button |\n| `onConfirm` | `() => void` | -- | Confirm callback |\n\n---\n\n### Forms\n\n#### FormInput\n\nThemed form input with label, required indicator, and optional hint text.\n\n```tsx\nimport { FormInput } from '@annondeveloper/ui-kit'\n\n<FormInput label=\"Hostname\" value={host} onChange={setHost} placeholder=\"10.0.0.1\" required hint=\"IPv4 or FQDN\" />\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `label` | `string` | -- | Label text |\n| `value` | `string` | -- | Input value |\n| `onChange` | `(value: string) => void` | -- | Value change callback |\n| `type` | `string` | `'text'` | HTML input type |\n| `placeholder` | `string` | -- | Placeholder text |\n| `required` | `boolean` | -- | Show required indicator |\n| `disabled` | `boolean` | -- | Disable input |\n| `hint` | `string` | -- | Help text below input |\n| `autoComplete` | `string` | -- | Autocomplete attribute |\n\nSupports `ref` forwarding and all native input attributes.\n\n---\n\n#### Select\n\nThemed dropdown built on Radix UI Select.\n\n```tsx\nimport { Select } from '@annondeveloper/ui-kit'\n\n<Select value={protocol} onValueChange={setProtocol}\n        options={[{ value: 'snmp', label: 'SNMP' }, { value: 'ssh', label: 'SSH' }]}\n        placeholder=\"Select protocol\" />\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `value` | `string` | -- | Selected value |\n| `onValueChange` | `(v: string) => void` | -- | Selection callback |\n| `options` | `SelectOption[]` | -- | `{ value, label }` |\n| `placeholder` | `string` | -- | Placeholder text |\n| `disabled` | `boolean` | -- | Disable select |\n\n---\n\n#### Checkbox\n\nThemed checkbox with indeterminate state support. Forwards ref.\n\n```tsx\nimport { Checkbox } from '@annondeveloper/ui-kit'\n\n<Checkbox checked={selected} onChange={handleChange} indeterminate={isPartial} size=\"sm\" />\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `indeterminate` | `boolean` | -- | Show minus indicator |\n| `size` | `'sm' \\| 'md'` | `'md'` | Size variant |\n\nExtends native `<input>` attributes (except `type` and `size`).\n\n---\n\n#### ToggleSwitch\n\nIcon-based boolean toggle using lucide icons.\n\n```tsx\nimport { ToggleSwitch } from '@annondeveloper/ui-kit'\n\n<ToggleSwitch enabled={isActive} onChange={setIsActive} label=\"Auto-refresh\" />\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `enabled` | `boolean` | -- | Toggle state |\n| `onChange` | `(enabled: boolean) => void` | -- | Change callback |\n| `size` | `'sm' \\| 'md'` | `'md'` | Size variant |\n| `disabled` | `boolean` | -- | Disable toggle |\n| `label` | `string` | -- | Accessible label |\n\n---\n\n#### RadioGroup\n\nCustom-styled radio button group with animated selection indicator.\n\n```tsx\nimport { RadioGroup } from '@annondeveloper/ui-kit'\n\n<RadioGroup\n  options={[\n    { value: 'v2c', label: 'SNMPv2c' },\n    { value: 'v3', label: 'SNMPv3', description: 'Recommended for production' },\n  ]}\n  value={version} onChange={setVersion} orientation=\"vertical\"\n/>\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `options` | `RadioOption[]` | -- | `{ value, label, description?, disabled? }` |\n| `value` | `string` | -- | Selected value |\n| `onChange` | `(value: string) => void` | -- | Selection callback |\n| `orientation` | `'horizontal' \\| 'vertical'` | `'vertical'` | Layout direction |\n\nSupports keyboard navigation (arrow keys, Home, End) and ARIA roles.\n\n---\n\n#### Slider\n\nCustom range slider with keyboard accessibility and hover tooltip.\n\n```tsx\nimport { Slider } from '@annondeveloper/ui-kit'\n\n<Slider value={threshold} onChange={setThreshold} min={0} max={100} step={5} label=\"Alert threshold\" showValue />\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `value` | `number` | -- | Current value |\n| `onChange` | `(value: number) => void` | -- | Change callback |\n| `min` | `number` | `0` | Minimum value |\n| `max` | `number` | `100` | Maximum value |\n| `step` | `number` | `1` | Step increment |\n| `label` | `string` | -- | Label text |\n| `showValue` | `boolean` | `false` | Show value display |\n\nSupports keyboard (arrow keys, Home, End), mouse drag, and touch.\n\n---\n\n#### ColorInput\n\nCompact color picker with expandable panel, hue/saturation area, format switching, and presets.\n\n```tsx\nimport { ColorInput } from '@annondeveloper/ui-kit'\n\n<ColorInput value={color} onChange={setColor} label=\"Accent\" format=\"hex\"\n            presets={['#3b82f6', '#10b981', '#f59e0b', '#ef4444']} />\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `value` | `string` | -- | Hex color string |\n| `onChange` | `(color: string) => void` | -- | Change callback |\n| `label` | `string` | -- | Optional label |\n| `presets` | `string[]` | -- | Preset color swatches |\n| `showAlpha` | `boolean` | `false` | Show alpha slider |\n| `format` | `'hex' \\| 'rgb' \\| 'hsl'` | `'hex'` | Display format |\n\nFeatures: HSL picker area, hue slider, format switching, clipboard copy, recent color history (localStorage).\n\n---\n\n#### StepWizard\n\nMulti-step form wizard with animated slide transitions and per-step validation.\n\n```tsx\nimport { StepWizard } from '@annondeveloper/ui-kit'\n\n<StepWizard\n  steps={[\n    { id: 'creds', title: 'Credentials', content: <CredentialsForm /> },\n    { id: 'targets', title: 'Targets', content: <TargetForm />, validate: () => targets.length > 0 },\n    { id: 'review', title: 'Review', content: <ReviewSummary /> },\n  ]}\n  onComplete={handleDeploy} showSummary\n/>\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `steps` | `WizardStep[]` | -- | `{ id, title, description?, icon?, content, validate? }` |\n| `onComplete` | `() => void` | -- | Final step completion callback |\n| `onStepChange` | `(step: number) => void` | -- | Step change callback |\n| `orientation` | `'horizontal' \\| 'vertical'` | `'horizontal'` | Step indicator layout |\n| `allowSkip` | `boolean` | `false` | Allow skipping to uncompleted steps |\n| `showSummary` | `boolean` | `false` | Show completion state after last step |\n\nFeatures: animated step transitions, progress bar, keyboard navigation (Enter to advance), session storage auto-save, async validation.\n\n---\n\n#### FilterPill\n\nRounded pill-style filter toggle with optional count.\n\n```tsx\nimport { FilterPill } from '@annondeveloper/ui-kit'\n\n<FilterPill label=\"Critical\" count={12} active={filter === 'critical'} onClick={() => setFilter('critical')} />\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `label` | `string` | -- | Pill text |\n| `count` | `number` | -- | Optional count badge |\n| `active` | `boolean` | -- | Active/selected state |\n| `onClick` | `() => void` | -- | Click handler |\n\n---\n\n### Data Display\n\n#### DataTable\n\nFull-featured data grid built on TanStack Table v8.\n\n```tsx\nimport { DataTable } from '@annondeveloper/ui-kit'\n\n<DataTable\n  columns={columns} data={devices} isLoading={isLoading}\n  searchPlaceholder=\"Search devices...\"\n  defaultPageSize={25} exportFilename=\"devices\"\n  onRowClick={(row) => router.push(`/devices/${row.id}`)}\n  emptyState={{ icon: Server, title: 'No devices', description: 'Run a discovery scan to get started.' }}\n/>\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `columns` | `ColumnDef<T>[]` | -- | TanStack column definitions |\n| `data` | `T[]` | -- | Row data |\n| `isLoading` | `boolean` | `false` | Show loading skeleton |\n| `emptyState` | `{ icon, title, description }` | -- | Custom empty state |\n| `searchPlaceholder` | `string` | `'Search...'` | Search input placeholder |\n| `onRowClick` | `(row: T) => void` | -- | Row click handler |\n| `defaultSort` | `{ id, desc }` | -- | Initial sort configuration |\n| `defaultPageSize` | `number` | `25` | Rows per page |\n| `exportFilename` | `string` | -- | Enables CSV export button |\n| `stickyFirstColumn` | `boolean` | `false` | Sticky first column on scroll |\n| `density` | `'compact' \\| 'comfortable' \\| 'spacious'` | `'comfortable'` | Row density |\n\nBuilt-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.\n\n---\n\n#### SmartTable\n\nEnhanced DataTable that auto-generates filter suggestions by analyzing column data.\n\n```tsx\nimport { SmartTable } from '@annondeveloper/ui-kit'\n\n<SmartTable columns={columns} data={data} maxSuggestions={4} onFilterSuggestion={console.log} />\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| ...all DataTable props | | | Inherits all DataTable props |\n| `onFilterSuggestion` | `(suggestion: FilterSuggestion) => void` | -- | Suggestion click callback |\n| `maxSuggestions` | `number` | `6` | Max visible suggestions |\n\nAuto-detects: statistical outliers (>2 std dev), top-N frequent values, dominant pattern detection, minority value highlighting.\n\n---\n\n#### AnimatedCounter\n\nSmooth number animation using requestAnimationFrame with cubic easing.\n\n```tsx\nimport { AnimatedCounter } from '@annondeveloper/ui-kit'\n\n<AnimatedCounter value={deviceCount} duration={400} format={n => n.toLocaleString()} />\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `value` | `number` | -- | Target value |\n| `duration` | `number` | `400` | Animation duration (ms) |\n| `format` | `(n: number) => string` | -- | Custom number formatter |\n\n---\n\n#### Sparkline\n\nTiny inline SVG sparkline chart with gradient fill.\n\n```tsx\nimport { Sparkline } from '@annondeveloper/ui-kit'\n\n<Sparkline data={[10, 25, 18, 30, 22]} width={80} height={24} showDots />\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `data` | `number[]` | -- | Values to plot (min 2) |\n| `width` | `number` | `80` | SVG width |\n| `height` | `number` | `24` | SVG height |\n| `color` | `string` | `'hsl(var(--brand-primary))'` | Line color |\n| `fillOpacity` | `number` | `0.1` | Gradient fill opacity (0 to disable) |\n| `showDots` | `boolean` | `false` | Dots on first/last points |\n\n---\n\n#### TruncatedText\n\nAuto-truncating text with tooltip and copy-to-clipboard on hover.\n\n```tsx\nimport { TruncatedText } from '@annondeveloper/ui-kit'\n\n<TruncatedText text=\"very-long-hostname-that-overflows.example.com\" maxWidth={200} />\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `text` | `string` | -- | Full text content |\n| `maxWidth` | `string \\| number` | `'100%'` | Max width for truncation |\n\n---\n\n#### CopyBlock\n\nMonospace code/text display with one-click copy and collapsible overflow.\n\n```tsx\nimport { CopyBlock } from '@annondeveloper/ui-kit'\n\n<CopyBlock content=\"curl -X GET https://api.example.com/health\" language=\"bash\" label=\"Health check\" />\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `content` | `string` | -- | Text content |\n| `language` | `string` | -- | Language hint (e.g. \"json\", \"bash\") |\n| `showLineNumbers` | `boolean` | `false` | Show line number gutter |\n| `maxHeight` | `number` | -- | Max height before \"Show more\" toggle |\n| `label` | `string` | -- | Label above the block |\n\n---\n\n#### DiffViewer\n\nLine-by-line diff viewer using LCS algorithm with collapsible unchanged sections.\n\n```tsx\nimport { DiffViewer } from '@annondeveloper/ui-kit'\n\n<DiffViewer oldValue={previousConfig} newValue={currentConfig} mode=\"side-by-side\" showLineNumbers />\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `oldValue` | `string` | -- | Original text |\n| `newValue` | `string` | -- | Modified text |\n| `mode` | `'inline' \\| 'side-by-side'` | `'inline'` | Display mode |\n| `language` | `string` | -- | Language hint |\n| `showLineNumbers` | `boolean` | `true` | Show line numbers |\n\n---\n\n### Status & Monitoring\n\n#### StatusBadge\n\nConfigurable status indicator with colored dot and label.\n\n```tsx\nimport { StatusBadge, defaultStatusMap } from '@annondeveloper/ui-kit'\n\n<StatusBadge status=\"active\" pulse />\n<StatusBadge status=\"healthy\" statusMap={myCustomStatuses} />\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `status` | `string` | -- | Status key |\n| `label` | `string` | -- | Override display label |\n| `size` | `'sm' \\| 'md'` | `'md'` | Size variant |\n| `pulse` | `boolean` | `false` | Pulse animation on the dot |\n| `statusMap` | `Record<string, StatusConfig>` | `defaultStatusMap` | Custom status definitions |\n\nBuilt-in statuses: `ok`, `active`, `warning`, `critical`, `unknown`, `maintenance`, `stale`, `inactive`, `decommissioned`, `pending`.\n\n---\n\n#### StatusPulse\n\nAnimated status dot with optional pulse ring and label.\n\n```tsx\nimport { StatusPulse } from '@annondeveloper/ui-kit'\n\n<StatusPulse status=\"online\" />\n<StatusPulse status=\"degraded\" label={false} />\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `status` | `string` | -- | Status key |\n| `label` | `boolean` | `true` | Show status text |\n| `configMap` | `Record<string, PulseConfig>` | `defaultPulseConfigMap` | Custom pulse configs |\n\nBuilt-in statuses: `online` (green pulse), `degraded` (yellow fast pulse), `offline` (red, no pulse), `unknown` (gray, no pulse).\n\n---\n\n#### MetricCard\n\nDashboard stat tile with animated counter, trend indicator, and optional sparkline.\n\n```tsx\nimport { MetricCard } from '@annondeveloper/ui-kit'\nimport { HardDrive } from 'lucide-react'\n\n<MetricCard\n  label=\"Disk Usage\" value={78.3} format={n => `${n.toFixed(1)}%`}\n  previousValue={72.1} trendDirection=\"up-bad\"\n  icon={HardDrive} status=\"warning\"\n  sparklineData={[65, 68, 70, 72, 75, 78]}\n/>\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `label` | `string` | -- | Metric name |\n| `value` | `number` | -- | Current value |\n| `format` | `(n: number) => string` | -- | Custom formatter |\n| `previousValue` | `number` | -- | Previous value for trend |\n| `trendDirection` | `'up-good' \\| 'up-bad' \\| 'down-good' \\| 'down-bad'` | -- | Color interpretation |\n| `icon` | `ElementType` | -- | Lucide icon component |\n| `status` | `'ok' \\| 'warning' \\| 'critical'` | -- | Left border accent color |\n| `sparklineData` | `number[]` | -- | Recent values for inline chart |\n\n---\n\n#### ThresholdGauge\n\nSemicircular SVG gauge with color-coded threshold zones.\n\n```tsx\nimport { ThresholdGauge } from '@annondeveloper/ui-kit'\n\n<ThresholdGauge value={85} label=\"CPU\" thresholds={{ warning: 70, critical: 90 }} size={120} />\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `value` | `number` | -- | Gauge value (0-100) |\n| `label` | `string` | -- | Label below gauge |\n| `thresholds` | `{ warning, critical }` | `{ warning: 70, critical: 90 }` | Color zone boundaries |\n| `size` | `number` | `120` | Diameter in pixels |\n| `showValue` | `boolean` | `true` | Show value in center |\n| `format` | `(n: number) => string` | -- | Custom value formatter |\n\n---\n\n#### UtilizationBar\n\nHorizontal bar with color-coded thresholds. Animates fill on mount.\n\n```tsx\nimport { UtilizationBar } from '@annondeveloper/ui-kit'\n\n<UtilizationBar value={92} label=\"Memory\" thresholds={{ warning: 70, critical: 90 }} size=\"md\" />\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `value` | `number` | -- | Utilization percentage (0-100) |\n| `thresholds` | `{ warning, critical }` | `{ warning: 70, critical: 90 }` | Color zone boundaries |\n| `label` | `string` | -- | Label to the left |\n| `showValue` | `boolean` | `true` | Show percentage text |\n| `size` | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Bar height |\n| `animated` | `boolean` | `true` | Animate fill width |\n\n---\n\n#### UptimeTracker\n\nGitHub/Statuspage-style daily uptime bar strip.\n\n```tsx\nimport { UptimeTracker } from '@annondeveloper/ui-kit'\n\n<UptimeTracker\n  days={last90Days} label=\"API Server\" showPercentage\n  onDayClick={(day) => showIncidents(day.date)}\n/>\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `days` | `DayStatus[]` | -- | `{ date, status: 'ok'\\|'degraded'\\|'outage'\\|'no-data', uptime? }` |\n| `showPercentage` | `boolean` | `true` | Show overall uptime % |\n| `label` | `string` | -- | Header label |\n| `onDayClick` | `(day: DayStatus) => void` | -- | Day click callback |\n\n---\n\n#### PortStatusGrid\n\nGrid of colored indicators for network ports/interfaces.\n\n```tsx\nimport { PortStatusGrid } from '@annondeveloper/ui-kit'\n\n<PortStatusGrid\n  ports={switchPorts} columns={24} size=\"md\"\n  onPortClick={(port) => showPortDetail(port.id)}\n/>\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `ports` | `PortStatus[]` | -- | `{ id, label, status: 'up'\\|'down'\\|'disabled'\\|'error', speed?, utilization? }` |\n| `columns` | `number` | auto-fit | Grid columns |\n| `size` | `'sm' \\| 'md'` | `'sm'` | Indicator size |\n| `onPortClick` | `(port: PortStatus) => void` | -- | Port click callback |\n\n---\n\n#### PipelineStage\n\nHorizontal data pipeline visualization with status dots and chevron connectors.\n\n```tsx\nimport { PipelineStage } from '@annondeveloper/ui-kit'\n\n<PipelineStage\n  stages={[\n    { name: 'Collector', status: 'active', metric: { label: 'msg/s', value: '1.2K' } },\n    { name: 'Normalizer', status: 'active' },\n    { name: 'Writer', status: 'error' },\n  ]}\n  onStageClick={(stage) => showStageDetail(stage)}\n/>\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `stages` | `StageInfo[]` | -- | `{ name, status: 'active'\\|'idle'\\|'error'\\|'disabled', metric?, icon? }` |\n| `onStageClick` | `(stage, index) => void` | -- | Stage click callback |\n\n---\n\n#### SeverityTimeline\n\nHorizontal scrollable event timeline with severity-colored dots.\n\n```tsx\nimport { SeverityTimeline } from '@annondeveloper/ui-kit'\n\n<SeverityTimeline events={recentAlerts} maxVisible={20} onEventClick={showAlertDetail} />\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `events` | `TimelineEvent[]` | -- | `{ time, label, severity: 'critical'\\|'warning'\\|'info'\\|'ok', detail? }` |\n| `maxVisible` | `number` | `20` | Max visible events |\n| `onEventClick` | `(event) => void` | -- | Event click callback |\n\n---\n\n#### TimeRangeSelector\n\nCompact horizontal pill-group time range selector.\n\n```tsx\nimport { TimeRangeSelector } from '@annondeveloper/ui-kit'\n\n<TimeRangeSelector value={range} onChange={(v, r) => setRange(v)} />\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `value` | `string` | -- | Selected range value |\n| `onChange` | `(value, range) => void` | -- | Selection callback |\n| `ranges` | `TimeRange[]` | `[1h, 6h, 24h, 7d, 30d]` | Custom range options (each `{ label, value, seconds }`) |\n\n---\n\n#### LogViewer\n\nReal-time log stream viewer with severity-colored borders and auto-scroll.\n\n```tsx\nimport { LogViewer } from '@annondeveloper/ui-kit'\n\n<LogViewer entries={logs} maxHeight={400} autoScroll showTimestamps onEntryClick={showDetail} />\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `entries` | `LogEntry[]` | -- | `{ time, level: 'error'\\|'warn'\\|'info'\\|'debug'\\|'trace', message, source? }` |\n| `maxHeight` | `number` | `400` | Container max height |\n| `autoScroll` | `boolean` | `true` | Auto-scroll on new entries |\n| `showTimestamps` | `boolean` | `true` | Show timestamps column |\n| `showLevel` | `boolean` | `true` | Show level badge |\n| `onEntryClick` | `(entry) => void` | -- | Entry click callback |\n\nFeatures: search filtering, \"N new entries\" floating badge when scrolled up.\n\n---\n\n### Real-Time & AI\n\n#### RealtimeValue\n\nLive data display with freshness tracking, connection state, and delta arrows.\n\n```tsx\nimport { RealtimeValue } from '@annondeveloper/ui-kit'\nimport { fmtBps } from '@annondeveloper/ui-kit'\n\n<RealtimeValue\n  value={throughput} format={fmtBps}\n  previousValue={prevThroughput} lastUpdated={lastTs}\n  staleAfterMs={30000} connectionState=\"connected\" size=\"lg\"\n/>\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `value` | `number \\| string` | -- | Current value |\n| `label` | `string` | -- | Label text |\n| `format` | `(v: number) => string` | -- | Custom formatter |\n| `lastUpdated` | `string \\| Date` | -- | Last data timestamp |\n| `staleAfterMs` | `number` | `30000` | Staleness threshold (ms) |\n| `connectionState` | `'connected' \\| 'reconnecting' \\| 'disconnected'` | `'connected'` | Connection indicator |\n| `previousValue` | `number` | -- | Previous value for delta |\n| `animate` | `boolean` | `true` | Animate value changes |\n| `size` | `'sm' \\| 'md' \\| 'lg' \\| 'xl'` | `'md'` | Display size |\n\nFeatures: animated number transitions, freshness dot (green/yellow/red), ping animation when fresh, connection state icon (reconnecting spinner, disconnected icon), auto-updating relative timestamp.\n\n---\n\n#### StreamingText\n\nAI/LLM streaming text display with blinking cursor and inline markdown formatting.\n\n```tsx\nimport { StreamingText } from '@annondeveloper/ui-kit'\n\n<StreamingText text={response} isStreaming={isGenerating} onComplete={() => logCompletion()} />\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `text` | `string` | -- | Text content (grows as tokens arrive) |\n| `isStreaming` | `boolean` | -- | Whether tokens are still arriving |\n| `speed` | `number` | `500` | Cursor blink speed (ms) |\n| `showCursor` | `boolean` | `true` | Show blinking cursor |\n| `onComplete` | `() => void` | -- | Streaming complete callback |\n\nFeatures: auto-scroll during streaming, inline `**bold**` and `` `code` `` formatting, copy button appears on completion.\n\n---\n\n#### TypingIndicator\n\n\"Someone is typing\" indicator with three animation variants.\n\n```tsx\nimport { TypingIndicator } from '@annondeveloper/ui-kit'\n\n<TypingIndicator variant=\"dots\" label=\"AI is thinking\" size=\"md\" />\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `label` | `string` | -- | Status text |\n| `variant` | `'dots' \\| 'pulse' \\| 'text'` | `'dots'` | Animation variant |\n| `size` | `'sm' \\| 'md'` | `'md'` | Size preset |\n\n---\n\n#### ConfidenceBar\n\nHorizontal probability bar with color-coded threshold zones.\n\n```tsx\nimport { ConfidenceBar } from '@annondeveloper/ui-kit'\n\n<ConfidenceBar value={0.87} label=\"Match confidence\" thresholds={{ low: 0.3, medium: 0.7 }} />\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `value` | `number` | -- | Confidence (0-1) |\n| `label` | `string` | -- | Label text |\n| `showPercentage` | `boolean` | `true` | Show percentage |\n| `thresholds` | `{ low, medium }` | `{ low: 0.3, medium: 0.7 }` | Color zone boundaries |\n| `size` | `'sm' \\| 'md'` | `'md'` | Bar height |\n\n---\n\n#### CommandBar\n\nUniversal command palette activated by Cmd+K / Ctrl+K.\n\n```tsx\nimport { CommandBar } from '@annondeveloper/ui-kit'\n\n<CommandBar\n  items={[\n    { id: 'devices', label: 'Go to Devices', shortcut: 'G D', onSelect: () => navigate('/devices') },\n    { id: 'search', label: 'Search entities', icon: Search, onSelect: openSearch, keywords: ['find'] },\n  ]}\n  placeholder=\"Type a command...\"\n  onSearch={async (q) => fetchResults(q)}\n/>\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `items` | `CommandItem[]` | -- | `{ id, label, description?, icon?, shortcut?, group?, onSelect, keywords? }` |\n| `placeholder` | `string` | `'Type a command...'` | Search placeholder |\n| `hotkey` | `string` | `'k'` | Hotkey letter (Cmd/Ctrl+key) |\n| `onSearch` | `(query) => Promise<CommandItem[]>` | -- | Async search function |\n| `recentKey` | `string` | `'ui-kit-command-recent'` | localStorage key for recents |\n| `maxRecent` | `number` | `5` | Max recent items |\n\nFeatures: fuzzy search scoring, grouped sections, recent selections (localStorage), async search with debounce, keyboard navigation (arrows + Enter), keyboard shortcut hints in footer.\n\n---\n\n#### LiveFeed\n\nReal-time event feed with animated entry, pause/resume, and type-colored borders.\n\n```tsx\nimport { LiveFeed } from '@annondeveloper/ui-kit'\n\n<LiveFeed\n  items={events} maxVisible={50} showTimestamps autoScroll\n  onItemClick={(item) => showDetail(item.id)}\n  emptyMessage=\"Waiting for events...\"\n/>\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `items` | `FeedItem[]` | -- | `{ id, content: ReactNode, timestamp, type?: 'info'\\|'success'\\|'warning'\\|'error' }` |\n| `maxVisible` | `number` | `50` | Max visible items |\n| `showTimestamps` | `boolean` | `true` | Show relative timestamps |\n| `autoScroll` | `boolean` | `true` | Auto-scroll to newest |\n| `onItemClick` | `(item) => void` | -- | Item click callback |\n| `emptyMessage` | `string` | `'No events yet'` | Empty state text |\n\nFeatures: pause/resume button, \"N new items\" floating badge when scrolled, auto-updating relative timestamps.\n\n---\n\n#### NotificationStack\n\nFixed-position notification cards with auto-dismiss progress bars.\n\n```tsx\nimport { NotificationStack } from '@annondeveloper/ui-kit'\n\n<NotificationStack\n  notifications={notifications}\n  onDismiss={(id) => removeNotification(id)}\n  position=\"top-right\" maxVisible={5}\n/>\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `notifications` | `Notification[]` | -- | `{ id, title, message?, type, action?, dismissible?, duration? }` |\n| `onDismiss` | `(id: string) => void` | -- | Dismiss callback |\n| `position` | `'top-right' \\| 'top-left' \\| 'bottom-right' \\| 'bottom-left'` | `'top-right'` | Screen position |\n| `maxVisible` | `number` | `5` | Max visible before stacking |\n\nFeatures: type-specific icons and colors, action buttons, auto-dismiss with progress bar, overflow indicator, spring entry/exit animations.\n\n---\n\n### Layout & Feedback\n\n#### EmptyState\n\nDecorative placeholder with icon, title, description, and optional actions.\n\n```tsx\nimport { EmptyState, Button } from '@annondeveloper/ui-kit'\nimport { Inbox } from 'lucide-react'\n\n<EmptyState icon={Inbox} title=\"No alerts\" description=\"Your infrastructure is healthy.\"\n            actions={<Button size=\"sm\">Configure Rules</Button>} />\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `icon` | `LucideIcon` | -- | Center icon |\n| `title` | `string` | -- | Title text |\n| `description` | `string` | -- | Description text |\n| `actions` | `ReactNode` | -- | Action buttons |\n\n---\n\n#### Skeleton\n\nShimmer loading placeholder.\n\n```tsx\nimport { Skeleton } from '@annondeveloper/ui-kit'\n\n<Skeleton width={128} height={32} />\n<Skeleton width=\"100%\" height={16} />\n<Skeleton variant=\"circle\" width={40} height={40} />\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `width` | `string \\| number` | `'100%'` | Skeleton width |\n| `height` | `string \\| number` | `'1em'` | Skeleton height |\n| `variant` | `'rect' \\| 'circle'` | `'rect'` | Shape variant |\n\n---\n\n#### Progress\n\nProgress bar with optional label, animated fill, and indeterminate mode.\n\n```tsx\nimport { Progress } from '@annondeveloper/ui-kit'\n\n<Progress value={65} max={100} label=\"Upload\" showValue variant=\"success\" />\n<Progress indeterminate label=\"Processing...\" />\n```\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `value` | `number` | -- | Current value |\n| `max` | `number` | `100` | Maximum value |\n| `label` | `string` | -- | Label text |\n| `showValue` | `boolean` | `false` | Show percentage |\n| `variant` | `'default' \\| 'success' \\| 'warning' \\| 'danger'` | `'default'` | Color variant |\n| `size` | `'sm' \\| 'md' \\| 'lg'` | `'md'` | Bar height |\n| `animated` | `boolean` | `true` | Animate fill changes |\n| `indeterminate` | `boolean` | `false` | Shimmer animation |\n\n---\n\n#### Avatar\n\nUser/entity ",
  "bytes": 60000,
  "sha": "62510e5545c6059d7ffe2151083c6d25de5e4ae98340910d184bdcbe1e5d890d",
  "repo_slug": "annondeveloper/ui-kit",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_annondeveloper_ui_kit_ui_kit_7e0a0a80/readme"
}