Always one step ahead
AI-enhanced adaptive design system for React
Features • Components • Installation • Quick Start • Adaptive Behavior • Architecture
Ahead UI is a next-generation design system that adapts to user behavior in real-time. Unlike traditional component libraries, Ahead UI uses invisible AI to create interfaces that feel intuitive and responsive—without the user ever noticing.
Key differentiators:
- 🧠 Adaptive Behavior — Components that respond to user pace, time of day, and interaction patterns
- ♿ Accessibility-First — Built on React Aria for bulletproof keyboard navigation and screen reader support
- ⚡ Zero Runtime CSS — OKLCH colors with CSS custom properties for instant theming
- 📦 Optimal Bundle Size — No barrel files, proper tree-shaking, ESM-only
- 🎨 Deeply Customizable — CVA variants + Tailwind CSS integration
- 🔄 asChild Pattern — Render components as any element with
asChild - 🎬 Motion Design — Framer Motion animations with reduced-motion support
- Slot — asChild pattern implementation for component composition
- Button — Versatile button with variants, loading states, and icons
- Input — Text input with labels, validation, and addons
- Switch — Toggle switch with labels and descriptions
- Checkbox — Checkbox with indeterminate state support
- Card — Container with header, body, and footer (compound component)
- Badge — Labels and status indicators with color schemes
- Avatar — User images with fallbacks and status indicators
- AvatarGroup — Multiple avatars with overlap and "+N" indicator
- Spinner — Loading spinners (circle and dots variants)
- Tooltip — Hover/focus tooltips with placements
- Dialog — Modal dialogs with focus trap and animations
# With pnpm (recommended)
pnpm add @ahead-ui/core @ahead-ui/components
# With npm
npm install @ahead-ui/core @ahead-ui/components
# With yarn
yarn add @ahead-ui/core @ahead-ui/components- Import the CSS tokens:
// In your app entry point (e.g., _app.tsx, layout.tsx)
import '@ahead-ui/core/tokens/css';- Use components:
import { Button, Input, Card, Badge } from '@ahead-ui/components';
import { cn } from '@ahead-ui/core';
function App() {
return (
<Card>
<Card.Header>
<Card.Title>Welcome</Card.Title>
<Badge colorScheme="success">New</Badge>
</Card.Header>
<Card.Body>
<Input label="Email" type="email" placeholder="you@example.com" />
</Card.Body>
<Card.Footer>
<Button variant="primary" size="lg">
Get Started
</Button>
</Card.Footer>
</Card>
);
}- Enable dark mode:
// Add 'dark' class or data-theme="dark" to html/body
<html className="dark">
{/* or */}
<html data-theme="dark">The killer feature of Ahead UI is its adaptive behavior system. Use hooks to detect user patterns and adjust your UI accordingly:
import { useUserBehavior, useAdaptiveConfig } from '@ahead-ui/core';
function MyApp({ children }) {
const behavior = useUserBehavior();
const config = useAdaptiveConfig(behavior);
// config.density → 'compact' | 'normal' | 'comfortable'
// config.animationMultiplier → Adjust animation speed
// config.showHints → Whether to show optional hints
// config.debounceMs → Recommended debounce time
return (
<div
data-density={config.density}
style={{ '--animation-speed': config.animationMultiplier }}
>
{children}
</div>
);
}- Click patterns — Average time between clicks
- Scroll behavior — How fast users scroll
- Mouse movement — Cursor speed and precision
- Typing speed — Characters per second
- Time of day — Adjustments for evening/night usage
- Session duration — Learning over time
| User Pace | Animations | Density | Hints | Debounce |
|---|---|---|---|---|
| Fast | 0.6x speed | Compact | Hidden | 150ms |
| Normal | 1x speed | Normal | Shown | 300ms |
| Slow | 1.2x speed | Comfortable | Shown | 500ms |
// Variants
<Button variant="primary">Primary</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="outline">Outline</Button>
<Button variant="ghost">Ghost</Button>
<Button variant="danger">Danger</Button>
// Sizes
<Button size="sm">Small</Button>
<Button size="md">Medium</Button>
<Button size="lg">Large</Button>
// With icons
<Button leftIcon={<PlusIcon />}>Add Item</Button>
// Loading
<Button isLoading loadingText="Saving...">Save</Button>
// As a link (asChild pattern)
<Button asChild>
<a href="/home">Go Home</a>
</Button>// With validation
<Input
label="Email"
type="email"
isInvalid
errorMessage="Please enter a valid email"
/>
// With addons
<Input leftAddon="https://" placeholder="example.com" />
// Variants
<Input variant="filled" placeholder="Filled style" />
<Input variant="flushed" placeholder="Flushed style" />const [isOpen, setIsOpen] = useState(false);
<Button onClick={() => setIsOpen(true)}>Open</Button>
<Dialog isOpen={isOpen} onClose={() => setIsOpen(false)}>
<Dialog.Header>
<Dialog.Title>Confirm</Dialog.Title>
<Dialog.Description>Are you sure?</Dialog.Description>
</Dialog.Header>
<Dialog.Body>
Content here
</Dialog.Body>
<Dialog.Footer>
<Button variant="ghost" onClick={() => setIsOpen(false)}>
Cancel
</Button>
<Button>Confirm</Button>
</Dialog.Footer>
</Dialog>Use the Ahead UI preset to integrate design tokens with Tailwind:
// tailwind.config.js
import aheadPreset from '@ahead-ui/core/tailwind-preset';
export default {
presets: [aheadPreset],
content: [
'./src/**/*.{js,ts,jsx,tsx}',
'./node_modules/@ahead-ui/components/**/*.js',
],
};Now you can use semantic colors:
<div className="bg-bg text-fg border-border">
<span className="text-primary">Primary color</span>
<span className="text-danger">Danger color</span>
</div>┌─────────────────────────────────────┐
│ Your Application │
├─────────────────────────────────────┤
│ @ahead-ui/components │
│ (Button, Input, Card, etc.) │
├─────────────────────────────────────┤
│ @ahead-ui/core │
│ (tokens, hooks, utilities) │
├─────────────────────────────────────┤
│ React Aria (accessibility) │
├─────────────────────────────────────┤
│ Tailwind CSS + CVA (styling) │
└─────────────────────────────────────┘
| Problem with Others | Ahead UI Solution |
|---|---|
| MUI's runtime CSS causes performance issues | Zero-runtime CSS custom properties |
| shadcn's copy-paste loses updates | Package-based with semantic versioning |
| Ant Design's strict theming | Three-layer token system |
| Chakra's bundle bloat | No barrel files, ESM-only |
| Radix's version conflicts | Unified React Aria foundation |
| Package | Description |
|---|---|
@ahead-ui/core |
Design tokens, utilities, and adaptive hooks |
@ahead-ui/components |
React components (Button, Input, etc.) |
@ahead-ui/cli |
CLI for adding components to your project |
Ahead UI supports all modern browsers:
- Chrome/Edge 88+
- Firefox 78+
- Safari 14+
OKLCH colors require modern browser support. For older browsers, a fallback is automatically provided.
We welcome contributions! Please see our Contributing Guide for details.
MIT © Francesco Pesoli
Built with ❤️ by Francesco Pesoli