kaicalls-design

name

kaicalls-design

description

Build KaiCalls-compliant UI components and pages using the KaiCalls design system. Use when creating new dashboard pages, components, forms, tables, cards, badges, or any UI within the KaiCalls admin panel. Ensures dark-first aesthetic, proper color tokens, typography classes, motion standards, and B2B SaaS best practices. Triggers on "build a page", "create a component", "add a dashboard", "design a form", or any frontend work in the adminpanelnew codebase.

Build KaiCalls-compliant UI using the dark-first design system, shadcn/ui components, and B2B SaaS best practices.

Design Philosophy

KaiCalls follows "Minimum Lovable Product" (MLP) principles:

• Zero Support Required: UI so intuitive users never need docs
• Every Click Invokes Emotion: Button clicks should feel satisfying with visual/motion feedback
• Micro-Celebrations: Reward actions with delightful feedback (confetti, checkmarks, sounds)
• Software Teammate: Humanize through conversational copy and helpful empty states
• Dark-First: Premium aesthetic inspired by Linear, Notion, Stripe

CRITICAL: Every interactive element should provide emotional feedback. Users should feel their actions.

IMPORTANT: Keep feedback subtle and gentle. No harsh flashing, strobing, or high-contrast animations that strain eyes. Our users include older professionals who spend long hours on screen.

Quick Reference

Core Colors (CSS Variables)

/* Backgrounds */
--background: #12121A      /* Main background */
--card: #181B23            /* Card surfaces */
--secondary: #23263B       /* Secondary surfaces, inputs */
--surface-elevated: #2A2D3E

/* Brand */
--kai-blue: #5C8CFF        /* Primary brand */
--kai-purple: #C68BF8      /* Accent */
--kai-btn-primary: #3575F6 /* Primary button */

/* Text */
--foreground: #F7F7FA      /* Primary text */
--muted-foreground: #A7A9BE /* Secondary text */
--kai-text-placeholder: #6B6D76

/* Status */
--kai-success-text: #34D399
--kai-error-text: #FF4B4B
--kai-warning-text: #FFC04B
--kai-info-text: #5C8CFF

Tailwind Classes

Use kai-* prefix for brand colors:

// Backgrounds
className="bg-background"      // Main page
className="bg-card"            // Cards
className="bg-secondary"       // Inputs, secondary surfaces

// Text
className="text-foreground"    // Primary text (white)
className="text-muted-foreground" // Secondary text
className="text-kai-blue"      // Brand blue
className="text-kai-purple"    // Accent purple

// Borders
className="border-border"      // Standard borders
className="border-kai-table-border" // Table borders

Typography Classes

// Headings (use semantic classes)
<h1 className="heading-xl">Page Title</h1>      // 2xl bold white
<h2 className="heading-lg">Section Title</h2>  // xl semibold white
<h3 className="heading-md">Card Title</h3>     // lg semibold white
<h4 className="heading-sm">Subsection</h4>     // base semibold white

// Body text
<p className="text-body-primary">Main content</p>    // white
<p className="text-body-secondary">Helper text</p>   // slate-400
<p className="text-body-tertiary">Timestamp</p>      // slate-500

// Labels
<span className="label-uppercase">SECTION</span>     // xs uppercase tracking-wide slate-400
<label className="label-default">Field</label>       // sm medium slate-400
<span className="stat-label">METRIC</span>           // xs uppercase slate-400

Component Patterns

Cards

import { Card, CardHeader, CardTitle, CardDescription, CardContent } from "@/components/ui/card";

<Card>
  <CardHeader>
    <CardTitle>Title Here</CardTitle>
    <CardDescription>Description text</CardDescription>
  </CardHeader>
  <CardContent>
    {/* Content */}
  </CardContent>
</Card>

// Card base: rounded-lg border-slate-700/50 bg-slate-800/60 text-white shadow-sm

Buttons

import { Button } from "@/components/ui/button";

<Button>Default (Primary)</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="outline">Outline</Button>
<Button variant="destructive">Destructive</Button>
<Button variant="ghost">Ghost</Button>
<Button variant="link">Link</Button>

// Sizes
<Button size="sm">Small</Button>
<Button size="default">Default</Button>
<Button size="lg">Large</>

Badges (Status & Temperature)

// Temperature badges (lead scoring)
<span className="badge-hot">Hot</span>    // Red: #FF4B4B33 bg, #FF6B6B text
<span className="badge-warm">Warm</span>  // Yellow: #FFC04B33 bg, #FFD76B text
<span className="badge-cold">Cold</span>  // Blue: #4B7BFF33 bg, #6B93FF text

// Status badges
<span className="status-success">Active</span>   // Green
<span className="status-error">Failed</span>     // Red
<span className="status-warning">Pending</span>  // Yellow
<span className="status-info">Info</span>        // Blue

// All badges: rounded-full px-2.5 py-0.5 font-semibold

Tables

// Table row with hover
<tr className="table-row hover:bg-kai-hover-row">
  <td className="px-4 py-3">Content</td>
</tr>

// Selected row
<tr className="table-row-selected">
  <td>Selected content</td>
</tr>

// Table headers: text-kai-text-table-heading (#B0B2C3)

Forms & Inputs

import { Input } from "@/components/ui/input";
import { Label } from "@/components/ui/label";

<div className="space-y-2">
  <Label htmlFor="email">Email</Label>
  <Input id="email" placeholder="Enter email" />
</div>

// Input base: bg-secondary border-border text-foreground
// Focus: ring-kai-blue

Dialogs/Modals

import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogDescription } from "@/components/ui/dialog";

<Dialog>
  <DialogContent className="bg-modal-bg border-modal-border">
    <DialogHeader>
      <DialogTitle>Modal Title</DialogTitle>
      <DialogDescription>Description here</DialogDescription>
    </DialogHeader>
    {/* Content */}
  </DialogContent>
</Dialog>

Emotional Interactions

Every button click should invoke emotion. Users perform tedious tasks; reward them.

Keep it subtle. Feedback should be felt, not seen. Avoid:

• Bright flashes or strobing effects
• High-contrast color pops (white on dark)
• Large, jarring movements
• Animations longer than 300ms
• Anything that draws attention away from the task

Prefer: soft glows, gentle scale changes (1.02-1.05x), muted color transitions, spring physics with high damping.

Micro-Celebration Triggers

Action	Feedback	Implementation
Task complete	Soft checkmark fade-in	Icon opacity 0→1 over 200ms
Form submit	Gentle green tint, quiet toast	Subtle bg-color shift, no flash
Delete/Archive	Smooth slide away	Slide-out 250ms with opacity fade
Toggle on	Soft snap into place	Spring with damping 0.8
Save success	Soft glow around button	Box-shadow fade in/out over 400ms
Error	Gentle wobble + muted red	2-3px horizontal shake, soft red

Eye comfort guidelines:

• Use muted success green (#34D399 at 60% opacity) not bright green
• Error red should be soft (#FF4B4B with transparency), never pure red
• Confetti/particles should be sparse and low-contrast
• Prefer opacity transitions over color flashes

Button Feedback Patterns

// Success button with feedback
<Button
  onClick={async () => {
    await action();
    // Show success state briefly
    setSuccess(true);
    setTimeout(() => setSuccess(false), 1500);
  }}
  className={cn(
    "transition-all duration-150",
    success && "bg-kai-success-text scale-105"
  )}
>
  {success ? <Check className="h-4 w-4" /> : "Save Changes"}
</Button>

// Loading state with anticipation
<Button disabled={loading}>
  {loading ? (
    <>
      <Loader2 className="mr-2 h-4 w-4 animate-spin" />
      Saving...
    </>
  ) : (
    "Save"
  )}
</Button>

Toast Celebrations

import { toast } from "sonner";

// Success with personality
toast.success("Agent created!", {
  description: "Your AI assistant is ready to take calls."
});

// Milestone celebration
toast("Deal closed!", {
  icon: "🎉",
  description: "Great work! $50,000 added to pipeline."
});

High-Anxiety Moment Patterns

Identify moments where users feel nervous and provide reassurance:

// Before destructive action - confirm with clear consequences
<AlertDialog>
  <AlertDialogContent>
    <AlertDialogHeader>
      <AlertDialogTitle>Delete this agent?</AlertDialogTitle>
      <AlertDialogDescription>
        This will permanently remove "Sales Assistant" and all its call history.
        This action cannot be undone.
      </AlertDialogDescription>
    </AlertDialogHeader>
    <AlertDialogFooter>
      <AlertDialogCancel>Keep Agent</AlertDialogCancel>
      <AlertDialogAction className="bg-destructive">
        Yes, Delete Agent
      </AlertDialogAction>
    </AlertDialogFooter>
  </AlertDialogContent>
</AlertDialog>

// After scary action - immediate reassurance
toast.success("Agent deleted", {
  description: "Don't worry, your leads are still safe."
});

Hover & Focus States

Every interactive element needs visible feedback (keep it gentle):

// Button hover: tiny scale, subtle brighten
className="hover:scale-[1.02] hover:brightness-105 transition-all duration-150"

// Card hover: slight lift with soft shadow
className="hover:shadow-elevation-md hover:-translate-y-0.5 transition-all duration-200"

// Link hover: gentle color shift
className="hover:text-kai-purple/80 transition-colors duration-150"

Reduced Motion Support

Respect users who prefer reduced motion:

// Use Tailwind's motion-safe/motion-reduce
className="motion-safe:hover:scale-[1.02] motion-reduce:hover:opacity-80"

// Or check in JS
const prefersReducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;

Motion Standards

All animations must run at 60fps.

Interaction	Duration	Easing
Micro (toggles, buttons)	120-160ms	ease-out
Small transitions	200-240ms	ease-out
Screen transitions	300-400ms	cubic-bezier(0.4, 0, 0.2, 1)

/* Use design system tokens */
--transition-fast: 150ms
--transition-normal: 200ms
--transition-slow: 300ms

Animation Classes

// Skeleton loading (use instead of spinners)
<div className="skeleton-shimmer h-4 w-32 rounded" />

// Collapsible
<CollapsibleContent className="collapsible-content">
  <ChevronIcon className="collapsible-chevron" />
</CollapsibleContent>

Elevation & Shadows

// Shadow utilities
className="shadow-elevation-sm"  // Subtle
className="shadow-elevation-md"  // Cards
className="shadow-elevation-lg"  // Dropdowns
className="shadow-elevation-xl"  // Modals

// Z-index scale
className="z-dropdown"  // 50
className="z-modal"     // 100
className="z-toast"     // 150

Empty States

Never show "No data found." Always provide:

1. Helpful illustration (optional)
2. Encouraging copy explaining what goes here
3. Clear CTA to populate data

<div className="text-center py-12">
  <Illustration className="mx-auto mb-4 h-24 w-24 text-muted-foreground" />
  <h3 className="heading-md mb-2">No leads yet</h3>
  <p className="text-body-secondary mb-4">
    Leads will appear here when callers reach your AI assistant.
  </p>
  <Button>Create Your First Agent</Button>
</div>

Loading States

Use skeleton loaders that match content shape:

// Card skeleton
<Card>
  <CardHeader>
    <Skeleton className="h-6 w-48" />
    <Skeleton className="h-4 w-32 mt-2" />
  </CardHeader>
  <CardContent>
    <Skeleton className="h-24 w-full" />
  </CardContent>
</Card>

// Table skeleton
{Array.from({ length: 5 }).map((_, i) => (
  <tr key={i}>
    <td><Skeleton className="h-4 w-24" /></td>
    <td><Skeleton className="h-4 w-32" /></td>
    <td><Skeleton className="h-4 w-16" /></td>
  </>
))}

Gradient Utilities

// Brand gradient background
<div className="bg-gradient-kai">Gradient bg</div>

// Gradient text
<span className="text-gradient-kai">Gradient text</span>

// The gradient: linear-gradient(90deg, #5C8CFF 0%, #C68BF8 100%)

Page Layout Template

export default function DashboardPage() {
  return (
    <div className="space-y-6">
      {/* Page header */}
      <div className="flex items-center justify-between">
        <div>
          <h1 className="heading-xl">Page Title</h1>
          <p className="text-body-secondary mt-1">
            Brief description of this page
          </p>
        </div>
        <Button>Primary Action</Button>
      </div>

      {/* Content cards */}
      <div className="grid gap-6 md:grid-cols-2 lg:grid-cols-3">
        <Card>
          <CardHeader>
            <CardTitle>Card Title</CardTitle>
          </CardHeader>
          <CardContent>
            {/* Content */}
          </CardContent>
        </Card>
      
    
  );
}

Stat Card Pattern

<Card>
  <CardContent className="p-6">
    <div className="flex items-center justify-between">
      <span className="stat-label">Total Calls</span>
      <Phone className="h-4 w-4 text-muted-foreground" />
    </div>
    <div className="mt-2">
      <span className="data-value">1,234</span>
      <span className="text-kai-success-text text-sm ml-2">+12%</span>
    </div>
  </CardContent>
</Card>

Error Handling

Humanize errors with conversational copy:

// Instead of "Error 500"
<Alert variant="destructive">
  <AlertTitle>Something went wrong</AlertTitle>
  <AlertDescription>
    We're looking into it. Try refreshing the page.
  </AlertDescription>
</Alert>

Checklist Before Shipping

• Every button has emotional feedback (hover, active, success states)
• Feedback is subtle (no flashing, strobing, or harsh contrast)
• Uses design system color tokens (not hardcoded hex)
• Typography uses semantic classes (heading-, text-body-)
• Loading states use skeletons (not spinners)
• Empty states have helpful copy and CTAs
• Success actions show micro-celebrations (toast, animation, color change)
• Destructive actions have confirmation + reassurance
• Animations run at 60fps and are under 300ms
• Respects prefers-reduced-motion (use motion-safe/motion-reduce)
• Dark mode compatible (no light-only colors)
• Mobile responsive (min-width 375px)
• Uses shadcn/ui components where available

Reference Documentation

For detailed information, see:

• Full Color Tokens - Complete list of all CSS variables and Tailwind classes
• Component Examples - Real-world patterns for dashboards, tables, forms, and more