@7onic-ui/react 0.3.5 → 0.3.7

package/llms.txt

@@ -8,6 +8,7 @@ Single source of truth — design tokens to code. Use this to build any React se
 - Documentation: https://7onic.design
 - npm: `@7onic-ui/react` (components) + `@7onic-ui/tokens` (design tokens)
 - For tokens-only guide, see: https://7onic.design/llms.txt
+- MCP server (token search / component catalog / validate_code): https://7onic.design/components/mcp — on Claude Code: `claude plugin marketplace add itonys/7onic && claude plugin install 7onic-design@7onic`
 
 ---
 
@@ -27,92 +28,29 @@ Before writing any code, present this checklist and wait for answers:
 
 **If the user answers in natural language** (e.g., "Make me a dashboard with dark mode, English only"), extract the answers from their message. **If any item is missing, ask a follow-up question for the missing items only.** Do not proceed until all 5 items are answered.
 
-### Step 2: Execute full setup (all at once, do not skip any)
+### Step 2: Install / Setup
 
-After receiving answers, execute ALL of the following in order. Every step is mandatory.
+⚠️ **DO NOT GUESS** — install procedures evolve with each Tailwind / Next / Vite version. Before writing any code, AI **MUST** fetch the live pages below and follow their instructions verbatim:
 
-**2-1. Install packages (skip if already installed):**
-```bash
-npm install @7onic-ui/react @7onic-ui/tokens lucide-react
-```
-> Check package.json first. If packages are already listed in dependencies, skip this step.
-
-**2-2. Create or update globals.css with token imports:**
-
-**How to detect Tailwind version:**
-- `tailwind.config.js` (or `.ts`) exists → **v3**
-- No config file → **v4** (uses CSS-based configuration)
-
-**New project (Tailwind v4):**
-```css
-/* globals.css (Next.js) or src/index.css (Vite) — ALL imports are required, do not skip any */
-@import "tailwindcss";
-@import "@7onic-ui/tokens/css/variables.css";
-@import "@7onic-ui/tokens/css/themes/light.css";
-@import "@7onic-ui/tokens/css/themes/dark.css";    /* omit ONLY if dark mode = no */
-@import "@7onic-ui/tokens/tailwind/v4-theme.css";
-```
-
-**Existing project with Tailwind v3** (detect from tailwind.config.js):
-```css
-/* globals.css */
-@import '@7onic-ui/tokens/css/variables.css';
-@import '@7onic-ui/tokens/css/themes/light.css';
-@import '@7onic-ui/tokens/css/themes/dark.css';    /* omit ONLY if dark mode = no */
-@tailwind base;
-@tailwind components;
-@tailwind utilities;
-```
-```js
-// tailwind.config.js — add preset
-const preset = require('@7onic-ui/tokens/tailwind/v3-preset')
-module.exports = {
-  presets: [preset],
-  content: [
-    './src/**/*.{js,ts,jsx,tsx}',
-    './node_modules/@7onic-ui/react/dist/**/*.{js,mjs}',
-  ],
-}
-```
-
-**2-3. Vite users only — clean up `src/index.css`:**
+- **Official install page (SSOT)**: https://7onic.design/components/installation
+- **Tailwind CSS official**: https://tailwindcss.com/docs/installation
 
-Vite's default template generates CSS that overrides 7onic token styles. Two paths:
+The install instructions are intentionally **not duplicated in this file**. Setup details (packages, `tailwind.config.js`, `vite.config.ts`, `postcss.config.mjs`, `globals.css` patterns, framework default cleanup, layer wrap tips, etc.) are version-sensitive and change frequently — always defer to the live documentation above.
 
-- **CLI path (`npx 7onic init`) — recommended**: auto-handles all cleanup below, plus injects `@import "tailwindcss"` (v4), configures `@/` path alias (patches `tsconfig.app.json` + `vite.config.ts`, installs `@types/node`), and `npx 7onic add` auto-injects `@source "./components/ui"`. Prompts user, creates `.bak` backup.
-- **npm-only path (manual)**: delete the following blocks from `src/index.css`:
-  - `:root { font-family: system-ui, ... }` block
-  - `body { display: flex; place-items: center; ... }` block
-  - `button { background-color: #1a1a1a; ... }` block and all other element-level rules (`a { color: #646cff }`, etc.)
-  - `@media (prefers-color-scheme: light) { ... }` block
+Apply user's answers from Step 1 after the install page steps are complete:
+- Dark mode = yes → implement dark mode toggle (see below in this file)
+- Custom font → load via `next/font/google` (Next.js) or Fontsource / CDN (Vite)
+- Japanese / Korean locale → load Noto Sans JP / KR
 
-  After deletion, `src/index.css` should contain only the token imports added in step 2-2. For v4 also add `@import "tailwindcss"` at the top, and configure `@/` alias manually.
+⛔ **Do NOT proceed to Step 3 until install page setup is verified.**
 
-**2-4. Apply user's answers:**
-
-- Dark mode = yes → implement dark mode toggle (see below)
-- Custom font → load font:
-  - **Next.js**: use `next/font/google`
-  - **Vite / Remix**: use Fontsource (`npm install @fontsource/inter`, then `import '@fontsource/inter/400.css'` in `src/main.tsx`) or Google Fonts CDN
-  - Then set `--font-family-sans` in CSS
-- Locale includes Japanese → load Noto Sans JP font
-  - Fontsource: `npm install @fontsource/noto-sans-jp` → import in `src/main.tsx` (Vite) or `app/layout.tsx` (Next.js)
-  - CDN: Google Fonts link tag in `index.html`
-- Locale includes Korean → load Noto Sans KR font
-  - Fontsource: `npm install @fontsource/noto-sans-kr` → import in `src/main.tsx` (Vite) or `app/layout.tsx` (Next.js)
-  - CDN: Google Fonts link tag in `index.html`
-
-**2-5. Verify setup is complete before writing any UI code:**
-- [ ] Packages installed (@7onic-ui/react, @7onic-ui/tokens, lucide-react)
-- [ ] globals.css / src/index.css has ALL required imports in correct order
-- [ ] (Vite only) Vite template CSS blocks deleted from src/index.css
-- [ ] Dark mode toggle (if selected)
-- [ ] Font loaded (if custom)
-- [ ] CJK fonts loaded (if applicable)
+### Icon Import Pattern (lucide-react)
 
-⛔ **Do NOT proceed to Step 3 until all checks pass.**
+⚠️ **`lucide-react` is NOT a 7onic dependency.** 7onic components themselves use inline SVG. Install separately if you want to use lucide icons in your app code:
 
-### Icon Import Pattern (lucide-react)
+```bash
+npm install lucide-react
+```
 
 ```tsx
 // ✅ Official pattern — no suffix
@@ -131,7 +69,9 @@ import { Badge as BadgeIcon } from 'lucide-react'
 Place `<Toaster />` once in your root layout file. Without this, `toast()` calls will not render.
 
 ```tsx
-import { Toaster } from '@7onic-ui/react'// In your root layout (e.g., app/layout.tsx)
+import { Toaster } from '@7onic-ui/react'
+
+// In your root layout (e.g., app/layout.tsx)
 <body>
   {children}
   <Toaster position="bottom-right" />
@@ -248,7 +188,9 @@ style={{ color: '#333', padding: '20px' }}
 w-4 h-4, w-5 h-5   → icon-sm, icon-md
 
 // ❌ Radix direct import
-import * as Dialog from '@radix-ui/react-dialog'   → import { Badge, Button, Card, Input, Table } from '@7onic-ui/react'// ❌ Unnecessary component wrappers
+import * as Dialog from '@radix-ui/react-dialog'   → import { Badge, Button, Card, Input, Table } from '@7onic-ui/react'
+
+// ❌ Unnecessary component wrappers
 function MyButton(props) { return <Button {...props} /> }   → Use Button directly
 ```
 
@@ -402,7 +344,9 @@ import { Button, Card, Input, toast } from '@7onic-ui/react'
 All components use Named imports. Works in every environment (Next.js App Router RSC, Client Components, Pages Router, Vite, CRA, CJS).
 
 ```tsx
-import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from '@7onic-ui/react'<Card>
+import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from '@7onic-ui/react'
+
+<Card>
   <CardHeader>
     <CardTitle>Title</CardTitle>
     <CardDescription>Description</CardDescription>
@@ -426,7 +370,7 @@ Badge, Button, ButtonGroup, Checkbox, Divider, IconButton, Input, Progress, Skel
 
 ---
 
-# ═══ SECTION 3: ALL COMPONENTS (42) ═══
+# ═══ SECTION 3: ALL COMPONENTS (41) ═══
 
 ---
 
@@ -435,7 +379,9 @@ Badge, Button, ButtonGroup, Checkbox, Divider, IconButton, Input, Progress, Skel
 ### Button
 
 ```tsx
-import { Button } from '@7onic-ui/react'<Button variant="solid" color="primary" size="default">Submit</Button>
+import { Button } from '@7onic-ui/react'
+
+<Button variant="solid" color="primary" size="default">Submit</Button>
 <Button variant="outline" color="default" leftIcon={<Icon />}>Cancel</Button>
 <Button loading>Processing...</Button>
 <Button variant="link" color="primary">Learn more</Button>
@@ -464,7 +410,9 @@ import { Button } from '@7onic-ui/react'<Button variant="solid" color="primary"
 ### IconButton
 
 ```tsx
-import { IconButton } from '@7onic-ui/react'<IconButton variant="ghost" size="default" aria-label="Settings">
+import { IconButton } from '@7onic-ui/react'
+
+<IconButton variant="ghost" size="default" aria-label="Settings">
   <SettingsIcon />
 </IconButton>
 ```
@@ -487,7 +435,9 @@ import { IconButton } from '@7onic-ui/react'<IconButton variant="ghost" size="de
 ### ButtonGroup
 
 ```tsx
-import { Button, ButtonGroup } from '@7onic-ui/react'<ButtonGroup variant="outline" size="default" attached>
+import { Button, ButtonGroup } from '@7onic-ui/react'
+
+<ButtonGroup variant="outline" size="default" attached>
   <Button>Left</Button>
   <Button>Center</Button>
   <Button>Right</Button>
@@ -511,7 +461,9 @@ Provides context — child Buttons inherit variant/size/radius automatically.
 ### Input
 
 ```tsx
-import { Input } from '@7onic-ui/react'<Input placeholder="Email" size="default" />
+import { Input } from '@7onic-ui/react'
+
+<Input placeholder="Email" size="default" />
 <Input variant="filled" leftIcon={<SearchIcon />} />
 <Input error rightIcon={<AlertIcon />} />
 ```
@@ -533,7 +485,9 @@ import { Input } from '@7onic-ui/react'<Input placeholder="Email" size="default"
 ### Textarea
 
 ```tsx
-import { Textarea } from '@7onic-ui/react'<Textarea placeholder="Message" rows={4} resize="vertical" />
+import { Textarea } from '@7onic-ui/react'
+
+<Textarea placeholder="Message" rows={4} resize="vertical" />
 ```
 
 | Prop | Type | Default | Description |
@@ -551,7 +505,9 @@ import { Textarea } from '@7onic-ui/react'<Textarea placeholder="Message" rows={
 ### Select
 
 ```tsx
-import { Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectTrigger, SelectValue } from '@7onic-ui/react'<Select>
+import { Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectTrigger, SelectValue } from '@7onic-ui/react'
+
+<Select>
   <SelectTrigger>
     <SelectValue placeholder="Choose option" />
   </SelectTrigger>
@@ -581,7 +537,9 @@ import { Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectTrig
 ### DropdownMenu
 
 ```tsx
-import { Button, DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuSeparator, DropdownMenuTrigger } from '@7onic-ui/react'<DropdownMenu>
+import { Button, DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuSeparator, DropdownMenuTrigger } from '@7onic-ui/react'
+
+<DropdownMenu>
   <DropdownMenuTrigger asChild>
     <Button variant="outline">Options</Button>
   </DropdownMenuTrigger>
@@ -601,14 +559,16 @@ import { Button, DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMe
 | flush | `boolean` | `false` | Full-width items (no padding) |
 | sideOffset | `number` | `4` | Gap from trigger |
 
-**Sub-components:** DropdownMenu.Trigger, DropdownMenu.Content, DropdownMenu.Item, DropdownMenu.CheckboxItem, DropdownMenu.RadioItem, DropdownMenu.Label, DropdownMenu.Separator, DropdownMenu.Group, DropdownMenu.Sub, DropdownMenu.SubTrigger, DropdownMenu.SubContent, DropdownMenu.Shortcut
+**Sub-components:** DropdownMenu.Trigger, DropdownMenu.Content, DropdownMenu.Item, DropdownMenu.CheckboxItem, DropdownMenu.RadioGroup, DropdownMenu.RadioItem, DropdownMenu.Label, DropdownMenu.Separator, DropdownMenu.Group, DropdownMenu.Sub, DropdownMenu.SubTrigger, DropdownMenu.SubContent, DropdownMenu.Shortcut
 
 ---
 
 ### Checkbox
 
 ```tsx
-import { Checkbox } from '@7onic-ui/react'<Checkbox label="Accept terms" />
+import { Checkbox } from '@7onic-ui/react'
+
+<Checkbox label="Accept terms" />
 <Checkbox size="lg" color="primary" checked />
 <Checkbox checked="indeterminate" />
 ```
@@ -630,7 +590,9 @@ import { Checkbox } from '@7onic-ui/react'<Checkbox label="Accept terms" />
 ### RadioGroup
 
 ```tsx
-import { RadioGroup, RadioGroupItem } from '@7onic-ui/react'<RadioGroup defaultValue="a">
+import { RadioGroup, RadioGroupItem } from '@7onic-ui/react'
+
+<RadioGroup defaultValue="a">
   <RadioGroupItem value="a" label="Option A" />
   <RadioGroupItem value="b" label="Option B" />
   <RadioGroupItem value="c" label="Option C" disabled />
@@ -654,7 +616,9 @@ import { RadioGroup, RadioGroupItem } from '@7onic-ui/react'<RadioGroup defaultV
 ### Switch
 
 ```tsx
-import { Switch } from '@7onic-ui/react'<Switch label="Notifications" />
+import { Switch } from '@7onic-ui/react'
+
+<Switch label="Notifications" />
 <Switch size="lg" color="primary" defaultChecked />
 <Switch startLabel="Off" endLabel="On" />
 ```
@@ -679,7 +643,9 @@ import { Switch } from '@7onic-ui/react'<Switch label="Notifications" />
 ### Toggle
 
 ```tsx
-import { Toggle } from '@7onic-ui/react'<Toggle variant="default" aria-label="Bold">
+import { Toggle } from '@7onic-ui/react'
+
+<Toggle variant="default" aria-label="Bold">
   <BoldIcon />
 </Toggle>
 <Toggle variant="outline" pressed>Active</Toggle>
@@ -702,7 +668,9 @@ import { Toggle } from '@7onic-ui/react'<Toggle variant="default" aria-label="Bo
 ### ToggleGroup
 
 ```tsx
-import { ToggleGroup, ToggleGroupItem } from '@7onic-ui/react'<ToggleGroup type="single" defaultValue="center">
+import { ToggleGroup, ToggleGroupItem } from '@7onic-ui/react'
+
+<ToggleGroup type="single" defaultValue="center">
   <ToggleGroupItem value="left"><AlignLeftIcon /></ToggleGroupItem>
   <ToggleGroupItem value="center"><AlignCenterIcon /></ToggleGroupItem>
   <ToggleGroupItem value="right"><AlignRightIcon /></ToggleGroupItem>
@@ -728,7 +696,9 @@ import { ToggleGroup, ToggleGroupItem } from '@7onic-ui/react'<ToggleGroup type=
 ### Segmented
 
 ```tsx
-import { Segmented, SegmentedItem } from '@7onic-ui/react'<Segmented defaultValue="all">
+import { Segmented, SegmentedItem } from '@7onic-ui/react'
+
+<Segmented defaultValue="all">
   <SegmentedItem value="all">All</SegmentedItem>
   <SegmentedItem value="active">Active</SegmentedItem>
   <SegmentedItem value="inactive">Inactive</SegmentedItem>
@@ -753,7 +723,9 @@ import { Segmented, SegmentedItem } from '@7onic-ui/react'<Segmented defaultValu
 ### Slider
 
 ```tsx
-import { Slider } from '@7onic-ui/react'<Slider defaultValue={[50]} showTooltip="auto" />
+import { Slider } from '@7onic-ui/react'
+
+<Slider defaultValue={[50]} showTooltip="auto" />
 <Slider defaultValue={[20, 80]} color="primary" />
 ```
 
@@ -778,7 +750,9 @@ import { Slider } from '@7onic-ui/react'<Slider defaultValue={[50]} showTooltip=
 ### Field (Form Wrapper)
 
 ```tsx
-import { Field, FieldCharCount, FieldError, FieldLabel, Input, Textarea } from '@7onic-ui/react'<Field error="Invalid email">
+import { Field, FieldCharCount, FieldError, FieldLabel, Input, Textarea } from '@7onic-ui/react'
+
+<Field error="Invalid email">
   <FieldLabel required>Email</FieldLabel>
   <Input placeholder="you@example.com" />
   <FieldError />
@@ -807,7 +781,9 @@ import { Field, FieldCharCount, FieldError, FieldLabel, Input, Textarea } from '
 ### Avatar
 
 ```tsx
-import { Avatar, AvatarFallback, AvatarGroup, AvatarImage } from '@7onic-ui/react'<Avatar size="default">
+import { Avatar, AvatarFallback, AvatarGroup, AvatarImage } from '@7onic-ui/react'
+
+<Avatar size="default">
   <AvatarImage src="/photo.jpg" alt="User" />
   <AvatarFallback name="John Doe" colorized />
 </Avatar>
@@ -845,7 +821,9 @@ import { Avatar, AvatarFallback, AvatarGroup, AvatarImage } from '@7onic-ui/reac
 ### Badge
 
 ```tsx
-import { Badge } from '@7onic-ui/react'<Badge variant="solid" color="primary">New</Badge>
+import { Badge } from '@7onic-ui/react'
+
+<Badge variant="solid" color="primary">New</Badge>
 <Badge variant="subtle" color="success" dot>Active</Badge>
 <Badge variant="outline" removable onRemove={() => {}}>Tag</Badge>
 ```
@@ -855,7 +833,7 @@ import { Badge } from '@7onic-ui/react'<Badge variant="solid" color="primary">Ne
 | variant | `'solid' \| 'subtle' \| 'outline'` | `'subtle'` | Visual style |
 | color | `'default' \| 'primary' \| 'success' \| 'warning' \| 'error' \| 'info'` | `'default'` | Color scheme |
 | size | `'sm' \| 'default' \| 'lg'` | `'default'` | Badge size |
-| radius | `'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | `'full'` | Border radius |
+| radius | `'sm' \| 'base' \| 'md' \| 'lg' \| 'full'` | `'full'` | Border radius |
 | icon | `ReactNode` | — | Leading icon |
 | dot | `boolean` | `false` | Status dot indicator |
 | removable | `boolean` | `false` | Shows remove button |
@@ -867,7 +845,9 @@ import { Badge } from '@7onic-ui/react'<Badge variant="solid" color="primary">Ne
 ### Card
 
 ```tsx
-import { Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardImage, CardTitle, IconButton } from '@7onic-ui/react'<Card variant="default" interactive>
+import { Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardImage, CardTitle, IconButton } from '@7onic-ui/react'
+
+<Card variant="default" interactive>
   <CardImage src="/cover.jpg" overlay overlayOpacity={40} />
   <CardHeader>
     <CardTitle icon={<StarIcon />}>Featured</CardTitle>
@@ -900,7 +880,9 @@ import { Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader,
 ### Table
 
 ```tsx
-import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '@7onic-ui/react'<Table variant="default" stickyHeader>
+import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '@7onic-ui/react'
+
+<Table variant="default" stickyHeader>
   <TableHeader>
     <TableRow>
       <TableHead sortable sortDirection="asc" onSort={() => {}}>Name</TableHead>
@@ -947,7 +929,9 @@ import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '@
 ### Tabs
 
 ```tsx
-import { Tabs, TabsContent, TabsList, TabsTrigger } from '@7onic-ui/react'<Tabs defaultValue="tab1">
+import { Tabs, TabsContent, TabsList, TabsTrigger } from '@7onic-ui/react'
+
+<Tabs defaultValue="tab1">
   <TabsList variant="line" size="default">
     <TabsTrigger value="tab1">Tab 1</TabsTrigger>
     <TabsTrigger value="tab2">Tab 2</TabsTrigger>
@@ -972,7 +956,9 @@ import { Tabs, TabsContent, TabsList, TabsTrigger } from '@7onic-ui/react'<Tabs
 ### Accordion
 
 ```tsx
-import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from '@7onic-ui/react'<Accordion type="single" collapsible defaultValue="item-1">
+import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from '@7onic-ui/react'
+
+<Accordion type="single" collapsible defaultValue="item-1">
   <AccordionItem value="item-1">
     <AccordionTrigger>Section 1</AccordionTrigger>
     <AccordionContent>Content 1</AccordionContent>
@@ -999,7 +985,9 @@ import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from '@7
 ### Divider
 
 ```tsx
-import { Divider } from '@7onic-ui/react'<Divider />
+import { Divider } from '@7onic-ui/react'
+
+<Divider />
 <Divider variant="dashed" color="muted" />
 <Divider label="OR" labelPosition="center" />
 <Divider orientation="vertical" />
@@ -1021,7 +1009,9 @@ import { Divider } from '@7onic-ui/react'<Divider />
 ### Modal
 
 ```tsx
-import { Button, Modal, ModalBody, ModalClose, ModalContent, ModalDescription, ModalFooter, ModalHeader, ModalOverlay, ModalPortal, ModalTitle, ModalTrigger } from '@7onic-ui/react'<Modal>
+import { Button, Modal, ModalBody, ModalClose, ModalContent, ModalDescription, ModalFooter, ModalHeader, ModalOverlay, ModalPortal, ModalTitle, ModalTrigger } from '@7onic-ui/react'
+
+<Modal>
   <ModalTrigger asChild>
     <Button>Open Modal</Button>
   </ModalTrigger>
@@ -1057,7 +1047,9 @@ import { Button, Modal, ModalBody, ModalClose, ModalContent, ModalDescription, M
 ### AlertModal
 
 ```tsx
-import { AlertModal, AlertModalAction, AlertModalBody, AlertModalCancel, AlertModalContent, AlertModalDescription, AlertModalFooter, AlertModalHeader, AlertModalOverlay, AlertModalPortal, AlertModalTitle, AlertModalTrigger, Button } from '@7onic-ui/react'<AlertModal>
+import { AlertModal, AlertModalAction, AlertModalBody, AlertModalCancel, AlertModalContent, AlertModalDescription, AlertModalFooter, AlertModalHeader, AlertModalOverlay, AlertModalPortal, AlertModalTitle, AlertModalTrigger, Button } from '@7onic-ui/react'
+
+<AlertModal>
   <AlertModalTrigger asChild>
     <Button color="destructive">Delete</Button>
   </AlertModalTrigger>
@@ -1091,7 +1083,9 @@ import { AlertModal, AlertModalAction, AlertModalBody, AlertModalCancel, AlertMo
 ### Drawer
 
 ```tsx
-import { Button, Drawer, DrawerBody, DrawerClose, DrawerContent, DrawerFooter, DrawerHeader, DrawerOverlay, DrawerPortal, DrawerTitle, DrawerTrigger } from '@7onic-ui/react'<Drawer>
+import { Button, Drawer, DrawerBody, DrawerClose, DrawerContent, DrawerFooter, DrawerHeader, DrawerOverlay, DrawerPortal, DrawerTitle, DrawerTrigger } from '@7onic-ui/react'
+
+<Drawer>
   <DrawerTrigger asChild>
     <Button>Open Drawer</Button>
   </DrawerTrigger>
@@ -1123,7 +1117,9 @@ import { Button, Drawer, DrawerBody, DrawerClose, DrawerContent, DrawerFooter, D
 ### Tooltip
 
 ```tsx
-import { Button, Tooltip, TooltipArrow, TooltipContent, TooltipPortal, TooltipProvider, TooltipTrigger } from '@7onic-ui/react'<TooltipProvider>
+import { Button, Tooltip, TooltipArrow, TooltipContent, TooltipPortal, TooltipProvider, TooltipTrigger } from '@7onic-ui/react'
+
+<TooltipProvider>
   <Tooltip>
     <TooltipTrigger asChild>
       <Button>Hover me</Button>
@@ -1158,7 +1154,9 @@ import { Button, Tooltip, TooltipArrow, TooltipContent, TooltipPortal, TooltipPr
 ### Popover
 
 ```tsx
-import { Button, Popover, PopoverArrow, PopoverContent, PopoverPortal, PopoverTrigger } from '@7onic-ui/react'<Popover>
+import { Button, Popover, PopoverArrow, PopoverContent, PopoverPortal, PopoverTrigger } from '@7onic-ui/react'
+
+<Popover>
   <PopoverTrigger asChild>
     <Button variant="outline">Open</Button>
   </PopoverTrigger>
@@ -1188,7 +1186,9 @@ import { Button, Popover, PopoverArrow, PopoverContent, PopoverPortal, PopoverTr
 ### Alert
 
 ```tsx
-import { Alert, AlertDescription, AlertTitle } from '@7onic-ui/react'<Alert color="success" closable onClose={() => {}}>
+import { Alert, AlertDescription, AlertTitle } from '@7onic-ui/react'
+
+<Alert color="success" closable onClose={() => {}}>
   <AlertTitle>Success</AlertTitle>
   <AlertDescription>Operation completed.</AlertDescription>
 </Alert>
@@ -1216,7 +1216,9 @@ import { Alert, AlertDescription, AlertTitle } from '@7onic-ui/react'<Alert colo
 ### Toast (Imperative API)
 
 ```tsx
-import { Toaster, toast } from '@7onic-ui/react'// 1. Add Toaster provider to your app layout (once)
+import { Toaster, toast } from '@7onic-ui/react'
+
+// 1. Add Toaster provider to your app layout (once)
 <Toaster position="bottom-right" />
 
 // 2. Call toast() anywhere
@@ -1264,7 +1266,9 @@ toast.dismiss()      // Dismiss all
 ### Progress
 
 ```tsx
-import { Progress } from '@7onic-ui/react'<Progress value={65} showValue />
+import { Progress } from '@7onic-ui/react'
+
+<Progress value={65} showValue />
 <Progress type="circular" value={75} color="primary" />
 <Progress variant="striped" animated value={50} />
 ```
@@ -1286,7 +1290,9 @@ import { Progress } from '@7onic-ui/react'<Progress value={65} showValue />
 ### Spinner
 
 ```tsx
-import { Spinner } from '@7onic-ui/react'<Spinner />
+import { Spinner } from '@7onic-ui/react'
+
+<Spinner />
 <Spinner variant="dots" size="lg" color="primary" />
 <Spinner variant="bars" speed="slow" />
 <Spinner variant="orbit" orbitStyle="morph" />
@@ -1306,7 +1312,9 @@ import { Spinner } from '@7onic-ui/react'<Spinner />
 ### Skeleton
 
 ```tsx
-import { Skeleton } from '@7onic-ui/react'<Skeleton variant="text" count={3} />
+import { Skeleton } from '@7onic-ui/react'
+
+<Skeleton variant="text" count={3} />
 <Skeleton variant="circular" width={48} height={48} />
 <Skeleton variant="rectangular" width="100%" height={200} />
 
@@ -1334,7 +1342,9 @@ import { Skeleton } from '@7onic-ui/react'<Skeleton variant="text" count={3} />
 ### Breadcrumb
 
 ```tsx
-import { Breadcrumb, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator } from '@7onic-ui/react'<Breadcrumb>
+import { Breadcrumb, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator } from '@7onic-ui/react'
+
+<Breadcrumb>
   <BreadcrumbList>
     <BreadcrumbItem>
       <BreadcrumbLink href="/">Home</BreadcrumbLink>
@@ -1366,7 +1376,9 @@ import { Breadcrumb, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbP
 ### Pagination
 
 ```tsx
-import { Pagination, PaginationContent, PaginationItems, PaginationNext, PaginationPrevious } from '@7onic-ui/react'{/* Quick mode — withControls (default: true), withEdges (default: false) */}
+import { Pagination, PaginationContent, PaginationItems, PaginationNext, PaginationPrevious } from '@7onic-ui/react'
+
+{/* Quick mode — withControls (default: true), withEdges (default: false) */}
 <Pagination total={10} defaultValue={1} />
 <Pagination total={10} defaultValue={1} withEdges />
 <Pagination total={10} defaultValue={1} withControls={false} />
@@ -1405,7 +1417,9 @@ import { Pagination, PaginationContent, PaginationItems, PaginationNext, Paginat
 ### NavigationMenu
 
 ```tsx
-import { NavigationMenu, NavigationMenuContent, NavigationMenuGroup, NavigationMenuItem, NavigationMenuLink, NavigationMenuList, NavigationMenuTrigger, NavigationMenuViewport } from '@7onic-ui/react'{/* Horizontal (header) */}
+import { NavigationMenu, NavigationMenuContent, NavigationMenuGroup, NavigationMenuItem, NavigationMenuLink, NavigationMenuList, NavigationMenuTrigger, NavigationMenuViewport } from '@7onic-ui/react'
+
+{/* Horizontal (header) */}
 <NavigationMenu orientation="horizontal">
   <NavigationMenuList>
     <NavigationMenuItem>
@@ -1470,7 +1484,9 @@ import { NavigationMenu, NavigationMenuContent, NavigationMenuGroup, NavigationM
 All chart types use the Chart namespace:
 
 ```tsx
-import { ChartArea, ChartBar, ChartLegend, ChartLegendContent, ChartLine, ChartPie, ChartTooltip, ChartTooltipContent, ChartXAxis, ChartYAxis } from '@7onic-ui/react/chart'const chartConfig = {
+import { Chart, ChartArea, ChartBar, ChartLegend, ChartLegendContent, ChartLine, ChartPie, ChartTooltip, ChartTooltipContent, ChartXAxis, ChartYAxis } from '@7onic-ui/react/chart'
+
+const chartConfig = {
   revenue: { label: 'Revenue', color: 'var(--color-chart-1)' },
   profit: { label: 'Profit', color: 'var(--color-chart-2)' },
 }
@@ -1570,7 +1586,9 @@ type ChartConfig = {
 ### MetricCard
 
 ```tsx
-import { MetricCard, MetricCardDescription, MetricCardHeader, MetricCardSymbol, MetricCardTitle, MetricCardTrend, MetricCardValue } from '@7onic-ui/react'<MetricCard>
+import { MetricCard, MetricCardDescription, MetricCardHeader, MetricCardSymbol, MetricCardTitle, MetricCardTrend, MetricCardValue } from '@7onic-ui/react'
+
+<MetricCard>
   <MetricCardHeader>
     <MetricCardTitle>Revenue</MetricCardTitle>
     <MetricCardSymbol><DollarIcon /></MetricCardSymbol>
@@ -1599,176 +1617,439 @@ import { MetricCard, MetricCardDescription, MetricCardHeader, MetricCardSymbol,
 
 ---
 
-# ═══ SECTION 4: COMPONENT USAGE GUIDE ═══
-
-## Component Selection
-
-Before creating custom UI, check if 7onic already has it:
-
-| Need | Use This Component |
-|---|---|
-| Action trigger | Button, IconButton |
-| Text input | Input (single line), Textarea (multi line) |
-| Selection (one) | RadioGroup, Select, Segmented |
-| Selection (many) | Checkbox, ToggleGroup |
-| Boolean toggle | Switch, Toggle, Checkbox |
-| Container | Card |
-| Data table | Table |
-| Tabs | Tabs |
-| Collapsible | Accordion |
-| Dialog | Modal |
-| Side panel | Drawer |
-| Hint text | Tooltip |
-| Rich hint | Popover |
-| Notification | Toast (imperative), Alert (inline) |
-| Loading | Spinner (indeterminate), Progress (determinate), Skeleton (placeholder) |
-| Navigation | Breadcrumb, Pagination, NavigationMenu |
-| Data visualization | Chart (Line/Area/Bar/Pie), MetricCard |
-| Metric display | MetricCard |
-| Tag / chip | Badge (with `removable`) |
-| Avatar | Avatar |
-| Separator | Divider |
-
-**If the component exists, use it.** Don't build custom versions with HTML + classes.
-
----
+## AI Components
 
-## Import Pattern
+### TypingIndicator
 
 ```tsx
-// ✅ Single import path
-import { Button, Card, Input, toast } from '@7onic-ui/react'
-
-// ✅ Chart components use a separate entry point (recharts is optional)
-import { ChartBar } from '@7onic-ui/react/chart'
-
-// ❌ Never import from internal paths
-import { Button } from '@7onic-ui/react/components/button'  // WRONG
+import { TypingIndicator } from '@7onic-ui/react'
 
-// ❌ Never import Radix directly
-import * as Dialog from '@radix-ui/react-dialog'  // WRONG → use Modal
-```
-
----
-
-## Compound Component Structure
+{/* Default — dots, muted, default size */}
+<TypingIndicator />
 
-Compound components have **required sub-components**. Missing them causes errors or broken UI.
+{/* Cursor variant */}
+<TypingIndicator variant="cursor" />
 
-**Modal — required structure:**
-```tsx
-<Modal>
-  <ModalTrigger>...</ModalTrigger>
-  <ModalPortal>           {/* ← Required for correct z-index */}
-    <ModalOverlay />      {/* ← Required for backdrop */}
-    <ModalContent>
-      <ModalHeader>
-        <ModalTitle>...</ModalTitle>
-      </ModalHeader>
-      <ModalBody>...</ModalBody>
-    </ModalContent>
-  </ModalPortal>
-</Modal>
-```
+{/* Chat bubble */}
+<TypingIndicator variant="dots" color="muted" />
 
-**Drawer — same pattern as Modal** (Portal + Overlay + Content required)
+{/* AI response — fast with label */}
+<TypingIndicator
+  variant="dots"
+  color="primary"
+  speed="fast"
+  showLabel
+  label="AI is typing..."
+/>
 
-**Tooltip — Provider required:**
-```tsx
-<TooltipProvider>         {/* ← Required, wrap app once */}
-  <Tooltip>
-    <TooltipTrigger>...</TooltipTrigger>
-    <TooltipPortal>
-      <TooltipContent>...</TooltipContent>
-    </TooltipPortal>
-  </Tooltip>
-</TooltipProvider>
+{/* Large cursor, primary color */}
+<TypingIndicator variant="cursor" size="lg" color="primary" />
 ```
 
-**Toast — imperative API, no compound structure:**
-```tsx
-// Place Toaster once in layout
-<Toaster />
-// Call toast() anywhere
-toast.success('Done')
-```
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| variant | `'dots' \| 'cursor'` | `'dots'` | Animation style |
+| size | `'sm' \| 'default' \| 'lg'` | `'default'` | Size |
+| color | `'default' \| 'primary' \| 'muted'` | `'muted'` | Color |
+| speed | `'slow' \| 'default' \| 'fast'` | `'default'` | Speed (dots only) |
+| label | `string` | `'Typing'` | aria-label and showLabel text |
+| showLabel | `boolean` | `false` | Show text label alongside indicator |
 
 ---
 
-## asChild Pattern (Slot)
-
-`asChild` replaces the component's DOM element with its child, keeping styles and behavior:
+### QuickReply
 
 ```tsx
-// ❌ Double <a> — broken HTML
-<Link href="/about">
-  <Button>About</Button>
-</Link>
-
-// ✅ Button renders as <a> with Button styles
-<Button asChild>
-  <Link href="/about">About</Link>
-</Button>
-
-// ✅ DropdownMenu item as link
-<DropdownMenuItem asChild>
-  <Link href="/settings">Settings</Link>
-</DropdownMenuItem>
-
-// ✅ Breadcrumb as Next.js Link
-<BreadcrumbLink asChild>
-  <Link href="/">Home</Link>
-</BreadcrumbLink>
-```
+import { QuickReply, QuickReplyItem } from '@7onic-ui/react'
 
-**Use `asChild` when combining 7onic components with routing `<Link>`.**
-Components that support `asChild`: Button, IconButton, Badge, Card, Modal.Trigger, Modal.Close, Drawer.Trigger, Drawer.Close, DropdownMenu.Item, Breadcrumb.Link, NavigationMenu.Link, Tooltip.Trigger, Popover.Trigger
-
----
-
-## Props Usage
+{/* Basic suggested replies */}
+<QuickReply aria-label="Suggested replies">
+  <QuickReplyItem>About payment</QuickReplyItem>
+  <QuickReplyItem>Shipping info</QuickReplyItem>
+  <QuickReplyItem>Return policy</QuickReplyItem>
+</QuickReply>
 
-**Always use allowed values.** Don't pass arbitrary strings to variant/size/color props.
+{/* Primary color, filled variant */}
+<QuickReply color="primary" variant="filled" aria-label="Quick replies">
+  <QuickReplyItem>Payment</QuickReplyItem>
+  <QuickReplyItem>Shipping</QuickReplyItem>
+</QuickReply>
 
-```tsx
-// ✅ Correct
-<Button variant="solid" size="default" color="primary" />
+{/* Wrap layout for FAQ */}
+<QuickReply layout="wrap" aria-label="FAQ topics">
+  <QuickReplyItem>Payments</QuickReplyItem>
+  <QuickReplyItem>Shipping</QuickReplyItem>
+  <QuickReplyItem>Returns</QuickReplyItem>
+  <QuickReplyItem>Account</QuickReplyItem>
+</QuickReply>
 
-// ❌ Wrong — invalid values
-<Button variant="primary" />     // 'primary' is a color, not a variant
-<Button size="medium" />         // Use 'md' or 'default', not 'medium'
-<Button color="blue" />          // Use 'primary', not raw color names
+{/* With icon */}
+<QuickReply aria-label="Actions">
+  <QuickReplyItem icon={<MessageCircle />}>Contact us</QuickReplyItem>
+  <QuickReplyItem icon={<Package />}>Track order</QuickReplyItem>
+</QuickReply>
 ```
 
-**`className` on components = layout ONLY** (margin, width, flex positioning). All visual styling (color, size, radius, variant) must use Props.
-
-**Style via Props, not className:**
-```tsx
-// ✅ Use Props
-<Button color="primary" size="lg" />
-<Badge color="error" variant="subtle" />
+| Prop (QuickReply) | Type | Default | Description |
+|---|---|---|---|
+| layout | `'scroll' \| 'wrap'` | `'scroll'` | Chip layout mode |
+| variant | `'outline' \| 'filled' \| 'ghost'` | `'outline'` | Visual style |
+| color | `'default' \| 'primary'` | `'default'` | Color theme |
+| size | `'sm' \| 'default' \| 'lg'` | `'default'` | Chip size |
+| radius | `'md' \| 'lg' \| 'full'` | `'full'` | Border radius |
+| gap | `'sm' \| 'default' \| 'lg'` | `'default'` | Gap between chips |
 
-// ❌ Don't override with className
-<Button className="bg-blue-500 text-white" />
-<Badge className="bg-red-100" />
-```
+| Prop (QuickReply.Item) | Type | Default | Description |
+|---|---|---|---|
+| icon | `ReactNode` | — | Leading icon |
+| asChild | `boolean` | `false` | Compose with custom element (Radix Slot) |
+| disabled | `boolean` | `false` | Disable the chip |
+| onClick | `() => void` | — | Click callback |
 
 ---
 
-## Form Patterns
-
-**Use Field wrapper** for labeled form elements with validation:
+### ChatInput
 
 ```tsx
-import { Field, FieldCharCount, FieldError, FieldLabel, Input, Textarea } from '@7onic-ui/react'{/* Text input with label + error */}
-<Field error={errors.email}>
-  <FieldLabel required>Email</FieldLabel>
-  <Input placeholder="you@example.com" />
-  <FieldError />
-</Field>
+import { ChatInput, ChatInputField, ChatInputSubmit } from '@7onic-ui/react'
 
-{/* Textarea with character count */}
-<Field>
+{/* Basic uncontrolled */}
+<ChatInput onSubmit={(value) => console.log(value)}>
+  <ChatInputField placeholder="Ask me anything..." />
+  <ChatInputSubmit />
+</ChatInput>
+
+{/* Controlled mode */}
+const [value, setValue] = useState('')
+<ChatInput onSubmit={(v) => { handleSend(v); setValue('') }}>
+  <ChatInputField
+    value={value}
+    onChange={(e) => setValue(e.target.value)}
+    placeholder="Ask me anything..."
+  />
+  <ChatInputSubmit />
+</ChatInput>
+
+{/* With loading state + stop */}
+<ChatInput onSubmit={handleSubmit}>
+  <ChatInputField placeholder="Ask me anything..." />
+  <ChatInputSubmit
+    loading={isLoading}
+    onStop={() => abortController.abort()}
+  />
+</ChatInput>
+
+{/* Character count */}
+<ChatInput onSubmit={(value) => console.log(value)}>
+  <ChatInputField placeholder="Ask me anything..." showCount maxLength={500} />
+  <ChatInputSubmit />
+</ChatInput>
+
+{/* Filled variant, large, custom radius */}
+<ChatInput variant="filled" size="lg" radius="2xl" onSubmit={(v) => console.log(v)}>
+  <ChatInputField placeholder="Ask me anything..." maxRows={6} />
+  <ChatInputSubmit />
+</ChatInput>
+
+{/* Inline layout (single-line field + button side by side) */}
+<ChatInput layout="inline" radius="full" onSubmit={(value) => console.log(value)}>
+  <ChatInputField placeholder="Message..." />
+  <ChatInputSubmit />
+</ChatInput>
+
+{/* Inline with custom button radius */}
+<ChatInput layout="inline" radius="xl" onSubmit={handleSubmit}>
+  <ChatInputField placeholder="Message..." />
+  <ChatInputSubmit buttonRadius="full" loading={isLoading} onStop={handleStop} />
+</ChatInput>
+```
+
+| Prop (ChatInput) | Type | Default | Description |
+|---|---|---|---|
+| variant | `'outline' \| 'filled'` | `'outline'` | Visual style |
+| size | `'sm' \| 'default' \| 'lg'` | `'default'` | Size scale |
+| radius | `'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| 'full'` | `'xl'` | Corner radius (`'full'` available in inline layout) |
+| color | `'default' \| 'primary'` | `'default'` | Submit button color |
+| layout | `'default' \| 'inline'` | `'default'` | `'inline'` renders field and button side by side |
+| disabled | `boolean` | `false` | Disable input and submit |
+| onSubmit | `(value: string) => void` | — | Submit callback |
+
+| Prop (ChatInput.Field) | Type | Default | Description |
+|---|---|---|---|
+| maxRows | `number` | `8` | Max rows before scrolling |
+| showCount | `boolean` | `false` | Show character counter (default layout only) |
+| maxLength | `number` | — | Max characters |
+| placeholder | `string` | — | Placeholder text |
+
+| Prop (ChatInput.Submit) | Type | Default | Description |
+|---|---|---|---|
+| loading | `boolean` | `false` | Switch to stop icon — button stays enabled |
+| onStop | `() => void` | — | Called on click when loading |
+| buttonRadius | `'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| 'full'` | — | Override button radius (default: auto from container radius) |
+| children | `ReactNode` | — | Custom icon (default: send arrow) |
+
+### ChatMessage
+
+```tsx
+import { ChatMessage, ChatMessageAvatar, ChatMessageContent, ChatMessageFooter } from '@7onic-ui/react'
+
+{/* Assistant message */}
+<ChatMessage role="assistant">
+  <ChatMessageAvatar />
+  <div className="flex flex-col gap-1">
+    <ChatMessageContent>How can I help you today?</ChatMessageContent>
+    <ChatMessageFooter timestamp="12:34" />
+  </div>
+</ChatMessage>
+
+{/* User message with status */}
+<ChatMessage role="user">
+  <div className="flex flex-col gap-1 items-end">
+    <ChatMessageContent>Thank you for your help!</ChatMessageContent>
+    <ChatMessageFooter timestamp="12:34" status="read" />
+  </div>
+</ChatMessage>
+
+{/* Typing animation */}
+<ChatMessage role="assistant" typing>
+  <ChatMessageAvatar />
+  <ChatMessageContent />
+</ChatMessage>
+
+{/* Custom avatar + hover actions */}
+<ChatMessage
+  role="assistant"
+  actions={<button aria-label="Copy">...</button>}
+>
+  <ChatMessageAvatar initials="AI" />
+  <div className="flex flex-col gap-1">
+    <ChatMessageContent>Response text here.</ChatMessageContent>
+    <ChatMessageFooter timestamp="12:34" />
+  </div>
+</ChatMessage>
+
+{/* User bubble with muted color (common pattern) */}
+<ChatMessage role="user" color="muted">
+  <div className="flex flex-col gap-1 items-end">
+    <ChatMessageContent>Message text</ChatMessageContent>
+    <ChatMessageFooter timestamp="12:34" status="read" />
+  </div>
+</ChatMessage>
+
+{/* History (flat) layout — full-width, no footer */}
+<div className="flex flex-col gap-3">
+  <ChatMessage role="assistant" variant="flat">
+    <ChatMessageAvatar />
+    <ChatMessageContent className="w-full">Here is the answer.</ChatMessageContent>
+  </ChatMessage>
+  <ChatMessage role="user" variant="flat" color="muted">
+    <ChatMessageContent className="w-full">Thanks!</ChatMessageContent>
+  </ChatMessage>
+</div>
+```
+
+| Prop (ChatMessage) | Type | Default | Description |
+|---|---|---|---|
+| role | `'assistant' \| 'user'` | `'assistant'` | Aligns left (assistant) or right (user) |
+| variant | `'bubble' \| 'flat'` | `'bubble'` | Bubble style with background/border, or flat with no fill |
+| color | `'default' \| 'muted' \| 'primary' \| 'dark'` | `'default'` | Bubble background color |
+| size | `'sm' \| 'default' \| 'lg'` | `'default'` | Size scale affecting padding and font |
+| radius | `'md' \| 'lg' \| 'xl' \| '2xl'` | `'2xl'` | Bubble corner radius |
+| tail | `boolean` | `true` | Asymmetric tail corner (sharp on avatar side) — bubble only |
+| avatarSize | `'sm' \| 'md' \| 'lg'` | — | Avatar size — also adjusts gap between avatar and bubble |
+| typing | `boolean` | `false` | Show animated typing dots inside Content |
+| actions | `ReactNode` | — | Hover-reveal action buttons (copy, react, etc.) |
+
+| Prop (ChatMessage.Avatar) | Type | Default | Description |
+|---|---|---|---|
+| size | `'sm' \| 'md' \| 'lg'` | `'md'` | Avatar size: 24/28/32px |
+| src | `string` | — | Avatar image URL |
+| alt | `string` | `'Avatar'` | Alt text |
+| initials | `string` | — | 1–2 character initials (fallback) |
+| icon | `ReactNode` | — | Custom icon (fallback) |
+
+| Prop (ChatMessage.Footer) | Type | Default | Description |
+|---|---|---|---|
+| timestamp | `string` | — | Pre-formatted time string |
+| status | `'sending' \| 'sent' \| 'read' \| 'error' \| ReactNode` | — | Delivery status (built-in presets or custom node) |
+| size | `'sm' \| 'default' \| 'lg'` | — | Size override (defaults to context value from root) |
+
+---
+
+---
+
+# ═══ SECTION 4: COMPONENT USAGE GUIDE ═══
+
+## Component Selection
+
+Before creating custom UI, check if 7onic already has it:
+
+| Need | Use This Component |
+|---|---|
+| Action trigger | Button, IconButton |
+| Text input | Input (single line), Textarea (multi line) |
+| Selection (one) | RadioGroup, Select, Segmented |
+| Selection (many) | Checkbox, ToggleGroup |
+| Boolean toggle | Switch, Toggle, Checkbox |
+| Container | Card |
+| Data table | Table |
+| Tabs | Tabs |
+| Collapsible | Accordion |
+| Dialog | Modal |
+| Side panel | Drawer |
+| Hint text | Tooltip |
+| Rich hint | Popover |
+| Notification | Toast (imperative), Alert (inline) |
+| Loading | Spinner (indeterminate), Progress (determinate), Skeleton (placeholder) |
+| Navigation | Breadcrumb, Pagination, NavigationMenu |
+| Data visualization | Chart (Line/Area/Bar/Pie), MetricCard |
+| Metric display | MetricCard |
+| Tag / chip | Badge (with `removable`) |
+| Avatar | Avatar |
+| Separator | Divider |
+
+**If the component exists, use it.** Don't build custom versions with HTML + classes.
+
+---
+
+## Import Pattern
+
+```tsx
+// ✅ Single import path
+import { Button, Card, Input, toast } from '@7onic-ui/react'
+
+// ✅ Chart components use a separate entry point (recharts is optional)
+import { ChartBar } from '@7onic-ui/react/chart'
+
+// ❌ Never import from internal paths
+import { Button } from '@7onic-ui/react/components/button'  // WRONG
+
+// ❌ Never import Radix directly
+import * as Dialog from '@radix-ui/react-dialog'  // WRONG → use Modal
+```
+
+---
+
+## Compound Component Structure
+
+Compound components have **required sub-components**. Missing them causes errors or broken UI.
+
+**Modal — required structure:**
+```tsx
+<Modal>
+  <ModalTrigger>...</ModalTrigger>
+  <ModalPortal>           {/* ← Required for correct z-index */}
+    <ModalOverlay />      {/* ← Required for backdrop */}
+    <ModalContent>
+      <ModalHeader>
+        <ModalTitle>...</ModalTitle>
+      </ModalHeader>
+      <ModalBody>...</ModalBody>
+    </ModalContent>
+  </ModalPortal>
+</Modal>
+```
+
+**Drawer — same pattern as Modal** (Portal + Overlay + Content required)
+
+**Tooltip — Provider required:**
+```tsx
+<TooltipProvider>         {/* ← Required, wrap app once */}
+  <Tooltip>
+    <TooltipTrigger>...</TooltipTrigger>
+    <TooltipPortal>
+      <TooltipContent>...</TooltipContent>
+    </TooltipPortal>
+  </Tooltip>
+</TooltipProvider>
+```
+
+**Toast — imperative API, no compound structure:**
+```tsx
+// Place Toaster once in layout
+<Toaster />
+// Call toast() anywhere
+toast.success('Done')
+```
+
+---
+
+## asChild Pattern (Slot)
+
+`asChild` replaces the component's DOM element with its child, keeping styles and behavior:
+
+```tsx
+// ❌ Double <a> — broken HTML
+<Link href="/about">
+  <Button>About</Button>
+</Link>
+
+// ✅ Button renders as <a> with Button styles
+<Button asChild>
+  <Link href="/about">About</Link>
+</Button>
+
+// ✅ DropdownMenu item as link
+<DropdownMenuItem asChild>
+  <Link href="/settings">Settings</Link>
+</DropdownMenuItem>
+
+// ✅ Breadcrumb as Next.js Link
+<BreadcrumbLink asChild>
+  <Link href="/">Home</Link>
+</BreadcrumbLink>
+```
+
+**Use `asChild` when combining 7onic components with routing `<Link>`.**
+Components that support `asChild`: Button, IconButton, Badge, Card, Modal.Trigger, Modal.Close, Drawer.Trigger, Drawer.Close, DropdownMenu.Item, Breadcrumb.Link, NavigationMenu.Link, Tooltip.Trigger, Popover.Trigger
+
+---
+
+## Props Usage
+
+**Always use allowed values.** Don't pass arbitrary strings to variant/size/color props.
+
+```tsx
+// ✅ Correct
+<Button variant="solid" size="default" color="primary" />
+
+// ❌ Wrong — invalid values
+<Button variant="primary" />     // 'primary' is a color, not a variant
+<Button size="medium" />         // Use 'md' or 'default', not 'medium'
+<Button color="blue" />          // Use 'primary', not raw color names
+```
+
+**`className` on components = layout ONLY** (margin, width, flex positioning). All visual styling (color, size, radius, variant) must use Props.
+
+**Style via Props, not className:**
+```tsx
+// ✅ Use Props
+<Button color="primary" size="lg" />
+<Badge color="error" variant="subtle" />
+
+// ❌ Don't override with className
+<Button className="bg-blue-500 text-white" />
+<Badge className="bg-red-100" />
+```
+
+---
+
+## Form Patterns
+
+**Use Field wrapper** for labeled form elements with validation:
+
+```tsx
+import { Field, FieldCharCount, FieldError, FieldLabel, Input, Textarea } from '@7onic-ui/react'
+
+{/* Text input with label + error */}
+<Field error={errors.email}>
+  <FieldLabel required>Email</FieldLabel>
+  <Input placeholder="you@example.com" />
+  <FieldError />
+</Field>
+
+{/* Textarea with character count */}
+<Field>
   <FieldLabel>Bio</FieldLabel>
   <Textarea maxLength={200} />
   <FieldCharCount />
@@ -1948,255 +2229,6 @@ But if YOUR code uses React hooks (`useState`, `useEffect`) or event handlers (`
 | ChatMessage | Compound | bubble/flat | sm/default/lg | default/muted/primary/dark | role (assistant/user), tail, avatarSize, radius (md/lg/xl/2xl), typing, actions, Avatar/Content/Footer sub-components |
 ---
 
-### TypingIndicator
-
-```tsx
-import { TypingIndicator } from '@7onic-ui/react'{/* Default — dots, muted, default size */}
-<TypingIndicator />
-
-{/* Cursor variant */}
-<TypingIndicator variant="cursor" />
-
-{/* Chat bubble */}
-<TypingIndicator variant="dots" color="muted" />
-
-{/* AI response — fast with label */}
-<TypingIndicator
-  variant="dots"
-  color="primary"
-  speed="fast"
-  showLabel
-  label="AI is typing..."
-/>
-
-{/* Large cursor, primary color */}
-<TypingIndicator variant="cursor" size="lg" color="primary" />
-```
-
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| variant | `'dots' \| 'cursor'` | `'dots'` | Animation style |
-| size | `'sm' \| 'default' \| 'lg'` | `'default'` | Size |
-| color | `'default' \| 'primary' \| 'muted'` | `'muted'` | Color |
-| speed | `'slow' \| 'default' \| 'fast'` | `'default'` | Speed (dots only) |
-| label | `string` | `'Typing'` | aria-label and showLabel text |
-| showLabel | `boolean` | `false` | Show text label alongside indicator |
-
----
-
-### QuickReply
-
-```tsx
-import { QuickReply, QuickReplyItem } from '@7onic-ui/react'{/* Basic suggested replies */}
-<QuickReply aria-label="Suggested replies">
-  <QuickReplyItem>About payment</QuickReplyItem>
-  <QuickReplyItem>Shipping info</QuickReplyItem>
-  <QuickReplyItem>Return policy</QuickReplyItem>
-</QuickReply>
-
-{/* Primary color, filled variant */}
-<QuickReply color="primary" variant="filled" aria-label="Quick replies">
-  <QuickReplyItem>Payment</QuickReplyItem>
-  <QuickReplyItem>Shipping</QuickReplyItem>
-</QuickReply>
-
-{/* Wrap layout for FAQ */}
-<QuickReply layout="wrap" aria-label="FAQ topics">
-  <QuickReplyItem>Payments</QuickReplyItem>
-  <QuickReplyItem>Shipping</QuickReplyItem>
-  <QuickReplyItem>Returns</QuickReplyItem>
-  <QuickReplyItem>Account</QuickReplyItem>
-</QuickReply>
-
-{/* With icon */}
-<QuickReply aria-label="Actions">
-  <QuickReplyItem icon={<MessageCircle />}>Contact us</QuickReplyItem>
-  <QuickReplyItem icon={<Package />}>Track order</QuickReplyItem>
-</QuickReply>
-```
-
-| Prop (QuickReply) | Type | Default | Description |
-|---|---|---|---|
-| layout | `'scroll' \| 'wrap'` | `'scroll'` | Chip layout mode |
-| variant | `'outline' \| 'filled' \| 'ghost'` | `'outline'` | Visual style |
-| color | `'default' \| 'primary'` | `'default'` | Color theme |
-| size | `'sm' \| 'default' \| 'lg'` | `'default'` | Chip size |
-| radius | `'md' \| 'lg' \| 'full'` | `'full'` | Border radius |
-| gap | `'sm' \| 'default' \| 'lg'` | `'default'` | Gap between chips |
-
-| Prop (QuickReply.Item) | Type | Default | Description |
-|---|---|---|---|
-| icon | `ReactNode` | — | Leading icon |
-| asChild | `boolean` | `false` | Compose with custom element (Radix Slot) |
-| disabled | `boolean` | `false` | Disable the chip |
-| onClick | `() => void` | — | Click callback |
-
----
-
-### ChatInput
-
-```tsx
-import { ChatInput, ChatInputField, ChatInputSubmit } from '@7onic-ui/react'{/* Basic uncontrolled */}
-<ChatInput onSubmit={(value) => console.log(value)}>
-  <ChatInputField placeholder="Ask me anything..." />
-  <ChatInputSubmit />
-</ChatInput>
-
-{/* Controlled mode */}
-const [value, setValue] = useState('')
-<ChatInput onSubmit={(v) => { handleSend(v); setValue('') }}>
-  <ChatInputField
-    value={value}
-    onChange={(e) => setValue(e.target.value)}
-    placeholder="Ask me anything..."
-  />
-  <ChatInputSubmit />
-</ChatInput>
-
-{/* With loading state + stop */}
-<ChatInput onSubmit={handleSubmit}>
-  <ChatInputField placeholder="Ask me anything..." />
-  <ChatInputSubmit
-    loading={isLoading}
-    onStop={() => abortController.abort()}
-  />
-</ChatInput>
-
-{/* Character count */}
-<ChatInput onSubmit={(value) => console.log(value)}>
-  <ChatInputField placeholder="Ask me anything..." showCount maxLength={500} />
-  <ChatInputSubmit />
-</ChatInput>
-
-{/* Filled variant, large, custom radius */}
-<ChatInput variant="filled" size="lg" radius="2xl" onSubmit={(v) => console.log(v)}>
-  <ChatInputField placeholder="Ask me anything..." maxRows={6} />
-  <ChatInputSubmit />
-</ChatInput>
-
-{/* Inline layout (single-line field + button side by side) */}
-<ChatInput layout="inline" radius="full" onSubmit={(value) => console.log(value)}>
-  <ChatInputField placeholder="Message..." />
-  <ChatInputSubmit />
-</ChatInput>
-
-{/* Inline with custom button radius */}
-<ChatInput layout="inline" radius="xl" onSubmit={handleSubmit}>
-  <ChatInputField placeholder="Message..." />
-  <ChatInputSubmit buttonRadius="full" loading={isLoading} onStop={handleStop} />
-</ChatInput>
-```
-
-| Prop (ChatInput) | Type | Default | Description |
-|---|---|---|---|
-| variant | `'outline' \| 'filled'` | `'outline'` | Visual style |
-| size | `'sm' \| 'default' \| 'lg'` | `'default'` | Size scale |
-| radius | `'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| 'full'` | `'xl'` | Corner radius (`'full'` available in inline layout) |
-| color | `'default' \| 'primary'` | `'default'` | Submit button color |
-| layout | `'default' \| 'inline'` | `'default'` | `'inline'` renders field and button side by side |
-| disabled | `boolean` | `false` | Disable input and submit |
-| onSubmit | `(value: string) => void` | — | Submit callback |
-
-| Prop (ChatInput.Field) | Type | Default | Description |
-|---|---|---|---|
-| maxRows | `number` | `8` | Max rows before scrolling |
-| showCount | `boolean` | `false` | Show character counter (default layout only) |
-| maxLength | `number` | — | Max characters |
-| placeholder | `string` | — | Placeholder text |
-
-| Prop (ChatInput.Submit) | Type | Default | Description |
-|---|---|---|---|
-| loading | `boolean` | `false` | Switch to stop icon — button stays enabled |
-| onStop | `() => void` | — | Called on click when loading |
-| buttonRadius | `'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| 'full'` | — | Override button radius (default: auto from container radius) |
-| children | `ReactNode` | — | Custom icon (default: send arrow) |
-
-### ChatMessage
-
-```tsx
-import { ChatMessage, ChatMessageAvatar, ChatMessageContent, ChatMessageFooter } from '@7onic-ui/react'{/* Assistant message */}
-<ChatMessage role="assistant">
-  <ChatMessageAvatar />
-  <div className="flex flex-col gap-1">
-    <ChatMessageContent>How can I help you today?</ChatMessageContent>
-    <ChatMessageFooter timestamp="12:34" />
-  </div>
-</ChatMessage>
-
-{/* User message with status */}
-<ChatMessage role="user">
-  <div className="flex flex-col gap-1 items-end">
-    <ChatMessageContent>Thank you for your help!</ChatMessageContent>
-    <ChatMessageFooter timestamp="12:34" status="read" />
-  </div>
-</ChatMessage>
-
-{/* Typing animation */}
-<ChatMessage role="assistant" typing>
-  <ChatMessageAvatar />
-  <ChatMessageContent />
-</ChatMessage>
-
-{/* Custom avatar + hover actions */}
-<ChatMessage
-  role="assistant"
-  actions={<button aria-label="Copy">...</button>}
->
-  <ChatMessageAvatar initials="AI" />
-  <div className="flex flex-col gap-1">
-    <ChatMessageContent>Response text here.</ChatMessageContent>
-    <ChatMessageFooter timestamp="12:34" />
-  </div>
-</ChatMessage>
-
-{/* User bubble with muted color (common pattern) */}
-<ChatMessage role="user" color="muted">
-  <div className="flex flex-col gap-1 items-end">
-    <ChatMessageContent>Message text</ChatMessageContent>
-    <ChatMessageFooter timestamp="12:34" status="read" />
-  </div>
-</ChatMessage>
-
-{/* History (flat) layout — full-width, no footer */}
-<div className="flex flex-col gap-3">
-  <ChatMessage role="assistant" variant="flat">
-    <ChatMessageAvatar />
-    <ChatMessageContent className="w-full">Here is the answer.</ChatMessageContent>
-  </ChatMessage>
-  <ChatMessage role="user" variant="flat" color="muted">
-    <ChatMessageContent className="w-full">Thanks!</ChatMessageContent>
-  </ChatMessage>
-</div>
-```
-
-| Prop (ChatMessage) | Type | Default | Description |
-|---|---|---|---|
-| role | `'assistant' \| 'user'` | `'assistant'` | Aligns left (assistant) or right (user) |
-| variant | `'bubble' \| 'flat'` | `'bubble'` | Bubble style with background/border, or flat with no fill |
-| color | `'default' \| 'muted' \| 'primary' \| 'dark'` | `'default'` | Bubble background color |
-| size | `'sm' \| 'default' \| 'lg'` | `'default'` | Size scale affecting padding and font |
-| radius | `'md' \| 'lg' \| 'xl' \| '2xl'` | `'2xl'` | Bubble corner radius |
-| tail | `boolean` | `true` | Asymmetric tail corner (sharp on avatar side) — bubble only |
-| avatarSize | `'sm' \| 'md' \| 'lg'` | — | Avatar size — also adjusts gap between avatar and bubble |
-| typing | `boolean` | `false` | Show animated typing dots inside Content |
-| actions | `ReactNode` | — | Hover-reveal action buttons (copy, react, etc.) |
-
-| Prop (ChatMessage.Avatar) | Type | Default | Description |
-|---|---|---|---|
-| size | `'sm' \| 'md' \| 'lg'` | `'md'` | Avatar size: 24/28/32px |
-| src | `string` | — | Avatar image URL |
-| alt | `string` | `'Avatar'` | Alt text |
-| initials | `string` | — | 1–2 character initials (fallback) |
-| icon | `ReactNode` | — | Custom icon (fallback) |
-
-| Prop (ChatMessage.Footer) | Type | Default | Description |
-|---|---|---|---|
-| timestamp | `string` | — | Pre-formatted time string |
-| status | `'sending' \| 'sent' \| 'read' \| 'error' \| ReactNode` | — | Delivery status (built-in presets or custom node) |
-| size | `'sm' \| 'default' \| 'lg'` | — | Size override (defaults to context value from root) |
-
----
-
 ## Compound Recipe (opt-in self-wrapper)
 
 v0.3.0+ library exports Named only (`<CardHeader>`). To restore dot-notation (`<Card.Header>`) in your project, add a wrapper file. File location is flexible (`src/lib/card.tsx`, `lib/card.tsx`, `src/components/compound/card.tsx`, etc.) — pick one. Adjust the import source to match your install method: