# @pxengine-ui

> **Shadcn-based UI component library for agent-driven interfaces**

A premium UI component library built on top of shadcn/ui, designed specifically for agent-driven user interfaces and creator discovery platforms. Components follow Atomic Design principles and are optimized for schema-driven rendering.

---

## Overview

`@pxengine-ui` provides a robust foundation for building modern dashboard and AI-integrated applications:

- **Built on shadcn/ui** - Industry-standard base layer using Radix UI primitives.
- **Vibrant & Premium** - Custom design system with glassmorphism, smooth gradients, and rich micro-interactions.
- **Agent-First** - Fully schema-driven atoms ready for AI generation.
- **Atomic Design** - 40+ Atoms and 18+ Composed Molecules.
- **Zero Configuration** - Inherits Tailwind config and CSS variables from the host application.

---

## Structure

```
@pxengine-ui/
├── src/
│   ├── atoms/               # Foundation UI (Button, Input, Slider, etc.)
│   ├── molecules/           # Composed Patterns
│   │   ├── generic/         # Cross-domain dashboard widgets
│   │   └── creator-discovery/ # Niche-specific for creator search
│   ├── types/               # Schema & Component definitions
│   └── lib/                 # Shared utilities
└── dist/                    # Compiled assets & Registry
```

---

## Component Catalog

### Atoms (Foundation Primitives)

40+ accessible atoms wrapping Radix-based shadcn components:

- **Forms**: Input, Checkbox, RadioGroup, Select, Switch, Slider, Textarea, Toggle.
- **Navigation**: DropdownMenu, ContextMenu, Pagination, Breadcrumb, Tabs, Command.
- **Overlay**: Dialog, AlertDialog, Drawer, Sheet, Popover, Tooltip.
- **Display**: Card, Badge, Avatar, Accordion, AspectRatio, Skeleton, Separator, Progress.
- **Specialized**: Resizable Panels, InputOTP, Kbd (Keyboard shortcuts).

### Molecules (High-Level Patterns)

#### Generic Dashboard

- **StatsGrid**: Data visualization with trends & icons.
- **EmptyState**: Premium placeholder for empty results.
- **LoadingOverlay**: Glassmorphism backdrop with progress.
- **FilterBar**: Search + Multi-chip filtering.
- **FileUpload**: Drag-and-drop zone.
- **TagCloud**: Interactive interest clusters.
- **FormCard**: Schema-driven editable forms.

#### Creator Discovery

- **CreatorGridCard**: Detailed discovery card with banner and metrics.
- **AudienceMetricCard**: Specialized progress-based demographics.
- **BrandAffinityGroup**: Visual recently associated brand logos.
- **ContentPreviewGallery**: Video/Image thumbnail grids.
- **CreatorProfileSummary**: Compact info row for list views.
- **PlatformIconGroup**: Social platform reach summary.
- **SearchSpecCard**: Advanced filter criteria summary.

---

## Usage

### Registry-Driven Rendering

The library generates a `registry.json` that includes component metadata and schemas, allowing agents to understand what they can render.

```tsx
import { PXEngineRenderer } from "@/components/PXEngineRenderer";

const schema = {
  type: "stats-grid",
  items: [
    {
      label: "Total Reach",
      value: "1.2M",
      trend: "+12%",
      trendDirection: "up",
    },
  ],
};

return <PXEngineRenderer schema={schema} />;
```

### Direct Component Import

All components are exported for standard React usage:

```tsx
import { CreatorGridCard } from "pxengine";

<CreatorGridCard
  name="Jane Doe"
  handle="janedoe"
  metrics={[{ label: "Followers", value: "500K" }]}
  platforms={["Instagram", "TikTok"]}
/>;
```

---

## Design System

The library uses a specific high-end aesthetic:

- **Colors**: Indigo, Purple, and Slate primary hues.
- **Border Radius**: Generous `rounded-3xl` and `rounded-[32px]` for major components.
- **Backdrop**: Heavy use of `backdrop-blur-md` and `bg-white/60`.
- **Shadows**: Subtle, layered soft shadows for depth.

---

## Tech Stack

- **Framework**: React 18+ (Vite/tsup build)
- **Styling**: Tailwind CSS + `class-variance-authority`
- **Primitives**: Radix UI
- **Animations**: Framer Motion
- **Icons**: Lucide React
- **Data**: Recharts / Zod