@archieai/ui 1.0.0 → 1.1.0

package/README.md

@@ -3,19 +3,21 @@
 A comprehensive React component library built with TypeScript, featuring 287+ custom icons and production-ready components.
 
 [![npm version](https://img.shields.io/npm/v/@archieai/ui.svg)](https://www.npmjs.com/package/@archieai/ui)
-[![License](https://img.shields.io/npm/l/@archieai/ui.svg)](https://github.com/archieai/archie-ui)
+[![License](https://img.shields.io/npm/l/@archieai/ui.svg)](https://github.com/heyarchie-ai/Archie-UI)
 
-## Features
+## ✨ Features
 
-✨ **287+ Custom Icons** - Beautiful SVG icons with customizable size and color
-🎨 **Modern Design System** - Built with Tailwind CSS and CSS variables
-♿ **Accessible** - Built with Radix UI primitives
-🎭 **Animated** - Smooth animations with Framer Motion
-📦 **Tree-shakeable** - Only import what you need
-🔧 **TypeScript** - Fully typed components
-🚀 **Production Ready** - Optimized and tested
+- 🎨 **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
+## 📦 Installation
 
 ```bash
 npm install @archieai/ui
@@ -25,163 +27,965 @@ pnpm add @archieai/ui
 yarn add @archieai/ui
 ```
 
-### Peer Dependencies
-
-Install the required peer dependencies:
+### Required Peer Dependencies
 
 ```bash
 npm install react react-dom framer-motion sonner @radix-ui/react-tabs @radix-ui/react-tooltip
 ```
 
-## Quick Start
+Or if using pnpm:
+
+```bash
+pnpm add react react-dom framer-motion sonner @radix-ui/react-tabs @radix-ui/react-tooltip
+```
+
+## 🚀 Quick Start
 
 ### 1. Import Styles
 
-In your main file (`main.tsx`, `App.tsx`, or `_app.tsx`):
+Add the component styles to your app's entry point (`main.tsx`, `App.tsx`, or `_app.tsx`):
 
 ```tsx
-// Import the component styles
 import '@archieai/ui/styles';
 ```
 
-### 2. Use Components
+### 2. Start Using Components
 
 ```tsx
-import { Button, Input, Toast, showToast, ToastContainer } from '@archieai/ui';
+import { Button, Input, MessageBubble, MarkdownRenderer } from '@archieai/ui';
+import { Star, Send } from '@archieai/ui/icons';
 
 function App() {
   return (
     <div>
-      <Input placeholder="Enter your name" />
+      <Input placeholder="Enter your message" />
 
-      <Button
-        onClick={() => showToast.success('Hello!', 'Welcome to Archie UI')}
-      >
-        Click Me
+      <Button variant="primary" startIcon={<Star size={16} />}>
+        Save
       </Button>
 
-      <ToastContainer />
+      <MessageBubble variant="assistant">
+        <MarkdownRenderer content="Hello! How can I **help** you today?" />
+      </MessageBubble>
     </div>
   );
 }
 ```
 
-## Available Components
+## 📚 Available Components
+
+### Atoms
+
+#### Avatar
 
-### UI Components
+User avatar component with text initials or image support.
 
-- **Button** - Primary, secondary, tertiary variants with icons
-- **Input** - Text inputs with icons and validation states
-- **Checkbox** - Styled checkboxes with labels
-- **Breadcrumbs** - Navigation breadcrumbs
-- **Tabs** - Tab navigation with badges
-- **Tag** - Labels and badges with avatars
-- **Toast** - Toast notifications with actions
-- **Tooltip** - Hover tooltips
-- **ChatInput** - Rich chat input with file uploads
-- **Navbar** - Navigation bar
-- **LoadingSpinner** - Loading indicators
+```tsx
+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"
+/>
+```
 
-### Icons (287+)
+**Props:**
 
-All icons are available as React components. Import from the dedicated icons entry for better tree-shaking:
+- `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.
 
 ```tsx
-// Recommended: Import from /icons for better bundle splitting
-import { Home, Settings, User, Mail, Star } from '@archieai/ui/icons';
+import { StatusIndicator } from '@archieai/ui';
 
-// Also works: Import from main entry
-import { Plus, X, Check, ArrowUp } from '@archieai/ui';
+<StatusIndicator variant="success" />
+<StatusIndicator variant="warning" />
+<StatusIndicator variant="error" />
+<StatusIndicator variant="info" />
+<StatusIndicator variant="neutral" />
 
-function MyComponent() {
-  return <Home size={24} color="#8C92AF" />;
-}
+// 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.
+
+```tsx
+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.
+
+```tsx
+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} />
 ```
 
-## Documentation
+#### Icons (287+)
 
-- [Quick Start Guide](./QUICK_START.md)
-- [Comprehensive Examples](./USAGE_EXAMPLE.md)
-- [Changelog](./CHANGELOG.md)
+All icons are available as React components. Import from the dedicated `/icons` entry point for better tree-shaking:
+
+```tsx
+// 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
+
+---
 
-## Component Examples
+### Molecules
 
-### Button
+#### Button
+
+Flexible button component with multiple variants, sizes, and icon support.
 
 ```tsx
 import { Button } from '@archieai/ui';
 import { Star } from '@archieai/ui/icons';
 
-<Button onClick={() => console.log('Clicked!')}>Click me</Button>
+// 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.
+
+```tsx
+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:**
 
-<Button variant="secondary" size="small" startIcon={<Star size={16} />}>
-  Favorite
-</Button>
+- `startIcon`: React node for leading icon
+- `endIcon`: React node for trailing icon
+- All standard input HTML attributes
+
+#### Checkbox
+
+Styled checkbox component with label support.
+
+```tsx
+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.
+
+```tsx
+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.
+
+```tsx
+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.
+
+```tsx
+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.
+
+```tsx
+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`}
+/>
 ```
 
-### Toast Notifications
+**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.
+
+```tsx
+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.
+
+```tsx
+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.
+
+```tsx
+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.
 
 ```tsx
 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?');
 
-// Add ToastContainer once in your app
-<ToastContainer />;
+// With custom duration
+showToast.success('Success!', 'Saved', { duration: 5000 });
+```
+
+#### Tooltip
+
+Hover tooltips with customizable positioning.
+
+```tsx
+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.
+
+```tsx
+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.
+
+```tsx
+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
+#### Breadcrumbs
+
+Navigation breadcrumb component.
 
 ```tsx
 import { Breadcrumbs } from '@archieai/ui';
 import { Home, Settings } from '@archieai/ui/icons';
 
 const items = [
-  { label: 'Home', href: '/', icon: <Home size={16} />, onClick: () => {} },
-  { label: 'Settings', href: '/settings', icon: <Settings size={16} /> },
+  {
+    label: 'Home',
+    href: '/',
+    icon: <Home size={16} />,
+    onClick: () => navigate('/'),
+  },
+  {
+    label: 'Settings',
+    href: '/settings',
+    icon: <Settings size={16} />,
+  },
   { label: 'Profile' },
 ];
 
 <Breadcrumbs items={items} />;
 ```
 
-## TypeScript Support
+#### LoadingSpinner
 
-All components are fully typed:
+Loading indicator component.
 
 ```tsx
-import type { ButtonProps, InputProps, ToastProps } from '@archieai/ui';
+import { LoadingSpinner } from '@archieai/ui';
+
+<LoadingSpinner />
+<LoadingSpinner size="small" />
+<LoadingSpinner size="large" />
 ```
 
-## Browser Support
+---
+
+### Organisms
+
+#### ChatInput
+
+Rich chat input with file upload support.
+
+```tsx
+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.
+
+```tsx
+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.
+
+```tsx
+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:
+
+```css
+: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:
+
+```tsx
+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
+## 🛠️ Tech Stack
 
 - **React** 18.3+ - UI library
 - **TypeScript** - Type safety
-- **Tailwind CSS** - Utility-first styling
+- **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)
+
+```tsx
+// 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
+
+```bash
+# Install dependencies
+pnpm install
+
+# Start development server
+pnpm dev
+
+# Run tests
+pnpm test
+
+# Build library
+pnpm build:lib
+
+# Run Storybook
+pnpm storybook
+```
+
+### Building
+
+```bash
+# 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:
 
-## License
+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
 
-UNLICENSED
+## 📞 Support
 
-## Contributing
+For issues and questions:
 
-This is a private package for the Archie team.
+- Internal team: Contact the Archie AI development team
+- GitHub Issues: [https://github.com/heyarchie-ai/Archie-UI/issues](https://github.com/heyarchie-ai/Archie-UI/issues)
 
-## Support
+## 📚 Additional Resources
 
-For issues and questions, please contact the Archie team.
+- [Changelog](./CHANGELOG.md) - Version history and updates
+- [Figma Design System](https://www.figma.com/design/lXoDTTuMaUscHm9sG86eh8/Archie-Design-System) - Design specifications
 
 ---
 
-Made with ❤️ by the Archie Team
+Made with ❤️ by the Archie AI Team