KiteUI for AI-Assisted Development

KiteUI is designed to work well with AI coding tools and developer agents. Its components are documented with clear usage examples, props, accessibility notes, and copyable implementation patterns for Cursor, Claude Code, ChatGPT, Copilot, Windsurf, and v0-style workflows.

AI Summary

KiteUI is a shadcn/ui-based UI system for building SaaS apps, dashboards, admin panels, customer portals, and internal tools. It provides components, templates, and implementation examples designed for production web applications.

KiteUI MCP

Install kiteuikit-mcp in Cursor or Claude Desktop for live component docs, design tokens, and code generation. Requires any paid plan (Pro, Team, or Enterprise) — use your license key as mcp_KITE-…. Do not use curl as the MCP command.

MCP setup guide Playground About MCP View pricing

REST backend used by the bridge (paid plans). Header X-API-Key for direct fetch/curl — not for Cursor MCP.

https://kiteui.com/api/mcp

https://kiteui.com/api/mcp

Integration snippets

Replace mcp_KITE-XXXX-XXXX-XXXX with your license key from checkout or the admin dashboard.

Install kiteuikit-mcp@0.1.0 via npx (stdio bridge). Paid plan required. Restart Cursor after saving.

.cursor/mcp.json

{
  "mcpServers": {
    "kiteui": {
      "command": "npx",
      "args": ["-y", "kiteuikit-mcp@0.1.0"],
      "env": {
        "KITEUI_API_KEY": "mcp_KITE-XXXX-XXXX-XXXX"
      }
    }
  }
}

Editor rules (copy & paste)

Full KiteUI rules: component catalog, CLI, design tokens, page recipes, Motion patterns, Pro licensing, and accessibility. Copy into your repo or the tool's settings.

Project rules for Cursor. Paste into `.cursorrules` at your repo root (or Cursor Settings → Rules).

.cursorrules

# KiteUI — AI editor rules

You are building UI with **KiteUI** (kiteui.com): a soft, rounded component library on **shadcn/ui**, **Tailwind CSS v4**, and **Motion**. Use it for profile pages, link-in-bio sites, creator storefronts, SaaS dashboards, admin panels, and internal tools.

## Stack & conventions

- **Framework**: Next.js 16 App Router, React 19, TypeScript
- **Styling**: Tailwind v4 + semantic tokens (`bg-background`, `text-muted-foreground`) — avoid raw `gray-*` for surfaces
- **Icons**: `lucide-react` only
- **Animation**: `motion/react` (import `{ motion }` from `"motion/react"`)
- **Utilities**: `cn()` from `@/lib/utils` for class merging
- **Client components**: Add `"use client"` when using hooks, Motion, or browser APIs

## Install & CLI

```bash
pnpm add kiteuikit@latest -D
npx kiteuikit setup
# or: npx kiteuikit init && npx kiteuikit add bubble-card profile-header
npx kiteuikit activate KITE-XXXX-XXXX-XXXX
npx kiteuikit theme ocean
```

- Free components ship in the npm package; **Pro** components download from kiteui.com after license validation.
- Docs: https://kiteui.com/docs/cli

## Imports (required)

Always import KiteUI profile components from the **barrel** — never deep-import individual files:

```tsx
import {
  BubbleCard,
  ProfileAvatar,
  ProfileHeader,
  SocialLinkButton,
  ThumbnailScroller,
  DynamicIsland,
  LinkTree,
  StatsWidget,
  SectionHeader,
  StoreProductCard,
  SportsCard,
  InfluencerBadge,
  BubbleSlider,
  DetailModal,
  StoryHighlights,
  QuickActions,
  ShareSheet,
  NotificationBell,
  Skeleton,
  CountdownTimer,
  TipJar,
  AnnouncementBanner,
  ReviewCard,
  SwipeableCard,
  MediaGrid,
  PollWidget,
} from "@/components/profile"
```

Base primitives (Button, Input, Dialog, etc.) come from `@/components/ui/*` (shadcn).

## Component catalog

### Free (npm)
| Component | Use for |
|-----------|---------|
| `BubbleCard` | Soft cards; variants: `pink`, `sky`, `mint`, `peach`, `lavender`, `white`; props `hoverable`, `pressable` |
| `ProfileAvatar` | Avatar + gradient ring + `status` (online/offline/busy/away) |
| `SocialLinkButton` | Instagram, Twitter/X, YouTube, TikTok, etc.; variants `pill`, `card`, `icon` |
| `BubbleSlider` | Touch-friendly range slider |
| `SectionHeader` | Section title + optional "See all" action |
| `Skeleton*` | Loading placeholders |

### Pro (license + `npx kiteuikit add <name>`)
| Component | Use for |
|-----------|---------|
| `ProfileHeader` | Cover image, stats, bio, verified badge |
| `ThumbnailScroller` | Horizontal snap gallery |
| `DynamicIsland` | Floating bottom/top nav (iOS-style) |
| `LinkTree` | Link-in-bio list with stagger animation |
| `StatsWidget` | Metrics + trend indicators |
| `StoreProductCard` | Product grid cards |
| `SportsCard` | Collectible / trading cards |
| `InfluencerBadge` | verified, creator, influencer, partner |
| `DetailModal`, `ImageViewer` | Full-screen detail |
| `StoryHighlights` | Story rings + viewer |
| `QuickActions` | FAB-style action sheet |
| `ShareSheet` | Native-style share sheet |
| `NotificationBell` | Notification dropdown |
| `CountdownTimer` | Event countdown |
| `TipJar` | Support / tip amounts |
| `AnnouncementBanner`, `MarqueeBanner` | Site-wide promos |
| `ReviewCard`, `ReviewSummary` | Social proof |
| `SwipeableCard` | Swipe actions |
| `MediaGrid`, `BentoGrid`, `MediaLightbox` | Photo grids |
| `PollWidget`, `QuizWidget` | Engagement |

Wrap Pro UI with `ProGate` / `LicenseGate` when gating in-app:

```tsx
import { ProGate } from "@/components/profile"

<ProGate feature="profile-header">
  <ProfileHeader {...props} />
</ProGate>
```

## Design system

### Bubble color tokens (prefer over Tailwind pastels)
`bg-bubble-pink`, `bg-bubble-sky`, `bg-bubble-mint`, `bg-bubble-peach`, `bg-bubble-lavender`

Page backgrounds often use soft gradients:
`bg-gradient-to-b from-bubble-pink/30 via-background to-bubble-sky/20`

### Radius scale
- Controls/chips: `rounded-xl`
- Cards: `rounded-2xl`
- Hero sections: `rounded-3xl`
- Pills, avatars, icon buttons: `rounded-full`

### Typography
- Headings: `font-semibold tracking-tight` (or `font-bold tracking-tight` for heroes)
- Body: `text-muted-foreground`
- Labels: `text-sm font-medium`

### Spacing & layout
- Page padding: `px-4 py-6` or `container mx-auto px-4`
- Section gaps: `space-y-6` or `space-y-8`
- Mobile-first grids: `grid grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-4`
- Touch targets: **minimum 44px** height/width on all interactive elements

## Motion standards

```tsx
<motion.div
  whileHover={{ scale: 1.02 }}
  whileTap={{ scale: 0.98 }}
  transition={{ type: "spring", stiffness: 400, damping: 25 }}
/>
```

Page enter:
```tsx
initial={{ opacity: 0, y: 16 }}
animate={{ opacity: 1, y: 0 }}
transition={{ duration: 0.3 }}
```

List stagger: parent `variants` with `staggerChildren: 0.08`.

## Page recipes

### Link-in-bio / creator profile
```tsx
export default function ProfilePage() {
  return (
    <div className="min-h-screen bg-gradient-to-b from-bubble-pink/40 to-bubble-sky/30">
      <ProfileHeader
        name="Creator Name"
        username="@handle"
        avatar="/avatar.jpg"
        coverImage="/cover.jpg"
        bio="Short bio"
        stats={[
          { label: "Followers", value: "12K" },
          { label: "Following", value: "240" },
          { label: "Posts", value: "89" },
        ]}
        verified
      />
      <motion.div className="flex justify-center gap-2 py-4">
        <SocialLinkButton platform="instagram" href="#" variant="icon" />
        <SocialLinkButton platform="youtube" href="#" variant="icon" />
      </motion.div>
      <ThumbnailScroller items={photos} variant="rounded" showTitles />
      <LinkTree links={links} variant="gradient" />
      <DynamicIsland items={navItems} position="bottom" />
    </div>
  )
}
```

### Storefront
```tsx
<div className="p-4 space-y-6 max-w-lg mx-auto">
  <BubbleCard variant="white" className="flex items-center gap-4 p-4">
    <ProfileAvatar src="/avatar.jpg" alt="Shop" size="lg" ring="gradient" />
    <div>
      <h1 className="font-semibold tracking-tight">Shop Name</h1>
      <p className="text-sm text-muted-foreground">Tagline</p>
    </div>
  </BubbleCard>
  <SectionHeader title="Featured" action={{ label: "View all", href: "/shop" }} />
  <div className="grid grid-cols-2 gap-4">
    {products.map((p) => (
      <StoreProductCard key={p.id} {...p} />
    ))}
  </div>
</div>
```

### SaaS dashboard section
```tsx
<div className="space-y-6 p-4 md:p-8">
  <SectionHeader title="Overview" />
  <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
    <StatsWidget stats={metrics} />
    <BubbleCard variant="sky" className="p-6">
      <h3 className="font-semibold tracking-tight">Quick actions</h3>
      <QuickActions actions={actions} />
    </BubbleCard>
  </div>
</div>
```

## Horizontal galleries

```tsx
<ThumbnailScroller
  items={items} // { id, image, title? }[]
  variant="rounded" // or "square" | "circle"
  showTitles
  className="px-4"
/>
```

Use `snap-x snap-mandatory` patterns; library handles overflow scroll.

## Accessibility (required)

1. `aria-label` on every icon-only button/link
2. Meaningful `alt` on `ProfileAvatar` and images
3. `focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2`
4. Don't rely on color alone for state — pair with text/icons
5. Respect `prefers-reduced-motion` for large animations when adding custom motion

## Do / Don't

| Do | Don't |
|----|-------|
| Import from `@/components/profile` | Deep-import `components/profile/foo.tsx` |
| Use `bg-bubble-*` and shadcn semantic colors | Hard-code `bg-gray-100`, `text-zinc-500` for UI chrome |
| `rounded-2xl`+ on cards | Sharp `rounded-md` cards (breaks brand) |
| Motion spring press/hover on interactive cards | Jarring CSS-only `hover:scale-110` without tap feedback |
| Mobile-first, 44px targets | Tiny icon hit areas |
| `kiteuikit-mcp` for Cursor MCP (paid plans) | `curl` as MCP command in Cursor |

## MCP (paid plans)

Cursor / Claude Desktop: `npx -y kiteuikit-mcp@0.1.0` with `KITEUI_API_KEY`. Setup: https://kiteui.com/docs/mcp

## Reference

- Docs: https://kiteui.com/docs
- Components: https://kiteui.com/docs/components
- Tokens: https://kiteui.com/docs/tokens
- CLI: https://kiteui.com/docs/cli
- AI page: https://kiteui.com/ai


## Cursor-specific

- Prefer editing existing KiteUI components over creating duplicates in `components/ui`.
- When adding a page, colocate data fetching in Server Components; keep Motion in Client Components.
- Use @/ path alias consistently.

Best use cases

SaaS dashboards
internal tools
admin panels
onboarding portals
customer portals
form-heavy applications
modern marketing sites

Recommended prompt

Use KiteUI components to build a clean SaaS dashboard with shadcn/ui patterns. Prefer accessible components, semantic HTML, responsive layouts, and production-ready design system conventions.

Docs Installation Components Templates MCP setup MCP playground

Last updated: 2026-05-16