flikkui 0.2.0-beta.1 → 0.2.0-beta.10

package/README.md

@@ -1,566 +1,224 @@
 # Flikkui
 
-<p align="center">
-  <strong>A modern React component library built with TypeScript, Tailwind CSS v4, and Framer Motion</strong>
-</p>
+A modern React component library built with TypeScript, Tailwind CSS v4, and Framer Motion. Follows the shadcn philosophy with complete `className` override support.
 
-<p align="center">
-  <a href="https://www.npmjs.com/package/flikkui"><img src="https://img.shields.io/npm/v/flikkui?label=npm&color=blue" alt="npm version" /></a>
-  <a href="https://www.npmjs.com/package/flikkui"><img src="https://img.shields.io/npm/dm/flikkui" alt="npm downloads" /></a>
-  <a href="https://github.com/yourusername/flikkui/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License" /></a>
-  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-Ready-blue" alt="TypeScript" /></a>
-</p>
+## Installation
 
-<p align="center">
-  Follows the <strong>shadcn philosophy</strong> - override any styling using className props while getting sensible defaults out of the box.
-</p>
-
----
-
-## 📋 Table of Contents
-
-- [Why Flikkui?](#-why-flikkui)
-- [Quick Start](#-quick-start)
-- [Usage Examples](#-usage-examples)
-- [Tree-Shaking & Optimized Imports](#-tree-shaking--optimized-imports)
-- [Customization](#-customization)
-- [Component Library](#-component-library)
-- [Performance](#-performance)
-- [Documentation](#-documentation)
-- [Contributing](#-contributing)
-- [License](#-license)
-
----
-
-## ✨ Why Flikkui?
-
-- 🎨 **100+ Production-Ready Components** - Everything from buttons to complex charts
-- 🚀 **CLI Setup Tool** - Get started in 30 seconds with `npx flikkui init`
-- 🌳 **Optimized Tree-Shaking** - 60-85% bundle size reduction
-- 🎭 **CSS Variables** - Easy theming without JavaScript
-- ⚡ **Tailwind CSS v4** - Latest and greatest
-- 🔥 **TypeScript-First** - Excellent DX with full type safety
-- ♿ **Accessibility Built-In** - WCAG 2.1 AA compliance
-- 🎪 **shadcn Compatible** - className overrides always take precedence
-
-### 📊 Features at a Glance
-
-| Feature | Flikkui | Other Libraries |
-|---------|---------|-----------------|
-| **Setup Time** | 30 seconds (CLI) | 10+ minutes (manual) |
-| **TypeScript** | ✅ Built-in | ⚠️ Limited/Optional |
-| **Tree-Shaking** | ✅ Optimized | ⚠️ Basic |
-| **className Override** | ✅ Always works | ❌ Often blocked |
-| **CSS Variables** | ✅ Full support | ⚠️ Partial |
-| **Accessibility** | ✅ WCAG 2.1 AA | ⚠️ Basic |
-| **Bundle Size** | 🟢 15-150KB | 🟡 100-500KB |
-| **Animation** | ✅ Optional Motion | ⚠️ Required/None |
-| **Charts** | ✅ 18+ Built-in | ❌ Separate library |
-| **AI Components** | ✅ Included | ❌ Not available |
-
-## 🚀 Quick Start
+```bash
+npm install flikkui
+# or
+yarn add flikkui
+```
 
-### ⚡ Automatic Setup (Recommended)
+## Setup
 
-Get started in seconds with our CLI tool:
+The quickest way to get started is with the CLI init command. It auto-detects your project type (Next.js, Vite, Remix, CRA), installs peer dependencies, and injects the CSS import into your entry file:
 
 ```bash
-# Step 1: Install Flikkui
-npm install flikkui@beta
-
-# Step 2: Run the setup wizard
 npx flikkui init
 ```
 
-**That's it!** The CLI automatically:
-- ✅ Installs all required dependencies (@heroicons/react, motion, tailwindcss, etc.)
-- ✅ Detects your framework (Next.js, Vite, CRA, Remix)
-- ✅ Injects CSS imports in the right file
-- ✅ Configures Tailwind CSS (optional)
-
-**CLI Options:**
-```bash
-npx flikkui init              # 🎯 Interactive setup (recommended)
-npx flikkui init --tailwind   # ⚡ Include Tailwind config
-npx flikkui init --yes        # 🚀 Skip prompts, use defaults
-npx flikkui init --skip-install  # 📦 Manual dependency installation
-```
+Options:
 
-> 💡 **Supports:** Next.js (App Router & Pages Router), Vite, Create React App, Remix, and generic React projects
+| Flag | Description |
+|------|-------------|
+| `--tailwind`, `-t` | Set up Tailwind CSS integration (adds preset and content paths) |
+| `--yes`, `-y` | Skip prompts and use defaults |
+| `--skip-install` | Skip installing dependencies (prints manual command instead) |
 
 ### Manual Setup
 
-If you prefer manual installation:
+If you prefer to set things up yourself:
 
-#### 1. Install the package
+1. Install peer dependencies:
 
 ```bash
-npm install flikkui @heroicons/react clsx motion tailwind-merge tailwindcss react-markdown react-syntax-highlighter remark-gfm three
+npm install react react-dom tailwindcss motion clsx tailwind-merge @heroicons/react
+# or
+yarn add react react-dom tailwindcss motion clsx tailwind-merge @heroicons/react
 ```
 
-**Or with yarn:**
-```bash
-yarn add flikkui @heroicons/react clsx motion tailwind-merge tailwindcss react-markdown react-syntax-highlighter remark-gfm three
-```
-
-#### 2. Import styles in your app
+2. Import styles in your main app file:
 
 ```tsx
-// In your main App.tsx, index.tsx, or _app.tsx
 import 'flikkui/styles.css'
-
-function App() {
-  return <YourApp />
-}
 ```
 
-#### 3. Start using components
+## Basic Usage
 
 ```tsx
 import { Button } from 'flikkui'
 
-export function MyComponent() {
-  return (
-    <Button variant="primary">
-      Hello World
-    </Button>
-  )
-}
-```
-
----
-
-## 💻 Usage Examples
-
-### Basic Components
-
-```tsx
-import { Button, Badge, Avatar } from 'flikkui'
-
 function App() {
-  return (
-    <div>
-      {/* Button with variants */}
-      <Button variant="primary" size="md">
-        Click me
-      </Button>
-
-      {/* Badge with colors */}
-      <Badge color="success" variant="soft">
-        Active
-      </Badge>
-
-      {/* Avatar */}
-      <Avatar
-        src="/user.jpg"
-        alt="User"
-        size="md"
-      />
-    </div>
-  )
+  return <Button variant="filled" color="primary">Click me</Button>
 }
 ```
 
-### Form Components
-
-```tsx
-import { Input, Select, Checkbox } from 'flikkui/forms'
-import { MagnifyingGlassIcon } from '@heroicons/react/24/outline'
-
-function SearchForm() {
-  return (
-    <form>
-      {/* Input with icon */}
-      <Input
-        placeholder="Search..."
-        iconStart={<MagnifyingGlassIcon />}
-      />
-
-      {/* Select */}
-      <Select>
-        <option>Choose option</option>
-        <option>Option 1</option>
-      </Select>
-
-      {/* Checkbox */}
-      <Checkbox label="Remember me" />
-    </form>
-  )
-}
-```
+### Subpath Imports
 
-### Charts
+Import from specific categories to optimize bundle size:
 
 ```tsx
+import { Button, Badge, Accordion } from 'flikkui/core'
+import { Input, Select, Checkbox } from 'flikkui/forms'
 import { AreaChart, BarChart } from 'flikkui/charts'
-
-const data = [
-  { month: 'Jan', sales: 4000, revenue: 2400 },
-  { month: 'Feb', sales: 3000, revenue: 1398 },
-  { month: 'Mar', sales: 2000, revenue: 9800 },
-]
-
-const config = {
-  sales: { label: 'Sales', color: '#3b82f6' },
-  revenue: { label: 'Revenue', color: '#10b981' },
-}
-
-function Dashboard() {
-  return (
-    <div>
-      <AreaChart
-        data={data}
-        config={config}
-        className="h-80"
-        showGrid
-        curved
-      />
-
-      <BarChart
-        data={data}
-        config={config}
-        className="h-80"
-      />
-    </div>
-  )
-}
-```
-
-### Advanced: Compound Components
-
-```tsx
-import { Accordion, Modal, Tabs } from 'flikkui'
-
-function AdvancedExample() {
-  return (
-    <>
-      {/* Accordion */}
-      <Accordion>
-        <Accordion.Item>
-          <Accordion.Trigger>What is Flikkui?</Accordion.Trigger>
-          <Accordion.Content>
-            A modern React component library...
-          </Accordion.Content>
-        </Accordion.Item>
-      </Accordion>
-
-      {/* Tabs */}
-      <Tabs defaultValue="profile">
-        <Tabs.List>
-          <Tabs.Trigger value="profile">Profile</Tabs.Trigger>
-          <Tabs.Trigger value="settings">Settings</Tabs.Trigger>
-        </Tabs.List>
-        <Tabs.Content value="profile">Profile content</Tabs.Content>
-        <Tabs.Content value="settings">Settings content</Tabs.Content>
-      </Tabs>
-    </>
-  )
-}
-```
-
-## 🌳 Tree-Shaking & Optimized Imports
-
-Flikkui is optimized for tree-shaking. For the best bundle size, import components from category subpaths:
-
-```tsx
-// ✅ Recommended: Category imports (best tree-shaking)
-import { Button } from 'flikkui/core'
-import { Input, Select } from 'flikkui/forms'
-import { BarChart } from 'flikkui/charts'
 import { GlassEffect } from 'flikkui/effects'
-
-// ✅ Also works: Main import (backward compatible)
-import { Button, Input, BarChart } from 'flikkui'
 ```
 
-### Bundle Size Comparison
-
-| Import Method | Components Used | Bundle Size | Savings |
-|--------------|----------------|-------------|---------|
-| Category imports | 1-3 components | ~50-100KB | 85-90% |
-| Category imports | 10-20 components | ~250-400KB | 67-79% |
-| Main import | Any | Works, but larger | - |
-
-**Categories available:**
-- `flikkui/core` - Button, Modal, Dropdown, Tooltip, etc.
-- `flikkui/forms` - Input, Select, Checkbox, Radio, etc.
-- `flikkui/charts` - AreaChart, BarChart, LineChart, etc.
-- `flikkui/effects` - GlassEffect, visual effects
+## Customizing the Theme
 
-## 🎨 Customization
+Flikkui uses CSS variables for all theming. Override any variable in your own CSS to customize colors, spacing, border radius, and more.
 
-### Using className Overrides (Recommended)
+### Colors
 
-Override styles using className props - the shadcn approach:
-
-```tsx
-<Button className="bg-purple-600 hover:bg-purple-700 rounded-full">
-  Custom Button
-</Button>
-
-<Input className="border-blue-500 focus:ring-blue-500" />
-
-<Badge className="bg-gradient-to-r from-purple-500 to-pink-500">
-  Gradient Badge
-</Badge>
-```
-
-### Using CSS Variables
-
-Customize your design system globally by overriding CSS variables:
+Override semantic color palettes by redefining the CSS variables after importing the library styles:
 
 ```css
-/* In your global CSS file */
-@layer base {
-  :root {
-    /* Change primary color */
-    --color-primary-600: #7c3aed; /* Purple */
-    --color-primary-700: #6d28d9;
-
-    /* Larger buttons */
-    --button-min-h-md: 3rem;
-    --button-px-md: 1.25rem;
-
-    /* More rounded design */
-    --form-rounded: 1rem;
-    --button-rounded: 0.75rem;
-  }
+:root {
+  /* Change the primary color to green */
+  --color-primary-50: oklch(0.982 0.018 155.826);
+  --color-primary-100: oklch(0.962 0.044 156.743);
+  --color-primary-200: oklch(0.925 0.084 155.995);
+  --color-primary-300: oklch(0.871 0.15 154.449);
+  --color-primary-400: oklch(0.792 0.209 151.711);
+  --color-primary-500: oklch(0.723 0.219 149.579);
+  --color-primary-600: oklch(0.627 0.194 149.214);
+  --color-primary-700: oklch(0.527 0.154 150.069);
+  --color-primary-800: oklch(0.448 0.119 151.328);
+  --color-primary-900: oklch(0.393 0.095 152.535);
+  --color-primary-950: oklch(0.266 0.065 152.934);
+
+  --color-primary: var(--color-primary-600);
 }
 ```
 
-**Available CSS variables:**
-- Colors: `--color-primary-*`, `--color-danger-*`, `--color-success-*`, `--color-warning-*`
-- Text: `--color-text-primary`, `--color-text-secondary`, `--color-text-muted`
-- Backgrounds: `--color-background`, `--color-background-secondary`
-- Component-specific: `--button-*`, `--form-*`, `--modal-*`, etc.
-
-## 📚 Component Library
-
-Flikkui includes **100+ production-ready components** across 5 categories. All components are:
-- ✅ **TypeScript-ready** with full type definitions
-- ✅ **Accessible** - WCAG 2.1 AA compliant
-- ✅ **Customizable** - Override with className
-- ✅ **Responsive** - Mobile-first design
-- ✅ **Themeable** - CSS variables support
-- ✅ **Animated** - Optional Framer Motion support
-
-### 🎨 Core Components (45+)
-
-```tsx
-import {
-  Button, Avatar, AvatarGroup, Badge, Accordion,
-  Modal, Drawer, Popover, Dropdown, Tooltip, Tabs,
-  Card, CardStack, Stepper, Segmented, Pagination,
-  Breadcrumbs, Link, Divider, Skeleton, Loader,
-  Calendar, Tree, CommandPalette, ContextMenu,
-  Sidebar, NavItem, Notification, Toast
-} from 'flikkui/core'
-```
-
-**Highlights:** Modal, Drawer, Tabs, Accordion, Dropdown, Tooltip, Popover, Card, CommandPalette
-
-### 📝 Form Components (22+)
+Available color palettes: `primary`, `danger`, `success`, `warning`. Each has shades from `50` to `950`.
 
-```tsx
-import {
-  Input, Select, Checkbox, Radio, Switch, Textarea,
-  DatePicker, TimePicker, ColorPicker, RichTextEditor,
-  FileUpload, Slider, Rating, PasswordInput, PinInput,
-  FormLabel, TagInput, MultiSelect, SearchableSelect
-} from 'flikkui/forms'
-```
+### Text Colors
 
-**Highlights:** Input (with icons), Select, DatePicker, FileUpload, RichTextEditor, ColorPicker
-
-### 📊 Chart Components (18+)
-
-```tsx
-import {
-  AreaChart, BarChart, LineChart, DonutChart, Heatmap,
-  FunnelChart, ScatterPlot, ActivityRings, ComboChart,
-  RadarChart, TreeMap, Sparkline, ProgressChart
-} from 'flikkui/charts'
-```
-
-**Highlights:** AreaChart, LineChart, BarChart, DonutChart, Heatmap, FunnelChart
-
-### ✨ Effect Components
-
-```tsx
-import { GlassEffect, CustomCursor, Overlay } from 'flikkui/effects'
+```css
+:root {
+  --color-text-primary: var(--color-neutral-950);
+  --color-text-secondary: var(--color-neutral-800);
+  --color-text-placeholder: var(--color-neutral-600);
+  --color-text-muted: var(--color-neutral-500);
+  --color-text-disabled: var(--color-neutral-400);
+  --color-text-inverse: var(--color-neutral-50);
+}
 ```
 
-**Highlights:** GlassEffect (automatic color adaptation), CustomCursor, Overlay
+### Backgrounds & Borders
 
-### 🤖 AI Components
-
-```tsx
-import { Message, PromptInput, ThinkingIndicator } from 'flikkui/ai'
+```css
+:root {
+  --color-background: oklch(98.5% 0.002 247.839);
+  --color-background-secondary: oklch(95% 0.002 247.839);
+  --color-background-tertiary: oklch(90% 0.002 247.839);
+  --color-background-quaternary: oklch(85% 0.002 247.839);
+  --color-background-quinary: oklch(80% 0.002 247.839);
+  --color-background-disabled: var(--color-neutral-100);
+  --color-border: oklch(92.2% 0 0);
+}
 ```
 
-**Highlights:** Message (with typewriter effect), PromptInput (AI-ready interface)
-
-## 🆕 What's New in v0.1.0-beta.12+
-
-### 🚀 CLI Setup Tool (NEW!)
-
-The biggest addition - automatic setup with `npx flikkui init`:
-- ✅ Auto-detects your framework (Next.js, Vite, CRA, Remix)
-- ✅ Installs all peer dependencies
-- ✅ Injects CSS imports automatically
-- ✅ Configures Tailwind (optional)
+### Border Radius System
 
-### 🌳 Better Tree-Shaking
+All border radii derive from a single `--radius-base` token. Change it once to update the entire UI:
 
-Improved bundle size with category imports:
-```tsx
-// Before: All components bundled
-import { Button, Input } from 'flikkui'
-
-// After: Only what you need (60-85% smaller)
-import { Button } from 'flikkui/core'
-import { Input } from 'flikkui/forms'
+```css
+:root {
+  --radius-base: 0.5rem; /* 8px - change this to update all radii */
+
+  /* Forms & Controls (1x base) */
+  --form-radius: var(--radius-base);
+  --button-radius: var(--form-radius);
+  --badge-radius: var(--form-radius);
+  --nav-item-radius: var(--radius-base);
+
+  /* Overlays (1.5x base) */
+  --dropdown-radius: calc(var(--radius-base) * 1.5);
+  --tooltip-radius: var(--radius-base);
+  --popover-radius: calc(var(--radius-base) * 1.5);
+
+  /* Feedback surfaces */
+  --alert-radius: calc(var(--radius-base) * 1.5);
+  --toast-radius: calc(var(--radius-base) * 2);
+  --drawer-radius: calc(var(--radius-base) * 2);
+
+  /* Surfaces (3x base) */
+  --card-radius: calc(var(--radius-base) * 3);
+  --modal-radius: calc(var(--radius-base) * 3);
+
+  /* Special shapes */
+  --segmented-radius: 99px;
+  --avatar-radius: 50%;
+}
 ```
 
-### 📦 Peer Dependencies
+### Form Elements
 
-Dependencies are now peers (not bundled) for maximum flexibility and smaller package size.
+Control sizing, padding, and border radius for all form components:
 
----
-
-## 🔄 Migration Guide
-
-### Upgrading from beta.11 → beta.12+
-
-**The easiest way:**
-```bash
-npx flikkui init
+```css
+:root {
+  /* Heights */
+  --form-min-h-sm: 2rem;
+  --form-min-h-md: 2.5rem;
+  --form-min-h-lg: 3rem;
+
+  /* Horizontal padding */
+  --form-px-sm: 0.75rem;
+  --form-px-md: 0.875rem;
+  --form-px-lg: 1rem;
+
+  /* Vertical padding */
+  --form-py-sm: 0.5rem;
+  --form-py-md: 0.625rem;
+  --form-py-lg: 0.75rem;
+
+  /* Font sizes */
+  --form-text-sm: 0.75rem;
+  --form-text-md: 0.875rem;
+  --form-text-lg: 1rem;
+}
 ```
 
-**Manual upgrade:**
+Button, badge, segmented, and other component variables inherit from these form defaults but can be overridden individually (e.g. `--button-radius`, `--badge-radius`, `--button-px-*`).
 
-1. **Install peer dependencies:**
-```bash
-npm install @heroicons/react clsx motion tailwind-merge tailwindcss react-markdown react-syntax-highlighter remark-gfm three
-```
+### Dark Mode
 
-2. **No code changes needed!** ✅
-```tsx
-import { Button } from 'flikkui' // Still works
-import 'flikkui/styles.css'      // Still works
-```
+Add the `dark` class to your `<html>` or any parent container. All components adapt automatically:
 
-3. **Optional: Use category imports for better tree-shaking:**
-```tsx
-import { Button } from 'flikkui/core'  // Smaller bundles
+```html
+<html class="dark">
+  <!-- dark mode active -->
+</html>
 ```
 
-### First Time Installing?
+The library ships with sensible dark mode defaults. To customize dark mode colors, override variables inside `.dark`:
 
-Just run:
-```bash
-npm install flikkui@beta
-npx flikkui init
+```css
+.dark {
+  --color-background: oklch(14.5% 0 0);
+  --color-border: oklch(30% 0 0);
+  --color-primary: var(--color-primary-400);
+  --color-text-primary: var(--color-neutral-50);
+  --color-text-secondary: var(--color-neutral-400);
+}
 ```
 
-## 💡 Philosophy
-
-Flikkui follows the **shadcn approach**:
-- ✅ Components provide sensible defaults
-- ✅ **className overrides always take precedence**
-- ✅ Full TypeScript support with excellent DX
-- ✅ Copy-paste friendly - customize anything
-- ✅ CSS variables for consistent theming
-- ✅ Tree-shaking optimized - only bundle what you use
-
-## 🛠️ Tech Stack
-
-- **React 18+** with TypeScript (strict mode)
-- **Tailwind CSS v4** with CSS variables
-- **Framer Motion 12+** for smooth animations
-- **Heroicons** for consistent iconography
-- **Accessibility-first** - WCAG 2.1 AA compliance built-in
-- **Optimized build** - Rollup with ESM output and preserveModules
-
-## ⚡ Performance
-
-Flikkui is optimized for production:
-
-- **Tree-shaking ready** - Only bundle components you use
-- **Small package size** - ~800KB unpacked (no bundled dependencies)
-- **Zero runtime overhead** - CSS variables, no theme providers
-- **Optimized animations** - Framer Motion with reduced motion support
-- **Code splitting** - Category-level exports for granular imports
-
-**Real-world bundle sizes (production build, gzipped):**
-- Single component (Button): ~15-20KB
-- Small app (5 components): ~40-60KB
-- Medium app (20 components): ~100-150KB
-
-## 🎯 Browser Support
+### Full Variable Reference
 
-- Chrome (latest)
-- Firefox (latest)
-- Safari (latest)
-- Edge (latest)
+See [`src/styles/theme.css`](src/styles/theme.css) for the complete list of available CSS variables.
 
-**Note:** Requires browsers with CSS custom properties support.
+## Documentation
 
-## 📖 Documentation
+This package is currently in beta. Full documentation coming soon.
 
-Comprehensive documentation and resources:
+## License
 
-- 📚 **[Documentation](https://flikkui.dev)** - Complete API reference
-- 🎨 **[Storybook](https://storybook.flikkui.dev)** - Interactive component demos
-- 🚀 **[Getting Started Guide](./docs/INSTALLATION.md)** - Detailed setup instructions
-- 🛠️ **[CLI Documentation](./docs/CLI.md)** - CLI command reference
-- 🎭 **[Theming Guide](https://flikkui.dev/theming)** - Customization and CSS variables
-- 🔄 **[Migration Guides](https://flikkui.dev/migrations)** - Version upgrade guides
-
-## 🤝 Contributing
-
-We welcome contributions! Here's how you can help:
-
-- 🐛 **Report bugs** - [Create an issue](https://github.com/yourusername/flikkui/issues)
-- 💡 **Suggest features** - [Start a discussion](https://github.com/yourusername/flikkui/discussions)
-- 📝 **Improve docs** - Submit documentation PRs
-- 🎨 **Add components** - Contribute new components
-
-Please read our [Contributing Guidelines](./CONTRIBUTING.md) before submitting PRs.
-
-## 📄 License
-
-**MIT License** - Free to use in personal and commercial projects.
-
-See [LICENSE](./LICENSE) for full details.
+MIT License - see LICENSE file for details.
 
 ---
 
-## 🌟 Show Your Support
-
-If you find Flikkui helpful, please consider:
-
-- ⭐ **Star this repository** on GitHub
-- 🐦 **Share on Twitter** with #Flikkui
-- 📝 **Write a blog post** about your experience
-- 💬 **Join our community** discussions
-
----
-
-## 🔗 Links
-
-- **NPM Package:** [npmjs.com/package/flikkui](https://www.npmjs.com/package/flikkui)
-- **Documentation:** [flikkui.dev](https://flikkui.dev)
-- **GitHub:** [github.com/yourusername/flikkui](https://github.com/yourusername/flikkui)
-- **Issues:** [github.com/yourusername/flikkui/issues](https://github.com/yourusername/flikkui/issues)
-- **Changelog:** [CHANGELOG.md](./CHANGELOG.md)
-
----
-
-<p align="center">
-  Built with ❤️ by <a href="https://espranza.net">Espranza Innovations</a>
-</p>
-
-<p align="center">
-  <strong>Flikkui</strong> - Modern React Components for Modern Apps
-</p>
+Built by Espranza Innovations