@agentxjs/ui

React component library for building AI agent interfaces.

Features

• 🎨 React components optimized for AI agent UIs
• 📘 TypeScript support with full type definitions
• 🎯 Tailwind CSS design system with AgentX branding
• 📦 Two usage modes: Tailwind Preset (recommended) or Precompiled CSS
• 🌳 Tree-shakeable ESM exports
• 📚 Storybook for component development

Installation

bun add @agentxjs/ui

Usage Modes

You can use this library in two ways:

✅ Mode 1: Tailwind Preset (Recommended)

Best for: Production apps that need optimal performance and customization.

Pros:

• ⚡ Smallest bundle size (only includes classes you use)
• 🎨 Full theme customization
• 🔄 Inherits AgentX design system

Setup:

1. Install Tailwind CSS dependencies:

bun add -D tailwindcss @tailwindcss/postcss postcss postcss-cli

2. Create tailwind.config.js:

import agentxPreset from "@agentxjs/ui/tailwind-preset";

/** @type {import('tailwindcss').Config} */
export default {
  presets: [agentxPreset],
  content: ["./src/**/*.{ts,tsx}", "./node_modules/@agentxjs/ui/dist/**/*.js"],
};

3. Create postcss.config.js:

export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

4. Create src/styles.css:

@import "@agentxjs/ui/globals.css";

5. Build CSS and use components:

import { Button } from "@agentxjs/ui";
import "./styles.css"; // Generated by PostCSS

function App() {
  return <Button>Click me</Button>;
}

Mode 2: Precompiled CSS (Zero Config)

Best for: Quick prototypes, demos, or non-Tailwind projects.

Pros:

• 🚀 Zero configuration
• ⚡ Quick setup

Cons:

• 📦 Larger bundle size (~40KB, includes all UI component classes)

Setup:

import { Button } from "@agentxjs/ui";
import "@agentxjs/ui/dist/agentx-ui.css"; // Precompiled CSS

function App() {
  return <Button>Click me</Button>;
}

Available Components

• Layout: Header, Sidebar, Panel, MainContent, ActivityBar, StatusBar
• Chat: Chat, ChatHeader, MessagePane, InputPane
• Mobile: MobileStudio, MobileMessagePane, MobileInputPane
• Elements: Button, Input, Badge, Avatar, EmptyState, LoadingState
• Typography: MarkdownText, JSONRenderer, DiffViewer
• Containers: AgentList, ToolCard

See Storybook for interactive examples (run from repository root: bun --filter @agentx/dev-storybook dev).

Exports

// Components
import { Button, Input, Chat } from "@agentxjs/ui";

// Tailwind Preset (Mode 1)
import agentxPreset from "@agentxjs/ui/tailwind-preset";

// Styles (Mode 2)
import "@agentxjs/ui/globals.css"; // Base styles + CSS variables
import "@agentxjs/ui/dist/agentx-ui.css"; // Precompiled CSS (zero-config)

Design System

The component library uses a semantic token system:

| Token | Purpose | Default Color | | --------------- | -------------------------- | ------------------ | | Primary | Computational intelligence | Blue (#0284c7) | | Secondary | Generative creativity | Amber (#f59e0b) | | Accent | Interactive highlights | Orange (#f97316) | | Success | Positive feedback | Green (#22c55e) | | Warning | Caution states | Yellow (#eab308) | | Destructive | Error states | Red (#ef4444) |

Theme Support:

• ✅ Dark mode via CSS custom properties
• ✅ All colors map to CSS variables (hsl(var(--primary)))
• ✅ Override in your app's globals.css

Development

Note: This package is part of the AgentX monorepo. Development tools (Storybook) are in the dev/ directory.

# From repository root:
# Install dependencies
bun install

# Run Storybook (port 6006)
bun --filter @agentx/dev-storybook dev

# From packages/ui directory:
# Build the library
bun build

# Type checking
bun typecheck

# Linting
bun lint

Architecture

Package Structure:

• src/components/ - React components (Button, Chat, Studio, etc.)
• src/styles/ - Global styles and CSS variables
• src/utils/ - Utility functions (cn, eventBus)
• tailwind-preset.js - Tailwind configuration preset
• dist/ - Built outputs (ESM + CSS)

Build Outputs:

• dist/index.js - ESM bundle (React components)
• dist/index.d.ts - TypeScript definitions
• dist/globals.css - Base styles + CSS variables
• dist/agentx-ui.css - Precompiled Tailwind CSS (zero-config mode)

Related Packages

• agentxjs - Platform API (createAgentX, defineAgent)
• @agentxjs/types - Message and event type definitions
• @agentxjs/agent - Agent runtime

License

MIT