@pxengine-ui

Shadcn-based UI component library for agent-driven interfaces

A UI component library built on top of shadcn/ui, published to npm as pxengine, designed specifically for agent-driven interfaces: LLM agents emit a JSON schema, and PXEngineRenderer maps it to a React component. Components follow Atomic Design principles and are optimized for schema-driven rendering. Primary consumer is pxengine-builder, which links it locally ("pxengine": "file:../@pxengine-ui").

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.
• Themeable via CSS variables - No hardcoded palette. Components read --px-*/host CSS custom properties at render time (falling back to internal purple/indigo defaults when a consumer doesn't supply them), so a dark-gold host app (like pxengine-builder) and a light one render the same components on entirely different themes with zero component changes.
• Agent-First - Fully schema-driven atoms and molecules ready for AI generation via PXEngineRenderer.
• Atomic Design - 52 Atoms and 60+ Composed Molecules across two domains (generic dashboard + creator discovery).
• Zero Configuration - Inherits Tailwind config and CSS variables from the host application; the host just needs "node_modules/pxengine/**/*.{js,ts,jsx,tsx}" in its Tailwind content array or production builds purge all pxengine classes.

Structure

@pxengine-ui/
├── src/
│   ├── atoms/               # Foundation UI (Button, Input, Slider, etc.) — 52 components
│   ├── molecules/           # Composed Patterns
│   │   ├── generic/         # Cross-domain dashboard widgets (~48 components)
│   │   └── creator-discovery/ # Niche-specific for creator search (~16 components)
│   ├── types/               # Schema & Component definitions
│   └── lib/                 # Shared utilities
├── scripts/
│   ├── generate-metadata.ts          # Builds dist/registry.json (component catalog for agents)
│   └── generate-molecule-registry.ts # Builds the molecule-only registry
├── tailwind-preset.js        # Shared Tailwind preset re-exported for consumers
└── dist/                    # Compiled assets (tsup: CJS + ESM + DTS) & Registry

Component Catalog

Atoms (Foundation Primitives)

52 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 (src/molecules/generic/)

Cross-domain widgets, including job-card families for long-running agent work (ResearchReportJobCard, PresentationJobCard, WebSearchJobCard — share layout/state conventions via job-card-shared/), data/table components (DataGrid, DataTableCard, TablePagination), integration cards (GitHubConnectCard, GitHubRepoHealthCard, GoogleSheetsCard, GoogleSheetsConnectCard), and general dashboard primitives:

• StatsGrid / KPIStatsCard: Data visualization with trends & icons.
• EmptyState, LoadingOverlay: Placeholder/loading states.
• FilterBar, FileUpload, TagCloud, FormCard, DynamicFormCard, EditableField: Input & filtering patterns.
• ChecklistCard, ApprovalCard, ConfirmationCard, PollCard: Decision/workflow patterns.
• CampaignBriefCard, ChannelPlanCard, BudgetAllocCard, CalendarEventCard: Campaign-planning widgets.

Creator Discovery (src/molecules/creator-discovery/)

• CreatorGridCard: Detailed discovery card with banner and metrics.
• AudienceMetricCard / AudienceDemographicsCard: Progress-based demographics.
• BrandAffinityGroup: Visual recently associated brand logos.
• ContentPreviewGallery: Video/Image thumbnail grids.
• CreatorProfileSummary, CreatorSearchBox, CreatorWidget, CreatorActionHeader: Search & profile patterns.
• PlatformIconGroup, GrowthChartCard, TopPostsGrid: Reach & performance summaries.
• SearchSpecCard, MCQCard, CampaignSeedCard, CampaignConceptCard: Agent-driven intake/spec patterns.

Usage

Registry-Driven Rendering

npm run build runs generate-metadata automatically (tsup.config.ts's onSuccess hook), producing dist/registry.json — component metadata + schemas so agents (the server's ui_generator/widget_builder agents) know what they can render. Never hand-edit dist/registry.json — it's derived output; if a new molecule isn't showing up in agent suggestions, rebuild and confirm the registry picked it up. PXEngineRenderer (exported from the package root) maps a schema's type field to a React component via a discriminated-union registry — adding a new molecule requires registering its type string there or it silently won't render.

import { PXEngineRenderer } from "pxengine";

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:

import { CreatorGridCard } from "pxengine";

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

Design System

Components are theme-agnostic by design — they read CSS custom properties (--px-*, plus the host's own tokens) at render time rather than hardcoding a palette, so cn() (re-exported from pxengine, not clsx, for consumers) composes host classes on top of component defaults. A few atoms (e.g. AvatarAtom) fall back to internal indigo/purple/slate defaults (var(--px-bg-color, var(--purple50))) when a host doesn't supply theme vars — that fallback palette is NOT what most consumers actually see. pxengine-builder, the primary consumer, supplies a dark, gold-accented theme (--gold: #C0AE82, surface.chat #0A0A0A → surface.elevated #1E1E1F, see its README) via globals.css, and every pxengine component renders on that theme with zero component-level changes.

• Border Radius: Generous rounded-3xl and rounded-[32px] for major components.
• Backdrop: Uses backdrop-blur-md for overlay/glass surfaces where the host theme calls for it.
• Shadows: Subtle, layered soft shadows for depth.

Tech Stack

• Framework: React (peer dep ^18.0.0 || ^19.0.0; primary consumer runs 19) — built with tsup (CJS + ESM + .d.ts), not Vite
• Styling: Tailwind CSS + class-variance-authority + tailwind-preset.js (shared preset re-exported for consumers)
• Primitives: Radix UI (via shadcn/ui)
• Animations: Framer Motion (peer dep, external — not bundled)
• Icons: Lucide React (bundled into the build via tsup's noExternal, along with date-fns, @date-fns/tz, react-day-picker)
• Charts: Highcharts + highcharts-react-official, and Recharts — all peer deps, external
• Data/validation: Zod