npm - @7onic-ui/react - Versions diffs - 0.3.6 → 0.3.8 - Mend

@7onic-ui/react 0.3.6 → 0.3.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/README.md CHANGED Viewed

@@ -26,13 +26,13 @@
 | **🎯** | **Zero design-code drift** | Design and code from a single vision. No handoff, no drift — every component is pixel-verified against Figma. |
 | **📦** | **One JSON, every format** | `figma-tokens.json` auto-generates CSS, Tailwind v3, Tailwind v4, JS/TS, and JSON — all in sync. |
 | **🧩** | **shadcn freedom + MUI convenience** | shadcn's customization with none of its missing features. MUI's built-in power with none of its styling constraints. Both, by design. |
-| **⚡** | **npm or CLI — your choice** | `npm install` for packages, `npx 7onic add` for local copy. Same components, two workflows. |
+| **⚡** | **npm, CLI, or MCP — three ways in** | `npm install` for packages, `npx 7onic add` for local copy, or `claude plugin install 7onic-design@7onic` so your AI agent can explore every token and component and run `validate_code` before a single file lands in your project. Same system, three workflows. |
 | **🔀** | **Only Tailwind v3+v4 dual support** | The ecosystem's only design system supporting both Tailwind versions. Same tokens, same DX. |
 | **🪄** | **Framework-aware setup** | Detects Next.js / Vite, TypeScript, and Tailwind — exits with a clear error if anything's missing. Auto-cleans Vite boilerplate (`.bak` backup), auto-wraps `*` reset in `@layer base` for Next.js + Tailwind v4. No Provider wrapper, no `globals.css` replacement. |
 | **🎮** | **Built-in playground** | Interactive props editor + live code generation in docs. No Storybook setup needed. |
 | **🌗** | **Dark mode, zero config** | Light/dark themes built into tokens. System preference detection out of the box. |
 | **🔓** | **Framework-agnostic tokens** | Tokens ship as pure CSS variables. Use with Vue, Angular, Svelte, or vanilla CSS — no React required. |
-| **🤖** | **AI-ready** | Ships with `llms.txt` — AI builds with design tokens, not hardcoded values. Zero config for Claude, Cursor, Copilot. |
+| **🤖** | **AI-ready** | `llms.txt` for any AI tool, plus an MCP server that installs as a Claude Code plugin in one command (no `npm install`, ~3 MB). AI builds with design tokens, not hardcoded values, and `validate_code` rejects what docs alone can't prevent. Claude Code, Cursor, Copilot. |
 | **🌏** | **CJK-first typography** | Type scale tuned for Japanese kanji, Korean hangul, and Latin — not an afterthought. |
 | **🔐** | **Supply chain verified** | Cryptographically signed releases (npm provenance), automated vulnerability scanning in CI, reproducible builds. You can verify every package came from this exact GitHub commit — not a hijacked account. |
 | **🔥** | **Relentlessly updated** | Actively maintained with continuous research, refinement, and new features. Not abandoned — ever. |
@@ -127,6 +127,8 @@ export default {
 ```
 </details>
+<br>
 **Option B — CLI (local file copy)**
 ```bash
@@ -134,7 +136,9 @@ npx 7onic init   # detects framework, installs deps, configures CSS automaticall
 npx 7onic add button card input
 ```
-Use components:
+<br>
+**Use components:**
 ```tsx
 import { Button, Card, CardHeader, CardTitle, CardContent } from '@7onic-ui/react'
@@ -165,7 +169,7 @@ import { Chart, type ChartConfig } from '@7onic-ui/react/chart'  // charts: sepa
 | **Navigation** | Breadcrumb, NavigationMenu, Pagination | 3 |
 | **AI** | TypingIndicator, QuickReply, ChatInput, ChatMessage | 4 |
-**42 components** — all with CVA variants, controlled + uncontrolled modes, `forwardRef`, and **Named exports** (`CardHeader`, `ModalContent`, `TabsList`, ...). If you prefer dot-notation (`<Card.Header>`), drop in a [Compound Recipe wrapper](docs/decisions/NAMED-PRIMARY-MIGRATION.md) — opt-in, Client Components only.
+**42 components** — all with CVA variants, controlled + uncontrolled modes, `forwardRef`, and **Named exports** (`CardHeader`, `ModalContent`, `TabsList`, ...). If you prefer dot-notation (`<Card.Header>`), drop in a Compound Recipe wrapper — opt-in, Client Components only.
 ---
@@ -269,7 +273,31 @@ Once loaded, AI automatically uses `bg-primary` instead of `bg-blue-500`, spacin
 Works with Claude Code, Cursor, GitHub Copilot, ChatGPT, and any AI tool that reads text files.
-**Setup guides**: [Tokens](https://7onic.design/design-tokens/ai) · [Components](https://7onic.design/components/ai)
+### MCP Server
+For agents that speak MCP, 7onic also ships a stdio server: token search, the full
+component catalog, layout recipes, and `validate_code` rule checking — with queries
+and violation messages in English, Japanese, and Korean. On Claude Code it installs
+as a plugin in one command (no `npm install`, ~3 MB):
+```bash
+claude plugin marketplace add itonys/7onic && claude plugin install 7onic-design@7onic
+```
+Other MCP clients: clone this repo and point your MCP config at `mcp/dist/index.js`
+(the bundle is committed — nothing to build).
+### AI Kit — skills & agent
+The plugin also ships two Claude Code skills and an agent on top of the MCP server:
+`/7onic-setup` (project detection, token CSS wiring, idempotent health check),
+`/7onic-design` (guided build workflow — discovery → tokens → layout → a mandatory
+`validate_code` loop), and `7onic-design-agent` for delegated page/component builds.
+Not on the plugin? Get the same kit via `npx 7onic init --claude` (writes them into
+your project's `.claude/`) or copy the files from
+[7onic.design/components/mcp](https://7onic.design/components/mcp#ai-kit).
+**Setup guides**: [Tokens](https://7onic.design/design-tokens/ai) · [Components](https://7onic.design/components/ai) · [MCP Server & AI Kit](https://7onic.design/components/mcp)
 ---
@@ -296,8 +324,10 @@ Works with Claude Code, Cursor, GitHub Copilot, ChatGPT, and any AI tool that re
 - [x] Automated doc verification (8 checks, AST-powered, blocks publish on error)
 - [x] Automated component verification (7 checks — hardcoded colors, tokens, dark mode, dead code)
 - [x] Multilingual documentation — English, Japanese, Korean (powered by next-intl)
-- [x] npm package distribution — `@7onic-ui/react` + `@7onic-ui/tokens` v0.3.6
+- [x] npm package distribution — `@7onic-ui/react` + `@7onic-ui/tokens` v0.3.8
 - [x] AI integration — `llms.txt` standard, setup guides for Claude Code / Cursor / Copilot / ChatGPT
+- [x] MCP server — token search, component catalog, layout recipes, `validate_code` rule checking (en/ja/ko), Claude Code plugin one-command install
+- [x] AI Kit — `/7onic-setup` + `/7onic-design` skills and a design agent (plugin, `npx 7onic init --claude`, or manual copy)
 - [x] `npx 7onic add` CLI (shadcn-style) — source copy with dependency resolution
 - [x] `npx 7onic init` full workflow — framework/TS/Tailwind detection (abort if missing), Vite `@/` alias auto-configure, base deps install, CSS token import, Vite boilerplate cleanup (`.bak` backup), Next.js+v4 `*` reset auto-wrap, `cn()` + `7onic.json` generation
 - [x] Technical blog — [blog.7onic.design](https://blog.7onic.design) ("Design to Code" series)
@@ -325,5 +355,5 @@ MIT
 <p align="center">
   <strong>One JSON, every format — from Figma to production.</strong><br>
   Independently built.<br>
-  <sub>Last updated: 2026-04-29 (v0.3.6)</sub>
+  <sub>Last updated: 2026-10-22 (v0.3.8)</sub>
 </p>

package/llms.txt CHANGED Viewed

@@ -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`
 ---
@@ -369,7 +370,7 @@ Badge, Button, ButtonGroup, Checkbox, Divider, IconButton, Input, Progress, Skel
 ---
-# ═══ SECTION 3: ALL COMPONENTS (42) ═══
+# ═══ SECTION 3: ALL COMPONENTS (41) ═══
 ---
@@ -558,7 +559,7 @@ 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
 ---
@@ -832,7 +833,7 @@ import { Badge } from '@7onic-ui/react'
 | 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 |
@@ -1483,7 +1484,7 @@ 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'
+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)' },
@@ -1616,157 +1617,418 @@ 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 |
+## AI Components
-**If the component exists, use it.** Don't build custom versions with HTML + classes.
+### TypingIndicator
----
+```tsx
+import { TypingIndicator } from '@7onic-ui/react'
-## Import Pattern
+{/* Default — dots, muted, default size */}
+<TypingIndicator />
-```tsx
-// ✅ Single import path
-import { Button, Card, Input, toast } from '@7onic-ui/react'
+{/* Cursor variant */}
+<TypingIndicator variant="cursor" />
-// ✅ Chart components use a separate entry point (recharts is optional)
-import { ChartBar } from '@7onic-ui/react/chart'
+{/* Chat bubble */}
+<TypingIndicator variant="dots" color="muted" />
-// ❌ Never import from internal paths
-import { Button } from '@7onic-ui/react/components/button'  // WRONG
+{/* AI response — fast with label */}
+<TypingIndicator
+  variant="dots"
+  color="primary"
+  speed="fast"
+  showLabel
+  label="AI is typing..."
+/>
-// ❌ Never import Radix directly
-import * as Dialog from '@radix-ui/react-dialog'  // WRONG → use Modal
+{/* 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 |
-## Compound Component Structure
+---
-Compound components have **required sub-components**. Missing them causes errors or broken UI.
+### QuickReply
-**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>
-```
+import { QuickReply, QuickReplyItem } from '@7onic-ui/react'
-**Drawer — same pattern as Modal** (Portal + Overlay + Content required)
+{/* Basic suggested replies */}
+<QuickReply aria-label="Suggested replies">
+  <QuickReplyItem>About payment</QuickReplyItem>
+  <QuickReplyItem>Shipping info</QuickReplyItem>
+  <QuickReplyItem>Return policy</QuickReplyItem>
+</QuickReply>
-**Tooltip — Provider required:**
-```tsx
-<TooltipProvider>         {/* ← Required, wrap app once */}
-  <Tooltip>
-    <TooltipTrigger>...</TooltipTrigger>
-    <TooltipPortal>
-      <TooltipContent>...</TooltipContent>
-    </TooltipPortal>
-  </Tooltip>
-</TooltipProvider>
-```
+{/* Primary color, filled variant */}
+<QuickReply color="primary" variant="filled" aria-label="Quick replies">
+  <QuickReplyItem>Payment</QuickReplyItem>
+  <QuickReplyItem>Shipping</QuickReplyItem>
+</QuickReply>
-**Toast — imperative API, no compound structure:**
-```tsx
-// Place Toaster once in layout
-<Toaster />
-// Call toast() anywhere
-toast.success('Done')
+{/* 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 |
-## asChild Pattern (Slot)
+| 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 |
-`asChild` replaces the component's DOM element with its child, keeping styles and behavior:
+---
+### ChatInput
 ```tsx
-// ❌ Double <a> — broken HTML
-<Link href="/about">
-  <Button>About</Button>
-</Link>
+import { ChatInput, ChatInputField, ChatInputSubmit } from '@7onic-ui/react'
-// ✅ Button renders as <a> with Button styles
-<Button asChild>
-  <Link href="/about">About</Link>
-</Button>
+{/* Basic uncontrolled */}
+<ChatInput onSubmit={(value) => console.log(value)}>
+  <ChatInputField placeholder="Ask me anything..." />
+  <ChatInputSubmit />
+</ChatInput>
-// ✅ DropdownMenu item as link
-<DropdownMenuItem asChild>
-  <Link href="/settings">Settings</Link>
-</DropdownMenuItem>
+{/* 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>
-// ✅ Breadcrumb as Next.js Link
-<BreadcrumbLink asChild>
-  <Link href="/">Home</Link>
-</BreadcrumbLink>
-```
+{/* With loading state + stop */}
+<ChatInput onSubmit={handleSubmit}>
+  <ChatInputField placeholder="Ask me anything..." />
+  <ChatInputSubmit
+    loading={isLoading}
+    onStop={() => abortController.abort()}
+  />
+</ChatInput>
-**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
+{/* 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>
-## Props Usage
+{/* Inline layout (single-line field + button side by side) */}
+<ChatInput layout="inline" radius="full" onSubmit={(value) => console.log(value)}>
+  <ChatInputField placeholder="Message..." />
+  <ChatInputSubmit />
+</ChatInput>
-**Always use allowed values.** Don't pass arbitrary strings to variant/size/color props.
+{/* Inline with custom button radius */}
+<ChatInput layout="inline" radius="xl" onSubmit={handleSubmit}>
+  <ChatInputField placeholder="Message..." />
+  <ChatInputSubmit buttonRadius="full" loading={isLoading} onStop={handleStop} />
+</ChatInput>
+```
-```tsx
-// ✅ Correct
-<Button variant="solid" size="default" color="primary" />
+| 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 |
-// ❌ 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
-```
+| 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 |
-**`className` on components = layout ONLY** (margin, width, flex positioning). All visual styling (color, size, radius, variant) must use Props.
+| 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
-**Style via Props, not className:**
 ```tsx
-// ✅ Use Props
-<Button color="primary" size="lg" />
-<Badge color="error" variant="subtle" />
+import { ChatMessage, ChatMessageAvatar, ChatMessageContent, ChatMessageFooter } from '@7onic-ui/react'
-// ❌ Don't override with className
-<Button className="bg-blue-500 text-white" />
+{/* 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" />
 ```
@@ -1967,263 +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:

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@7onic-ui/react",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "private": false,
   "sideEffects": [
     "*.css"
@@ -51,9 +51,10 @@
     "verify:components": "tsx scripts/verify-components.ts",
     "verify:framework-compat": "tsx scripts/verify-framework-compat.ts",
     "verify:llms-examples": "tsx scripts/verify-llms-examples.ts",
+    "verify:mcp": "cd mcp && npm run verify-drift && npm run verify-validate",
     "verify:publish": "tsx scripts/verify-publish.ts",
     "smoke": "bash scripts/smoke-test.sh",
-    "prepublishOnly": "npm run verify:framework-compat && npm run verify:llms-examples && npm run build:lib && npm run verify:publish && npm run smoke"
+    "prepublishOnly": "npm run verify:framework-compat && npm run verify:llms-examples && npm run verify:mcp && npm run build:lib && npm run verify:publish && npm run smoke"
   },
   "dependencies": {
     "@radix-ui/react-accordion": "^1.2.0",
@@ -79,8 +80,6 @@
     "@radix-ui/react-tooltip": "^1.1.0",
     "class-variance-authority": "^0.7.0",
     "clsx": "^2.1.0",
-    "jsonc-parser": "^3.3.1",
-    "next-intl": "^4.9.1",
     "tailwind-merge": "^2.3.0"
   },
   "peerDependencies": {
@@ -106,14 +105,16 @@
     "autoprefixer": "^10.4.19",
     "cmdk": "^1.1.1",
     "eslint": "^8.57.0",
-    "eslint-config-next": "^15.0.0",
+    "eslint-config-next": "^15.5.28",
     "eslint-config-prettier": "^9.1.0",
     "eslint-plugin-react": "^7.34.0",
     "eslint-plugin-react-hooks": "^4.6.0",
+    "jsonc-parser": "^3.3.1",
     "lucide-react": "^0.400.0",
-    "next": "^15.5.15",
+    "next": "^15.5.28",
+    "next-intl": "^4.14.9",
     "picocolors": "^1.1.1",
-    "postcss": "^8.4.38",
+    "postcss": "^8.5.31",
     "prettier": "^3.3.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
@@ -149,5 +150,8 @@
   "engines": {
     "node": ">=18"
   },
-  "packageManager": "npm@10.9.1+sha512.c89530d37c4baa38afd43e76a077a84b9aa63840b986426584fd5c5a54ab0a0b21bb1595c851042b733784b0b43706d36a494b4d8ae1a086a762cb8d3f95942a"
+  "packageManager": "npm@10.9.1+sha512.c89530d37c4baa38afd43e76a077a84b9aa63840b986426584fd5c5a54ab0a0b21bb1595c851042b733784b0b43706d36a494b4d8ae1a086a762cb8d3f95942a",
+  "overrides": {
+    "postcss": "$postcss"
+  }
 }