DamkarAI Components

A comprehensive React component library for DamkarAI - an AI-powered text and code assistant. This library provides a complete set of components, hooks, and utilities to build modern AI interfaces with beautiful design and smooth animations.

🚀 Installation

npm install @damkarai/components
# or
yarn add @damkarai/components
# or
pnpm add @damkarai/components

📦 Peer Dependencies

Make sure you have the following peer dependencies installed:

npm install react@>=18.0.0 react-dom@>=18.0.0

🎯 Quick Start

import { DamkarMascot, DamkarButton, DamkarLoader } from '@damkarai/components';
import '@damkarai/components/dist/style.css';

function App() {
  return (
    <div>
      <DamkarMascot 
        variant="head" 
        service="llm" 
        state="processing" 
        size="lg" 
        animated={true} 
      />

      <DamkarButton 
        variant="primary" 
        onClick={() => console.log('Clicked!')}
      >
        Start Processing
      </DamkarButton>

      <DamkarLoader 
        service="grammar" 
        message="Checking your text..." 
        showMascot={true} 
      />
    </div>
  );
}

🧩 Core Components

DamkarMascot

The heart of the library - an animated AI mascot that represents different services and states.

<DamkarMascot 
  variant="full" | "half" | "head" | "icon"
  service="llm" | "grammar" | "code" | "text" | "idle"
  state="idle" | "processing" | "success" | "error" | "thinking"
  size="xs" | "sm" | "md" | "lg" | "xl"
  animated={true}
  message="Optional status message"
  onClick={() => {}}
/>

DamkarButton

Consistent button component with multiple variants and loading states.

<DamkarButton
  variant="primary" | "secondary" | "accent" | "warning" | "error" | "success" | "neutral"
  size="xs" | "sm" | "md" | "lg" | "xl"
  loading={false}
  disabled={false}
  icon={<SendIcon />}
  iconPosition="left" | "right"
  fullWidth={false}
  onClick={() => {}}
>
  Button Text
</DamkarButton>

DamkarLoader

Loading states with multiple variants including mascot animations.

<DamkarLoader
  service="llm" | "grammar" | "code" | "text"
  variant="spinner" | "dots" | "mascot" | "skeleton"
  message="Loading message..."
  showMascot={true}
  size="sm" | "md" | "lg"
  estimatedTime={30}
/>

DamkarStatusCard

Status notifications with mascot integration.

<DamkarStatusCard
  status="success" | "error" | "warning" | "info"
  title="Status Title"
  description="Detailed description"
  showMascot={true}
  dismissible={true}
  onDismiss={() => {}}
  action={<DamkarButton>Action</DamkarButton>}
/>

DamkarInput

Form inputs with validation and character counting.

<DamkarInput
  type="text" | "email" | "password" | "textarea"
  label="Input Label"
  placeholder="Enter text..."
  value={value}
  onChange={setValue}
  error="Error message"
  required={true}
  maxLength={500}
  rows={4} // for textarea
/>

🎨 Theming

Using the Theme Hook

import { useDamkarTheme } from '@damkarai/components';

function ThemeToggle() {
  const { theme, toggleTheme, setTheme, isDark } = useDamkarTheme();

  return (
    <button onClick={toggleTheme}>
      Current theme: {theme}
    </button>
  );
}

CSS Variables

The library uses CSS variables for theming. You can customize the design system:

:root {
  --damkar-primary: #0066FF;
  --damkar-secondary: #6366F1;
  --damkar-accent: #10B981;
  --damkar-warning: #F59E0B;
  --damkar-error: #EF4444;
  --damkar-success: #10B981;

  /* Spacing */
  --damkar-space-xs: 4px;
  --damkar-space-sm: 8px;
  --damkar-space-md: 16px;
  --damkar-space-lg: 24px;
  --damkar-space-xl: 32px;

  /* Typography */
  --damkar-font-family: 'Inter', sans-serif;
  --damkar-font-mono: 'JetBrains Mono', monospace;
}

Dark Mode

Dark mode is automatically supported through CSS variables and the data-theme attribute:

<div data-theme="dark">
  <DamkarMascot variant="head" />
</div>

🔧 Advanced Usage

TypeScript Support

The library is built with TypeScript and provides comprehensive type definitions:

import type { 
  DamkarMascotProps, 
  DamkarService, 
  DamkarState 
} from '@damkarai/components';

const mascotProps: DamkarMascotProps = {
  variant: 'head',
  service: 'llm',
  state: 'processing',
  size: 'lg'
};

Custom Styling

Use the cn utility for conditional classes:

import { cn } from '@damkarai/components';

<DamkarButton 
  className={cn(
    'custom-button',
    isActive && 'active-state',
    { 'special-variant': isSpecial }
  )}
>
  Custom Button
</DamkarButton>

Animation Control

Disable animations for reduced motion preference:

<DamkarMascot 
  animated={!window.matchMedia('(prefers-reduced-motion: reduce)').matches}
/>

🎭 Animation Features

Mascot Animations

Idle: Subtle floating and glow pulse
Processing: Service-specific animations (code syntax highlighting, text flowing, etc.)
Success: Celebration with positive feedback
Error: Concerned but helpful expression
Thinking: Contemplative movement

Micro-interactions

Button hover states with mascot acknowledgment
Loading states with typing animations
File upload with mascot "catching" files
Copy/export with handover animations

♿ Accessibility

The library follows accessibility best practices:

ARIA labels and descriptions
Keyboard navigation support
Screen reader compatibility
High contrast mode support
Reduced motion preferences
Focus management

<DamkarButton
  aria-label="Process document with AI"
  aria-describedby="help-text"
>
  Process
</DamkarButton>

📱 Responsive Design

All components are responsive and work across different screen sizes:

<DamkarMascot 
  size={{ mobile: 'sm', tablet: 'md', desktop: 'lg' }}
/>

🧪 Testing

Components include test IDs for easy testing:

<DamkarButton testId="submit-button">
  Submit
</DamkarButton>

// In tests
const button = screen.getByTestId('submit-button');

📚 Storybook Documentation

Explore all components interactively:

npm run storybook

This opens the Storybook interface where you can:

View all components and variants
Test different props interactively
See code examples
Test accessibility features

🔧 Development

Local Development

git clone https://github.com/damkarai/components
cd components
npm install
npm run dev

Building the Library

npm run build

This creates:

dist/index.js - UMD build
dist/index.esm.js - ES modules build
dist/index.d.ts - TypeScript definitions
dist/style.css - Compiled styles

Running Tests

npm test        # Run tests
npm run test:ui # Run tests with UI

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Run tests and ensure they pass
Submit a pull request

🔗 Links

📈 Roadmap

Current Version (1.0.0)

✅ Core mascot component with animations
✅ Essential UI components (Button, Input, Loader, StatusCard)
✅ Theme system with light/dark mode
✅ TypeScript support
✅ Storybook documentation

Upcoming Features (1.1.0)

🔄 Chat interface component
🔄 Grammar checking component
🔄 Code assistant component
🔄 File upload component
🔄 Voice interface components

Future Versions

🔜 Advanced AI integrations
🔜 More animation variants
🔜 Additional theme options
🔜 Mobile-specific optimizations
🔜 SSR improvements

Built with ❤️ by the DamkarAI Team

Package detail

damkar-ui-components

readme