Archie UI Components

A comprehensive React component library built with TypeScript, featuring 287+ custom icons and production-ready components.

✨ Features

• 🎨 287+ Custom Icons - Beautiful SVG icons with customizable size and color
• 🧩 Production-Ready Components - Button, Input, Checkbox, Toast, Tabs, and more
• 💬 Chat Components - MessageBubble, ChatInput, MarkdownRenderer for AI/chat UIs
• 🎯 TypeScript First - Fully typed components with excellent IntelliSense
• 🎨 Modern Design System - Built with Tailwind CSS v4 and CSS variables
• ♿ Accessible - Built with Radix UI primitives following WCAG guidelines
• 🎭 Animated - Smooth animations powered by Framer Motion
• 📦 Tree-Shakeable - Optimized bundle size with separate entry points
• 🔧 Class Variance Authority - Powerful variant management system

📦 Installation

npm install @archieai/ui
# or
pnpm add @archieai/ui
# or
yarn add @archieai/ui

Required Peer Dependencies

npm install react react-dom framer-motion sonner @radix-ui/react-tabs @radix-ui/react-tooltip

Or if using pnpm:

pnpm add react react-dom framer-motion sonner @radix-ui/react-tabs @radix-ui/react-tooltip

🚀 Quick Start

1. Import Styles

Add the component styles to your app's entry point (main.tsx, App.tsx, or _app.tsx):

import '@archieai/ui/styles';

2. Start Using Components

import { Button, Input, MessageBubble, MarkdownRenderer } from '@archieai/ui';
import { Star, Send } from '@archieai/ui/icons';

function App() {
  return (
    <div>
      <Input placeholder="Enter your message" />

      <Button variant="primary" startIcon={<Star size={16} />}>
        Save
      </Button>

      <MessageBubble variant="assistant">
        <MarkdownRenderer content="Hello! How can I **help** you today?" />
      </MessageBubble>
    </div>
  );
}

📚 Available Components

Atoms

Avatar

User avatar component with text initials or image support.

import { Avatar } from '@archieai/ui';

// Text avatar with initials
<Avatar type="text" initials="JD" />

// Image avatar
<Avatar type="image" src="/path/to/image.jpg" alt="John Doe" />

// Different shapes
<Avatar type="text" initials="AR" shape="circular" />
<Avatar type="text" initials="AR" shape="square" />

// Different sizes
<Avatar type="text" initials="AR" size="small" />
<Avatar type="text" initials="AR" size="big" />

// With fallback when image fails to load
<Avatar
  type="image"
  src="/invalid-image.jpg"
  fallbackInitials="JD"
/>

Props:

• type: 'text' | 'image'
• shape: 'circular' | 'square'
• size: 'small' | 'big'
• initials: String for text avatar
• src: Image URL for image avatar
• alt: Alt text for accessibility
• fallbackInitials: Initials to show when image fails

StatusIndicator

Visual status indicator dot with optional animation.

import { StatusIndicator } from '@archieai/ui';

<StatusIndicator variant="success" />
<StatusIndicator variant="warning" />
<StatusIndicator variant="error" />
<StatusIndicator variant="info" />
<StatusIndicator variant="neutral" />

// With animation
<StatusIndicator variant="success" animated />

// Different sizes
<StatusIndicator variant="info" size="small" />
<StatusIndicator variant="info" size="medium" />
<StatusIndicator variant="info" size="large" />

Props:

• variant: 'success' | 'warning' | 'error' | 'info' | 'neutral'
• size: 'small' | 'medium' | 'large'
• animated: Boolean for pulsing animation

Typography

Text components with semantic HTML.

import { Typography } from '@archieai/ui';

<Typography variant="h1">Heading 1</Typography>
<Typography variant="h2">Heading 2</Typography>
<Typography variant="body1">Body text</Typography>
<Typography variant="caption">Caption text</Typography>

Logos

Archie brand logos with customizable colors and animations.

import { LogoA, SignatureA, FullLogo } from '@archieai/ui';

// Logo A (icon mark)
<LogoA size={32} colorVariant="lightTeal" />
<LogoA size={32} colorVariant="darkTeal" />

// Animated Signature
<SignatureA size={40} colorVariant="orange" animated animationDuration={2} />

// Full Logo
<FullLogo width={120} />

Icons (287+)

All icons are available as React components. Import from the dedicated /icons entry point for better tree-shaking:

// Recommended: Import from /icons entry point
import {
  Home, Settings, User, Mail, Star, Check, X,
  Plus, Minus, Search, Filter, Edit, Trash,
  ArrowLeft, ArrowRight, ChevronDown, ChevronUp,
  Heart, Bell, Calendar, Clock, Download, Upload,
  Clipboard, ThumbsUp, ThumbsDown, FileText
} from '@archieai/ui/icons';

// All icons support size and color props
<Home size={24} color="#8C92AF" />
<Settings size={20} color="var(--color-blue-800)" />
<Star size={16} />

Icon Props:

• size: Number (default: 24)
• color: String (CSS color value)
• className: String for additional styling

Molecules

Button

Flexible button component with multiple variants, sizes, and icon support.

import { Button } from '@archieai/ui';
import { Star } from '@archieai/ui/icons';

// Basic button
<Button onClick={handleClick}>Click me</Button>

// With variants
<Button variant="primary" tone="brand" size="large">Primary</Button>
<Button variant="secondary" tone="neutral">Secondary</Button>
<Button variant="tertiary">Tertiary</Button>

// With icons
<Button startIcon={<Star size={16} />}>Favorite</Button>
<Button endIcon={<Star size={16} />}>Continue</Button>

// Disabled state
<Button disabled>Disabled</Button>

Props:

• variant: 'primary' | 'secondary' | 'tertiary'
• tone: 'brand' | 'neutral'
• size: 'small' | 'medium' | 'large'
• startIcon: React node for leading icon
• endIcon: React node for trailing icon
• All standard button HTML attributes

Input

Text input component with icon support and validation states.

import { Input } from '@archieai/ui';
import { Search } from '@archieai/ui/icons';

<Input placeholder="Search..." />
<Input type="email" placeholder="Email" />
<Input
  startIcon={<Search size={16} />}
  placeholder="Search..."
/>

Props:

• startIcon: React node for leading icon
• endIcon: React node for trailing icon
• All standard input HTML attributes

Checkbox

Styled checkbox component with label support.

import { Checkbox } from '@archieai/ui';

<Checkbox id="terms" label="I agree to the terms" />
<Checkbox id="newsletter" label="Subscribe to newsletter" defaultChecked />

Props:

• label: String or React node for checkbox label
• id: Required for accessibility
• All standard checkbox HTML attributes

MessageBubble

Chat message bubble component for user, assistant, and system messages.

import { MessageBubble, MarkdownRenderer } from '@archieai/ui';

// User message
<MessageBubble variant="user">
  What is the weather today?
</MessageBubble>

// Assistant message with avatar
<MessageBubble variant="assistant">
  <MarkdownRenderer content="The weather is **sunny** with a high of 72°F." />
</MessageBubble>

// Initial prompt (centered)
<MessageBubble variant="user" isInitialPrompt>
  Help me write a poem about nature
</MessageBubble>

// System message
<MessageBubble variant="system">
  Connected to the assistant
</MessageBubble>

// Loading state
<MessageBubble variant="loader" />

// With action handlers
<MessageBubble
  variant="assistant"
  onCopy={() => console.log('Copied')}
  onHelpful={() => console.log('Helpful')}
  onUnhelpful={() => console.log('Not helpful')}
>
  Here's my response...
</MessageBubble>

// Sticky mode (no action controls, adds shadow)
<MessageBubble variant="assistant" isSticky>
  Pinned message
</MessageBubble>

Props:

• variant: 'user' | 'assistant' | 'system' | 'loader'
• heading: Optional heading text (assistant only)
• isLoading: Shows loading animation
• showAvatar: Show Archie logo (defaults to true for assistant)
• showTimestamp: Show timestamp (default: false)
• timestamp: Date or string for timestamp
• isSticky: Sticky mode with shadow
• isInitialPrompt: Center align (user variant only)
• alignment: 'left' | 'center' | 'right'
• onCopy, onEdit, onHelpful, onUnhelpful: Action callbacks

ChatFile

File attachment component with upload progress states.

import { ChatFile, FileStatus } from '@archieai/ui';

// Completed file
<ChatFile filename="document.pdf" status={FileStatus.Done} />

// Uploading with progress
<ChatFile
  filename="report.xlsx"
  status={FileStatus.Uploading}
  progress={45}
/>

// Processing
<ChatFile filename="image.png" status={FileStatus.Processing} progress={80} />

// Error state
<ChatFile filename="failed.doc" status={FileStatus.Error} />

// With delete handler
<ChatFile
  filename="attachment.pdf"
  status={FileStatus.Done}
  onDelete={() => console.log('Delete file')}
/>

Props:

• filename: File name to display
• status: FileStatus.Uploading | FileStatus.Processing | FileStatus.Done | FileStatus.Error
• progress: Number (0-100) for upload progress
• onDelete: Callback when delete is clicked

Dropdown

Dropdown menu component with animation support.

import {
  Dropdown,
  DropdownTrigger,
  DropdownContent,
  DropdownItem,
} from '@archieai/ui';
import { Button } from '@archieai/ui';

<Dropdown>
  <DropdownTrigger>
    <Button>Open Menu</Button>
  </DropdownTrigger>
  <DropdownContent align="start">
    <DropdownItem onClick={() => console.log('Edit')}>Edit</DropdownItem>
    <DropdownItem onClick={() => console.log('Duplicate')}>
      Duplicate
    </DropdownItem>
    <DropdownItem variant="destructive" onClick={() => console.log('Delete')}>
      Delete
    </DropdownItem>
  </DropdownContent>
</Dropdown>;

// Controlled dropdown
const [isOpen, setIsOpen] = useState(false);
<Dropdown open={isOpen} onOpenChange={setIsOpen}>
  ...
</Dropdown>;

Props:

• Dropdown: defaultOpen, open, onOpenChange
• DropdownContent: align ('start' | 'end' | 'center'), attached
• DropdownItem: active, variant ('default' | 'destructive'), closeOnSelect

ProgressBar

Progress indicator component with labels and variants.

import { ProgressBar } from '@archieai/ui';

// Basic progress
<ProgressBar value={60} />

// With label and value display
<ProgressBar value={75} max={100} label="Uploading..." showValueLabel />

// Different variants
<ProgressBar value={100} variant="success" />
<ProgressBar value={30} variant="warning" />
<ProgressBar value={15} variant="error" />

// Different sizes
<ProgressBar value={50} size="small" />
<ProgressBar value={50} size="medium" />
<ProgressBar value={50} size="large" />

// Custom value formatter
<ProgressBar
  value={750}
  max={1000}
  showValueLabel
  valueFormatter={(value, max) => `${value}/${max} items`}
/>

Props:

• value: Current progress value
• max: Maximum value (default: 100)
• variant: 'default' | 'success' | 'error' | 'warning'
• size: 'small' | 'medium' | 'large'
• showValueLabel: Show percentage/value label
• label: Custom label text
• valueFormatter: Custom value formatting function

StatusMessage

Status message component with icon and indicator.

import { StatusMessage } from '@archieai/ui';

<StatusMessage status="success" message="Operation completed successfully" />
<StatusMessage status="warning" message="Please review your changes" />
<StatusMessage status="error" message="An error occurred" />
<StatusMessage status="info" message="Processing your request" />
<StatusMessage status="loading" message="Loading data..." />
<StatusMessage status="neutral" message="No updates available" />

Props:

• status: 'success' | 'warning' | 'error' | 'info' | 'neutral' | 'loading'
• message: Message text to display

SidebarItem

Navigation sidebar item component.

import { SidebarItem } from '@archieai/ui';
import { Home, Settings, User } from '@archieai/ui/icons';

// Basic item
<SidebarItem icon={<Home size={20} />} label="Home" onClick={() => navigate('/')} />

// Active state
<SidebarItem icon={<Settings size={20} />} label="Settings" isActive />

// Brand variant
<SidebarItem icon={<User size={20} />} label="Profile" variant="brand" />

// Collapsed mode (icon only)
<SidebarItem icon={<Home size={20} />} label="Home" isCollapsed />

Props:

• icon: React node for the icon
• label: Label text
• isCollapsed: Collapsed mode (icon only)
• isActive: Active/selected state
• variant: 'default' | 'brand'
• onClick: Click handler

Timestamp

Formatted timestamp component with relative time support.

import { Timestamp } from '@archieai/ui';

// Relative time (default)
<Timestamp date={new Date()} /> // "just now"
<Timestamp date={Date.now() - 3600000} /> // "1 hour ago"

// Different formats
<Timestamp date={new Date()} format="relative" /> // "just now"
<Timestamp date={new Date()} format="short" /> // "Nov 26, 2024"
<Timestamp date={new Date()} format="long" /> // "November 26, 2024"
<Timestamp date={new Date()} format="time" /> // "3:45 PM"
<Timestamp date={new Date()} format="datetime" /> // "Nov 26, 2024, 3:45 PM"

// With icon
<Timestamp date={new Date()} showIcon />

// Different sizes and variants
<Timestamp date={new Date()} size="small" variant="muted" />
<Timestamp date={new Date()} size="large" variant="primary" />

Props:

• date: Date object, timestamp number, or ISO string
• format: 'relative' | 'short' | 'long' | 'time' | 'datetime'
• size: 'small' | 'medium' | 'large'
• variant: 'default' | 'primary' | 'muted'
• showIcon: Show clock icon
• locale: Locale string (default: 'en-US')

Toast

Toast notification system with multiple variants.

import { showToast, ToastContainer } from '@archieai/ui';

// Add ToastContainer once at your app root
<ToastContainer />;

// Show notifications
showToast.success('Success!', 'Your changes have been saved.');
showToast.error('Error!', 'Something went wrong.');
showToast.info('Info', 'Please check your email.');
showToast.warning('Warning', 'Are you sure?');

// With custom duration
showToast.success('Success!', 'Saved', { duration: 5000 });

Tooltip

Hover tooltips with customizable positioning.

import { Tooltip } from '@archieai/ui';
import { Info } from '@archieai/ui/icons';

<Tooltip content="This is a tooltip">
  <button>Hover me</button>
</Tooltip>

<Tooltip content="Help information" side="right">
  <Info size={16} />
</Tooltip>

Props:

• content: String or React node for tooltip content
• side: 'top' | 'right' | 'bottom' | 'left'
• delayDuration: Number (milliseconds)

Tabs

Tab navigation component with badge support.

import { Tabs } from '@archieai/ui';

const tabs = [
  { id: 'overview', label: 'Overview' },
  { id: 'analytics', label: 'Analytics', badge: '12' },
  { id: 'settings', label: 'Settings' },
];

<Tabs
  tabs={tabs}
  defaultValue="overview"
  onValueChange={(value) => console.log(value)}
>
  <Tabs.Content value="overview">Overview content</Tabs.Content>
  <Tabs.Content value="analytics">Analytics content</Tabs.Content>
  <Tabs.Content value="settings">Settings content</Tabs.Content>
</Tabs>;

Tag

Label and badge component with avatar support.

import { Tag } from '@archieai/ui';

<Tag>Default Tag</Tag>
<Tag variant="success">Success</Tag>
<Tag variant="error">Error</Tag>
<Tag onRemove={() => console.log('removed')}>Removable</Tag>

Breadcrumbs

Navigation breadcrumb component.

import { Breadcrumbs } from '@archieai/ui';
import { Home, Settings } from '@archieai/ui/icons';

const items = [
  {
    label: 'Home',
    href: '/',
    icon: <Home size={16} />,
    onClick: () => navigate('/'),
  },
  {
    label: 'Settings',
    href: '/settings',
    icon: <Settings size={16} />,
  },
  { label: 'Profile' },
];

<Breadcrumbs items={items} />;

LoadingSpinner

Loading indicator component.

import { LoadingSpinner } from '@archieai/ui';

<LoadingSpinner />
<LoadingSpinner size="small" />
<LoadingSpinner size="large" />

Organisms

ChatInput

Rich chat input with file upload support.

import { ChatInput } from '@archieai/ui';

<ChatInput
  placeholder="Type a message..."
  onSend={(message, files) => {
    console.log('Message:', message);
    console.log('Files:', files);
  }}
  onFileSelect={(files) => console.log('Files selected:', files)}
/>;

Props:

• placeholder: Input placeholder text
• onSend: Callback with message and files
• onFileSelect: Callback when files are selected
• All standard textarea HTML attributes

ConversationHeader

Header component for chat conversations with breadcrumbs, tags, and collaborators.

import { ConversationHeader } from '@archieai/ui';
import { Home, MessageSquare } from '@archieai/ui/icons';

const breadcrumbs = [
  { label: 'Conversations', icon: <Home size={16} />, onClick: () => {} },
  { label: 'Project Discussion', icon: <MessageSquare size={16} /> },
];

const tags = [
  { id: '1', label: 'Design' },
  { id: '2', label: 'Urgent' },
];

const collaborators = [
  { id: '1', name: 'John Doe', src: '/avatar1.jpg' },
  { id: '2', name: 'Jane Smith', src: '/avatar2.jpg' },
];

<ConversationHeader
  breadcrumbs={breadcrumbs}
  tags={tags}
  collaborators={collaborators}
  onAddTag={() => console.log('Add tag')}
  onAddCollaborator={() => console.log('Add collaborator')}
  tagsOverflowCount={3}
/>;

Props:

• breadcrumbs: Array of breadcrumb items
• tags: Array of tag objects with id and label
• collaborators: Array of collaborator objects with id, name, and optional src
• onAddTag: Callback for adding a tag
• onAddCollaborator: Callback for adding a collaborator
• tagsOverflowCount: Number showing additional hidden tags

Renderers

MarkdownRenderer

Markdown content renderer with support for headings, lists, code blocks, tables, math (LaTeX), and more.

import { MarkdownRenderer } from '@archieai/ui';

// Basic markdown
<MarkdownRenderer content="# Hello World\n\nThis is **bold** and *italic* text." />

// With code blocks
<MarkdownRenderer
  content={`
## Code Example

\`\`\`javascript
const greeting = 'Hello, World!';
console.log(greeting);
\`\`\`

Inline \`code\` also works!
  `}
/>

// With tables
<MarkdownRenderer
  content={`
| Feature | Status |
|---------|--------|
| Tables | ✅ |
| Lists | ✅ |
| Code | ✅ |
  `}
/>

// With math (LaTeX)
<MarkdownRenderer
  content={`
The quadratic formula: $x = \\frac{-b \\pm \\sqrt{b^2-4ac}}{2a}$

Block math:
$$
\\int_0^\\infty e^{-x^2} dx = \\frac{\\sqrt{\\pi}}{2}
$$
  `}
/>

// Custom renderers
<MarkdownRenderer
  content="Check `this code` and [this link](https://example.com)"
  renderCodeBlock={(code, language) => (
    <SyntaxHighlighter language={language}>{code}</SyntaxHighlighter>
  )}
  renderLink={(href, text) => (
    <CustomLink href={href}>{text}</CustomLink>
  )}
/>

// Size and variant
<MarkdownRenderer content="# Title" size="small" variant="muted" />

Props:

• content: Markdown string to render
• size: 'small' | 'medium' | 'large'
• variant: 'default' | 'muted' | 'primary'
• renderCodeBlock: Custom code block renderer
• renderInlineCode: Custom inline code renderer
• renderMathBlock: Custom math block renderer (LaTeX)
• renderInlineMath: Custom inline math renderer
• renderLink: Custom link renderer

Supported Markdown Features:

• Headings (H1-H6)
• Bold, italic, strikethrough
• Links
• Inline code and code blocks with language support
• Ordered and unordered lists
• Blockquotes
• Tables with alignment
• Horizontal rules
• Math/LaTeX (inline with $...$, block with $$...$$)

🎨 Theming

The library uses CSS custom properties for theming. You can customize colors by overriding these variables:

:root {
  /* Primary Colors */
  --color-white: #ffffff;
  --color-blue-1000: #022e40;
  --color-blue-800: #15b1cd;
  --color-blue-400: #6aeafd;
  --color-blue-200: #d6f4ff;

  /* Orange Colors */
  --color-orange-1000: #e15713;
  --color-orange-800: #ff6f00;
  --color-orange-200: #fff2e2;

  /* Neutral Colors */
  --color-gray-1000: #000626;
  --color-gray-800: #595f7a;
  --color-gray-600: #8c92af;
  --color-gray-200: #e5e7f0;
  --color-gray-100: #f5f6fa;
  --color-gray-50: #fafafc;

  /* System Colors */
  --color-red-1000: #fb6060;
  --color-red-200: #ffecec;
  --color-green-1000: #71d481;
  --color-green-200: #e2f7e5;
  --color-amber-1000: #8f6c1a;
}

📘 TypeScript Support

All components are fully typed with TypeScript:

import type {
  ButtonProps,
  InputProps,
  CheckboxProps,
  ToastProps,
  TabsProps,
  BreadcrumbsProps,
  MessageBubbleProps,
  ChatFileProps,
  DropdownProps,
  ProgressBarProps,
  StatusMessageProps,
  SidebarItemProps,
  TimestampProps,
  AvatarProps,
  StatusIndicatorProps,
  ConversationHeaderProps,
  MarkdownRendererProps,
} from '@archieai/ui';

// Use types in your components
const MyButton: React.FC<ButtonProps> = (props) => {
  return <Button {...props} />;
};

🌐 Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

🛠️ Tech Stack

• React 18.3+ - UI library
• TypeScript - Type safety
• Tailwind CSS v4 - Utility-first styling
• Framer Motion - Animations
• Radix UI - Accessible primitives
• KaTeX - Math/LaTeX rendering
• Class Variance Authority - Variant management
• Vite - Build tool

📦 Bundle Size

The library is optimized for minimal bundle size:

• Separate entry points for icons and styles
• Tree-shakeable - only import what you use
• CSS: ~50 KB (minified)
• JS: ~49 KB (minified, gzipped)

// Import only what you need
import { Button, Input, MessageBubble } from '@archieai/ui'; // Main components
import { Home, Star } from '@archieai/ui/icons'; // Icons separately
import '@archieai/ui/styles'; // Styles

📝 Development

Running Locally

# Install dependencies
pnpm install

# Start development server
pnpm dev

# Run tests
pnpm test

# Build library
pnpm build:lib

# Run Storybook
pnpm storybook

Building

# Build the library for production
pnpm build:lib

# This generates:
# - dist/index.js (ESM)
# - dist/index.cjs (CommonJS)
# - dist/index.d.ts (TypeScript declarations)
# - dist/icons.js (Icons ESM)
# - dist/icons.cjs (Icons CommonJS)
# - dist/styles.js (Styles entry point)
# - dist/ui.css (Compiled CSS)

📄 License

MIT License - See LICENSE file for details.

🤝 Contributing

This package is maintained by the Archie AI team. For internal contributors:

1. Follow the component creation standards in .cursor/rules/component-creation.mdc
2. Ensure all components have:
   • Main component file (.tsx)
   • Styles file (.styles.ts)
   • Stories file (.stories.tsx)
   • Test file (.test.tsx)
3. Run tests before committing
4. Update CHANGELOG.md for significant changes

📞 Support

For issues and questions:

• Internal team: Contact the Archie AI development team
• GitHub Issues: https://github.com/heyarchie-ai/Archie-UI/issues

📚 Additional Resources

• Changelog - Version history and updates
• Figma Design System - Design specifications

Made with ❤️ by the Archie AI Team