Project Structure

The AI UX Kit follows a layered architecture where components build on top of each other. Understanding this structure helps you find components quickly and extend them confidently.

Directory Overview

ai-ux-kit/
├── app/                        # Next.js App Router pages
│   ├── composites/             # Demo pages for composite components
│   ├── primitives/             # Demo pages for primitive components
│   ├── recipes/                # Demo pages for recipe patterns
│   │   ├── citation/
│   │   ├── compare/
│   │   ├── error-handling/
│   │   ├── prompt-submission/
│   │   ├── refinement/
│   │   ├── session/
│   │   ├── upload/
│   │   └── voice/
│   ├── templates/              # Demo pages for templates
│   ├── globals.css             # Tailwind config and design tokens
│   └── layout.tsx              # Root layout
├── components/
│   └── ui/
│       ├── primitives/         # 22 foundational components
│       ├── composites/         # 24 multi-part components
│       ├── recipes/            # 39 purpose-built patterns
│       └── templates/          # 29 ready-to-use sections
├── hooks/                      # Custom React hooks
│   └── use-mobile.ts
├── lib/                        # Utility functions
│   └── utils.ts
├── public/                     # Static assets
├── components.json             # shadcn/ui configuration
├── next.config.ts              # Next.js configuration
├── package.json
└── tsconfig.json

Component Tiers

The kit organizes components into four tiers, each building on the layer below:

Primitives (22 components)

Atomic building blocks — the smallest reusable UI elements. These have minimal internal logic and are styled with Tailwind CSS variants.

Examples: Button, Input, Checkbox, Select, Tooltip, Switch, Skeleton, Spinner, Tag, Label

components/ui/primitives/
├── button/
├── input/
├── input-group/
├── select/
├── checkbox/
├── radio-group/
├── switch/
├── textarea/
├── tooltip/
├── tag/
├── label/
├── icon/
├── icon-button/
├── link/
├── divider/
├── field/
├── spinner/
├── skeleton/
├── progress-bar/
├── collapsible/
├── form/
└── data-table/

Composites (24 components)

Multi-part components that combine primitives into cohesive UI patterns. These handle internal state and user interactions.

Examples: Sidebar, Dialog, Drawer, Sheet, Chat Bubble, Code Block, Navigation Menu, Prompt Input

components/ui/composites/
├── sidebar/
├── dialog/
├── drawer/
├── sheet/
├── modal/
├── tabs/
├── navigation-menu/
├── dropdown-menu/
├── chat-bubble/
├── chat-sidebar/
├── chat-image/
├── code-block/
├── prompt-input/
├── ai-suggestion/
├── alert/
├── toast/
├── avatar/
├── citations/
├── topbar/
├── audio/
├── interactive-dropdown/
├── fab-ai-assistance/
└── theme-toggle/

Recipes (39 components)

Purpose-built patterns that solve specific AI UX problems. Each recipe is a complete interaction pattern you can drop into your app.

Category	Components	Purpose
Prompt Submission	9	Text input, command palette, multi-step prompts
Refinement	6	Editing and refining AI responses
Citation	4	Source attribution and reference display
Upload	6	File, image, and document upload flows
Voice	5	Voice input and audio interaction
Compare	3	Side-by-side AI response comparison
Error Handling	2	Graceful error states and retry patterns
Session	3	Chat session management

Templates (29 components)

Full page sections ready for production use. These combine multiple composites and primitives into complete UI regions.

• Dropdown Templates (5): profile menu, flyout menu, avatar checkbox, simple list, searchbar
• Modal Templates (24): various dialog and overlay patterns

The app/ Directory

Every component tier has a corresponding demo directory under app/. These pages show each component in action and serve as usage documentation:

• /primitives/button — Button variants and sizes
• /composites/sidebar — Sidebar navigation patterns
• /recipes/prompt-submission — Prompt input variations
• /templates/dropdown/profile-menu — Profile dropdown template

Key Files

File	Purpose
components.json	shadcn/ui config (new-york style, Lucide icons)
lib/utils.ts	cn() helper for merging class names
hooks/use-mobile.ts	Mobile viewport detection hook
app/globals.css	Design tokens and Tailwind configuration