@usevyre/ai-context 1.2.2 → 1.4.0

package/dist/windsurf-rules.md

@@ -1,5 +1,5 @@
 # useVyre Rules for Windsurf
-# Version: 1.2.0
+# Version: 1.16.0
 
 # useVyre Design System — AI Context
 # Version: 0.2.0
@@ -342,6 +342,7 @@ import { Button } from "@usevyre/react"
 - ❌ `color="..."` → Use variant prop instead
 - ❌ `icon={...}` → Use leftIcon={...} or rightIcon={...}
 - ❌ `size="icon" without aria-label` → Add aria-label describing the action
+- ❌ `padding / margin / marginTop (any spacing prop) on a useVyre component` → Space BETWEEN components with <Stack gap> / <Grid gap>; space AROUND a block with <Box padding/margin> wrapping it
 
 ---
 
@@ -427,6 +428,7 @@ import { Card, CardHeader, CardBody, CardFooter } from "@usevyre/react"
 
 **Common mistakes:**
 - ❌ `variant="primary"` → Use variant="elevated" | "outlined" | "ghost" | "accent"
+- ❌ `padding / margin / marginTop (any spacing prop) on a useVyre component` → Space BETWEEN components with <Stack gap> / <Grid gap>; space AROUND a block with <Box padding/margin> wrapping it
 
 ---
 
@@ -638,6 +640,7 @@ import { Input } from "@usevyre/react"
 - ❌ `size="icon"` → Use size="sm" | "md" | "lg"
 - ❌ `type="search" for search UI` → Import Command from @usevyre/react for search palettes
 - ❌ `Vue: binding Input/Textarea value without v-model` → Use v-model on <Input>/<Textarea> in Vue; in React use value + onChange
+- ❌ `padding / margin / marginTop (any spacing prop) on a useVyre component` → Space BETWEEN components with <Stack gap> / <Grid gap>; space AROUND a block with <Box padding/margin> wrapping it
 
 ---
 
@@ -1380,6 +1383,716 @@ const messages = [
 
 ---
 
+### Stack
+
+Full one-dimensional flex layout primitive. USE INSTEAD OF <div style={{display:'flex'}}>. Covers the whole CSS flexbox surface (direction incl. reverse, wrap, align/justify/alignContent/alignSelf, grow/shrink/basis, per-axis gap) with token-locked spacing. Renders a plain <div> (or `as`).
+
+```tsx
+import { Stack } from "@usevyre/react"
+
+// Props:
+// direction      = "row" | "column" | "row-reverse" | "column-reverse" (default: row)
+// inline         = boolean (default: false)
+// gap            = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" (default: md)
+// rowGap         = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl"
+// columnGap      = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl"
+// align          = "start" | "center" | "end" | "stretch" | "baseline" (default: stretch)
+// justify        = "start" | "center" | "end" | "between" | "around" | "evenly" (default: start)
+// alignContent   = "start" | "center" | "end" | "stretch" | "between" | "around" | "evenly"
+// alignSelf      = "auto" | "start" | "center" | "end" | "stretch" | "baseline"
+// wrap           = "nowrap" | "wrap" | "wrap-reverse" (default: nowrap)
+// grow           = number
+// shrink         = number
+// basis          = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "auto" | "content" | "0"
+// width          = "auto" | "full" | "fit" | "screen" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl"
+// height         = "auto" | "full" | "fit" | "screen" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl"
+// as             = string (default: div)
+
+// Examples:
+<Stack direction="row" gap="md" align="center" justify="between">
+  <Avatar src={user.avatar} />
+  <Text>{user.name}</Text>
+  <Button>Edit</Button>
+</Stack>
+<Stack wrap="wrap" rowGap="lg" columnGap="md">
+  {tags.map((t) => <Tag key={t}>{t}</Tag>)}
+</Stack>
+```
+
+**Common mistakes:**
+- ❌ `<div style={{ display: 'flex', gap: 12 }}>` → Use <Stack gap="md"> — gap is a token
+- ❌ `gap={12} or gap="12px"` → Use gap="none|xs|sm|md|lg|xl|2xl"
+- ❌ `direction="vertical" / "horizontal"` → Use direction="row" or "column" (also row-reverse / column-reverse)
+- ❌ `style={{ width: "100%" }} / style={{ height: 320 }}` → Use the width / height prop: width="full", width="md", height="screen", etc.
+
+---
+
+### Grid
+
+Two-dimensional CSS grid primitive. Explicit column/row counts (or auto-fit), auto-flow control, token gap. Pair with GridItem for cell spanning/placement. Renders a plain <div> (or `as`).
+
+```tsx
+import { Grid, GridItem } from "@usevyre/react"
+
+// Props:
+// columns        = number | "auto-fit" (default: 1)
+// rows           = number | "auto"
+// flow           = "row" | "column" | "dense" | "row-dense" | "column-dense"
+// gap            = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" (default: md)
+// rowGap         = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl"
+// columnGap      = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl"
+// align          = "start" | "center" | "end" | "stretch" (default: stretch)
+// justify        = "start" | "center" | "end" | "stretch"
+// width          = "auto" | "full" | "fit" | "screen" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl"
+// height         = "auto" | "full" | "fit" | "screen" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl"
+// as             = string (default: div)
+
+// Examples:
+<Grid columns={3} gap="lg">
+  <GridItem colSpan={2}><Card>Wide</Card></GridItem>
+  <Card>Two</Card>
+  <Card>Three</Card>
+</Grid>
+<Grid columns="auto-fit" gap="md">
+  {items.map((i) => <Card key={i.id}>{i.title}</Card>)}
+</Grid>
+```
+
+**Common mistakes:**
+- ❌ `<div style={{ display:'grid', gridTemplateColumns:'1fr 1fr 1fr' }}>` → Use <Grid columns={3} gap="md">
+- ❌ `columns="3" (string)` → Use columns={3} or columns="auto-fit"
+- ❌ `Nested div with inline grid-column for spanning` → Wrap the cell in <GridItem colSpan={2}>
+- ❌ `style={{ width: "100%" }} / style={{ height: 320 }}` → Use the width / height prop: width="full", width="md", height="screen", etc.
+
+---
+
+### GridItem
+
+Child placement inside <Grid>. Sets column/row span and start lines. Renders a plain <div> (or `as`).
+
+```tsx
+import { GridItem } from "@usevyre/react"
+
+// Props:
+// colSpan        = number
+// rowSpan        = number
+// colStart       = number
+// rowStart       = number
+// as             = string (default: div)
+
+// Examples:
+<Grid columns={4} gap="md">
+  <GridItem colSpan={2}>Featured</GridItem>
+  <div>a</div>
+  <div>b</div>
+</Grid>
+```
+
+**Common mistakes:**
+- ❌ `GridItem outside a Grid` → Place <GridItem> directly inside <Grid>
+
+---
+
+### Box
+
+Spacing-only container plus a controlled escape hatch. Token padding/margin with shorthand, per-axis (X/Y) and per-side (Top/Right/Bottom/Left) overrides. The `style` prop is an explicit anti-pattern escape hatch. Renders a plain <div> (or `as`).
+
+```tsx
+import { Box } from "@usevyre/react"
+
+// Props:
+// padding        = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl"
+// paddingX       = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl"
+// paddingY       = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl"
+// paddingTop     = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl"
+// paddingRight   = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl"
+// paddingBottom  = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl"
+// paddingLeft    = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl"
+// margin         = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl"
+// marginX        = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl"
+// marginY        = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl"
+// marginTop      = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl"
+// marginRight    = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl"
+// marginBottom   = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl"
+// marginLeft     = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl"
+// width          = "auto" | "full" | "fit" | "screen" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl"
+// height         = "auto" | "full" | "fit" | "screen" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl"
+// as             = string (default: div)
+// style          = React.CSSProperties
+
+// Examples:
+<Box as="section" paddingX="lg" paddingY="md">
+  <Heading>Settings</Heading>
+</Box>
+<Box marginTop="xl"><Separator /></Box>
+```
+
+**Common mistakes:**
+- ❌ `<Box style={{ padding: 16 }}>` → Use <Box padding="md"> (or paddingX/paddingTop/...)
+- ❌ `Using Box for flex/grid layout` → Use <Stack> or <Grid>
+- ❌ `style={{ width: "100%" }} / style={{ height: 320 }}` → Use the width / height prop: width="full", width="md", height="screen", etc.
+
+---
+
+### Form
+
+Controlled, data-driven form. Zero dependencies. Validation runs on submit and (after the first submit) on blur. Errors map into the wrapped Field automatically (state=error + hint=message). Compose with FormField, which wires name/value/onChange/onBlur into a single control child.
+
+```tsx
+import { Form, FormField } from "@usevyre/react"
+
+// Props:
+// values         = Record<string, any>
+// defaultValues  = Record<string, any>
+// onChange       = function
+// onSubmit       = function
+// onInvalid      = function
+
+// Examples:
+const [values, setValues] = useState({ email: "", password: "" });
+
+<Form values={values} onChange={setValues} onSubmit={(v) => signIn(v)}>
+  <FormField name="email" label="Email" rules={{ required: true, email: true }}>
+    <Input type="email" />
+  </FormField>
+  <FormField name="password" label="Password" rules={{ required: true, minLength: 8 }}>
+    <Input type="password" />
+  </FormField>
+  <Button type="submit" variant="primary">Sign in</Button>
+</Form>
+<FormField
+  name="confirm"
+  label="Confirm password"
+  rules={{
+    required: true,
+    validate: (v, all) => v === all.password ? null : "Passwords do not match",
+  }}
+>
+  <Input type="password" />
+</FormField>
+```
+
+**Common mistakes:**
+- ❌ `Manually tracking each field's error state with useState` → Wrap controls in <FormField name rules> and let Form manage errors
+- ❌ `Adding a validation library (zod/yup) just for basic rules` → Use rules={{ required, minLength, pattern, email, validate }}
+- ❌ `<FormField> with multiple control children` → Use one control per FormField (Input/Textarea/Select/etc.)
+- ❌ `<FormField> outside a <Form>` → Always nest FormField inside <Form>
+
+---
+
+### FormField
+
+A single labelled, validated field inside <Form>. Injects name/value/onChange/onBlur into its one control child and wraps it in <Field> (label + error state + hint).
+
+```tsx
+import { FormField } from "@usevyre/react"
+
+// Props:
+// name           = string
+// label          = string
+// hint           = string
+// rules          = object
+
+// Examples:
+<FormField name="bio" label="Bio" hint="Max 200 characters" rules={{ maxLength: 200 }}>
+  <Textarea />
+</FormField>
+```
+
+**Common mistakes:**
+- ❌ `Putting onChange/value manually on the control inside FormField` → Let FormField wire the control; only pass static props (type, placeholder)
+
+---
+
+### NumberInput
+
+Controlled numeric input with −/+ stepper buttons. onChange emits a NUMBER (or null when empty) — NOT an event. Drops straight into <FormField> (Form handles the non-event value). Clamps to min/max on blur; keyboard ArrowUp/Down ±step, Shift+Arrow ±step×10.
+
+```tsx
+import { NumberInput } from "@usevyre/react"
+
+// Props:
+// value          = number | null
+// defaultValue   = number | null (default: null)
+// onChange       = function
+// min            = number
+// max            = number
+// step           = number (default: 1)
+// precision      = number
+// size           = "sm" | "md" | "lg" (default: md)
+// disabled       = boolean (default: false)
+// readOnly       = boolean (default: false)
+
+// Examples:
+const [qty, setQty] = useState<number | null>(1);
+
+<NumberInput value={qty} onChange={setQty} min={1} max={99} />
+<FormField name="age" label="Age" rules={{ required: true, min: 18 }}>
+  <NumberInput min={0} max={120} />
+</FormField>
+```
+
+**Common mistakes:**
+- ❌ `onChange={(e) => set(e.target.value)}` → onChange={(value) => set(value)} — value is number | null
+- ❌ `Using <Input type="number"> for numeric fields` → Use <NumberInput value onChange min max step />
+- ❌ `Parsing the value with Number() in form state` → Store the value directly; it is already number | null
+
+---
+
+### ToggleGroup
+
+Segmented control. CONTROLLED — the group owns the value. onChange emits the VALUE (not an event). type=single → value:string|null; type=multiple → value:string[]. Provide options[] for simple lists or <ToggleItem value> children for custom content. Distinct from Switch (boolean), ButtonGroup (layout only), RadioGroup (form radios, single only).
+
+```tsx
+import { ToggleGroup, ToggleItem } from "@usevyre/react"
+
+// Props:
+// type           = "single" | "multiple" (default: single)
+// value          = string | null | string[]
+// onChange       = function
+// options        = array
+// size           = "sm" | "md" | "lg" (default: md)
+// orientation    = "horizontal" | "vertical" (default: horizontal)
+// disabled       = boolean (default: false)
+
+// Examples:
+const [view, setView] = useState<string | null>("grid");
+
+<ToggleGroup
+  value={view}
+  onChange={setView}
+  options={[
+    { value: "grid", label: "Grid" },
+    { value: "list", label: "List" },
+  ]}
+/>
+const [fmt, setFmt] = useState<string[]>(["bold"]);
+
+<ToggleGroup type="multiple" value={fmt} onChange={setFmt}>
+  <ToggleItem value="bold">B</ToggleItem>
+  <ToggleItem value="italic">I</ToggleItem>
+  <ToggleItem value="underline">U</ToggleItem>
+</ToggleGroup>
+```
+
+**Common mistakes:**
+- ❌ `onChange={(e) => set(e.target.value)}` → onChange={(value) => set(value)} — string|null (single) or string[] (multiple)
+- ❌ `Using ToggleGroup for a single on/off setting` → Use <Switch> for on/off; ToggleGroup is for choosing among options
+- ❌ `type="multiple" with a string value` → value={['a','b']} and onChange receives string[]
+- ❌ `<ToggleItem> outside <ToggleGroup>` → Always nest ToggleItem inside ToggleGroup (or use options)
+
+---
+
+### ToggleItem
+
+A single toggle button inside <ToggleGroup>. Reads selection state from the group via context.
+
+```tsx
+import { ToggleItem } from "@usevyre/react"
+
+// Props:
+// value          = string
+// icon           = ReactNode
+// disabled       = boolean (default: false)
+
+// Examples:
+<ToggleGroup value={v} onChange={setV}>
+  <ToggleItem value="left">Left</ToggleItem>
+  <ToggleItem value="center">Center</ToggleItem>
+</ToggleGroup>
+```
+
+**Common mistakes:**
+- ❌ `Tracking selected state on ToggleItem yourself` → Only set value; the group controls selected state
+
+---
+
+### Stepper
+
+Multi-step flow indicator + controller (onboarding/checkout/wizard). CONTROLLED by a 0-based index. Compose StepperNav (with Step indicators) and StepPanel (content shown when its index == active). Step/StepPanel take an explicit 0-based `index`. Not Tabs — Stepper is an ORDERED linear flow with completed/current/upcoming states.
+
+```tsx
+import { Stepper, StepperNav, Step, StepPanel } from "@usevyre/react"
+
+// Props:
+// value          = number
+// defaultValue   = number (default: 0)
+// onChange       = function
+// orientation    = "horizontal" | "vertical" (default: horizontal)
+// clickable      = boolean (default: false)
+
+// Examples:
+const [step, setStep] = useState(0);
+
+<Stepper value={step} onChange={setStep}>
+  <StepperNav>
+    <Step index={0} label="Account" />
+    <Step index={1} label="Profile" />
+    <Step index={2} label="Done" />
+  </StepperNav>
+  <StepPanel index={0}><AccountForm /></StepPanel>
+  <StepPanel index={1}><ProfileForm /></StepPanel>
+  <StepPanel index={2}><Summary /></StepPanel>
+  <Stack direction="row" gap="sm" justify="between">
+    <Button onClick={() => setStep((s) => s - 1)} disabled={step === 0}>Back</Button>
+    <Button variant="primary" onClick={() => setStep((s) => s + 1)}>Next</Button>
+  </Stack>
+</Stepper>
+<Stepper orientation="vertical" defaultValue={1}>
+  <StepperNav>
+    <Step index={0} label="Cart" description="2 items" />
+    <Step index={1} label="Shipping" description="Enter address" />
+    <Step index={2} label="Payment" />
+  </StepperNav>
+</Stepper>
+```
+
+**Common mistakes:**
+- ❌ `Using Tabs for a wizard / checkout flow` → Use <Stepper> with StepperNav + Step + StepPanel
+- ❌ `onChange={(e) => set(e.target.value)}` → onChange={(index) => setStep(index)}
+- ❌ `Manually toggling which panel is visible` → Give each StepPanel an index; Stepper shows the active one
+- ❌ `<Step> or <StepPanel> outside <Stepper>` → Nest Step inside StepperNav, StepPanel inside Stepper
+
+---
+
+### StepperNav
+
+Container for Step indicators inside <Stepper>. Lays them out per the Stepper's orientation.
+
+```tsx
+import { Stepper, StepperNav, Step, StepPanel } from "@usevyre/react"
+
+```
+
+---
+
+### Step
+
+One step indicator inside <StepperNav>. State (completed/current/upcoming) derives from the Stepper's active index automatically.
+
+```tsx
+import { Stepper, StepperNav, Step, StepPanel } from "@usevyre/react"
+
+// Props:
+// index          = number
+// label          = ReactNode
+// description    = ReactNode
+// icon           = ReactNode
+
+```
+
+---
+
+### StepPanel
+
+Content for one step. Renders its children only when its index equals the Stepper's active step.
+
+```tsx
+import { Stepper, StepperNav, Step, StepPanel } from "@usevyre/react"
+
+// Props:
+// index          = number
+
+```
+
+---
+
+### EmptyState
+
+Presentational placeholder for empty lists, tables, and search results. No state. title/description/variant/size are props; the optional call-to-action goes in children (React) or the default slot (Vue). variant picks a preset icon (default=box, search=magnifier, error=warning); pass `icon` (or #icon slot) to override.
+
+```tsx
+import { EmptyState } from "@usevyre/react"
+
+// Props:
+// title          = string
+// description    = string
+// variant        = "default" | "search" | "error" (default: default)
+// icon           = ReactNode
+// size           = "sm" | "md" | "lg" (default: md)
+// children       = ReactNode
+
+// Examples:
+<EmptyState
+  variant="search"
+  title="No results"
+  description="Try a different search term."
+>
+  <Button variant="secondary" onClick={reset}>Clear filters</Button>
+</EmptyState>
+<EmptyState
+  size="lg"
+  title="No projects yet"
+  description="Create your first project to get started."
+>
+  <Button variant="primary">New project</Button>
+</EmptyState>
+```
+
+**Common mistakes:**
+- ❌ `Building an empty placeholder with a bare <div> + centered text` → Use <EmptyState title description variant>
+- ❌ `action / cta prop` → Put the Button as children of EmptyState
+- ❌ `Using EmptyState for a loading state` → Use <Skeleton> while loading; EmptyState when the result set is empty
+
+---
+
+### Stat
+
+Presentational dashboard KPI. No state. The arrow DIRECTION follows the sign of `delta` (the actual change: -0.4% → down arrow). The arrow/delta COLOR is set explicitly by `trend` (up=success, down=danger, neutral=muted) — so 'churn -0.4%, trend=up' shows a green DOWN arrow. Wrap several in StatGroup for an evenly-split row with dividers.
+
+```tsx
+import { Stat, StatGroup } from "@usevyre/react"
+
+// Props:
+// label          = string
+// value          = string | number
+// delta          = string | number
+// trend          = "up" | "down" | "neutral" (default: neutral)
+// deltaLabel     = string
+// icon           = ReactNode
+// size           = "sm" | "md" | "lg" (default: md)
+
+// Examples:
+<StatGroup>
+  <Stat label="Revenue" value="$48.2k" delta="+12%" trend="up" deltaLabel="vs last month" />
+  <Stat label="Churn" value="2.1%" delta="-0.4%" trend="up" deltaLabel="lower is better" />
+  <Stat label="Orders" value="1,204" delta="0%" trend="neutral" />
+</StatGroup>
+<Stat label="Active users" value="12,840" delta="+3.2%" trend="up"
+      icon={<UsersIcon />} size="lg" />
+```
+
+**Common mistakes:**
+- ❌ `Assuming trend flips the arrow direction` → delta="-0.4%" always shows a down arrow; trend="up" just colors it green
+- ❌ `Building a KPI card with Card + manual layout` → Use <Stat label value delta trend />
+- ❌ `Laying out a KPI row with custom flex + dividers` → Wrap the Stats in <StatGroup>
+
+---
+
+### StatGroup
+
+Evenly-split row of <Stat> with subtle dividers between items. Each Stat flexes to equal width.
+
+```tsx
+import { Stat, StatGroup } from "@usevyre/react"
+
+// Examples:
+<StatGroup>
+  <Stat label="MRR" value="$9.6k" delta="+5%" trend="up" />
+  <Stat label="Refunds" value="32" delta="+8" trend="down" />
+</StatGroup>
+```
+
+**Common mistakes:**
+- ❌ `Putting non-Stat children in StatGroup` → Only place <Stat> elements inside StatGroup
+
+---
+
+### Timeline
+
+Vertical activity feed for audit logs and history. Presentational — a status dot per item plus a connector line. Pass `items` for plain logs, or TimelineItem children for rich per-item content. Timeline does NOT reorder; pass items in the order you want shown.
+
+```tsx
+import { Timeline, TimelineItem } from "@usevyre/react"
+
+// Props:
+// items          = array
+// children       = ReactNode
+
+// Examples:
+<Timeline
+  items={[
+    { title: "Deployed v2.1", time: "2m ago", status: "success" },
+    { title: "Build started", time: "5m ago", status: "info" },
+    { title: "Push to main", time: "6m ago" },
+  ]}
+/>
+<Timeline>
+  <TimelineItem title="Invoice paid" time="Apr 2" status="success">
+    <Text size="sm">$1,200 — <a href="#">view receipt</a></Text>
+  </TimelineItem>
+  <TimelineItem title="Invoice sent" time="Mar 28" status="info" />
+</Timeline>
+```
+
+**Common mistakes:**
+- ❌ `Building an activity log with a <ul> + manual dots/lines` → Use <Timeline items={[...]} /> or TimelineItem children
+- ❌ `Using Stepper for a history/audit feed` → Use <Timeline> for logs/history; Stepper for wizards
+- ❌ `Expecting Timeline to sort by time` → Sort the array yourself (newest- or oldest-first)
+
+---
+
+### TimelineItem
+
+One entry in a <Timeline>. Renders a status-colored dot (or a custom icon), a title, an optional time, and optional rich content.
+
+```tsx
+import { Timeline, TimelineItem } from "@usevyre/react"
+
+// Props:
+// title          = ReactNode
+// time           = ReactNode
+// status         = "default" | "success" | "warning" | "danger" | "info" (default: default)
+// icon           = ReactNode
+// children       = ReactNode
+
+// Examples:
+<TimelineItem title="Comment added" time="1h ago" status="default">
+  <Text size="sm">“Looks good to me 👍”</Text>
+</TimelineItem>
+```
+
+**Common mistakes:**
+- ❌ `<TimelineItem> outside <Timeline>` → Always nest TimelineItem inside Timeline
+
+---
+
+### Tree
+
+Hierarchical tree view for file explorers and nested navigation. DATA-DRIVEN and CONTROLLED — pass a nested `data` array; the Tree renders recursively. Single selection. A node WITH children is a folder (click toggles expand); a leaf fires onSelect. Keyboard: ArrowUp/Down move, ArrowRight/Left expand/collapse, Enter/Space select.
+
+```tsx
+import { Tree } from "@usevyre/react"
+
+// Props:
+// data           = TreeNode[]
+// expandedIds    = string[]
+// defaultExpandedIds = string[] (default: [])
+// onExpandedChange = function
+// selectedId     = string | null
+// defaultSelectedId = string | null (default: null)
+// onSelect       = function
+
+// Examples:
+const [sel, setSel] = useState<string | null>("src/a.ts");
+
+<Tree
+  data={[
+    { id: "src", label: "src", children: [
+      { id: "src/a.ts", label: "a.ts" },
+      { id: "src/b", label: "b", children: [
+        { id: "src/b/c.ts", label: "c.ts" },
+      ]},
+    ]},
+    { id: "README.md", label: "README.md" },
+  ]}
+  selectedId={sel}
+  onSelect={setSel}
+  defaultExpandedIds={["src"]}
+/>
+const [open, setOpen] = useState<string[]>(["root"]);
+
+<Tree data={tree} expandedIds={open} onExpandedChange={setOpen} />
+```
+
+**Common mistakes:**
+- ❌ `Rendering a nested <ul> tree by hand with manual expand state` → Pass a nested `data` array to <Tree> and control expandedIds/selectedId
+- ❌ `onSelect={(e) => ...}` → onSelect={(id) => setSelected(id)}
+- ❌ `Mutating the data array to expand/collapse` → Track expandedIds in state (or use defaultExpandedIds)
+- ❌ `Using DropdownMenu submenus for a file tree` → Use <Tree> for file explorers / nested nav
+
+---
+
+### OTPInput
+
+Segmented one-time-code input for verification / 2FA. CONTROLLED. onChange emits the STRING value (not an event), and onComplete fires once when every slot is filled. Paste-aware (pasting a full code fills all slots), auto-advance on input, backspace moves to the previous slot, arrow keys navigate. Drops straight into <FormField>.
+
+```tsx
+import { OTPInput } from "@usevyre/react"
+
+// Props:
+// value          = string
+// defaultValue   = string (default: "")
+// onChange       = function
+// onComplete     = function
+// length         = number (default: 6)
+// type           = "numeric" | "alphanumeric" (default: numeric)
+// mask           = boolean (default: false)
+// size           = "sm" | "md" | "lg" (default: md)
+// disabled       = boolean (default: false)
+// autoFocus      = boolean (default: false)
+
+// Examples:
+const [code, setCode] = useState("");
+
+<OTPInput
+  value={code}
+  onChange={setCode}
+  onComplete={(c) => verify(c)}
+  autoFocus
+/>
+<FormField name="otp" label="Verification code"
+           rules={{ required: true, minLength: 6 }}>
+  <OTPInput length={6} />
+</FormField>
+```
+
+**Common mistakes:**
+- ❌ `onChange={(e) => set(e.target.value)}` → onChange={(value) => setCode(value)}
+- ❌ `Six separate <Input> boxes wired by hand` → Use <OTPInput length={6} value onChange />
+- ❌ `Reading completion by comparing length yourself` → Use onComplete={(code) => verify(code)}
+- ❌ `type="password" to hide digits` → Use mask (type stays numeric/alphanumeric)
+
+---
+
+### Carousel
+
+Accessible content slider for galleries, onboarding, and testimonials. CONTROLLED by a 0-based slide index. Compose CarouselSlide children (slide order = index). Snap scrolling, clickable dot indicators, prev/next arrows, ArrowLeft/Right keyboard, optional loop and autoPlay (autoplay pauses on hover/focus). onChange emits the index (not an event).
+
+```tsx
+import { Carousel, CarouselSlide } from "@usevyre/react"
+
+// Props:
+// value          = number
+// defaultValue   = number (default: 0)
+// onChange       = function
+// loop           = boolean (default: false)
+// autoPlay       = boolean (default: false)
+// interval       = number (default: 5000)
+// showArrows     = boolean (default: true)
+// showIndicators = boolean (default: true)
+
+// Examples:
+const [i, setI] = useState(0);
+
+<Carousel value={i} onChange={setI} loop>
+  <CarouselSlide><img src="/a.jpg" alt="A" /></CarouselSlide>
+  <CarouselSlide><img src="/b.jpg" alt="B" /></CarouselSlide>
+  <CarouselSlide><img src="/c.jpg" alt="C" /></CarouselSlide>
+</Carousel>
+<Carousel autoPlay interval={4000} showArrows={false}>
+  <CarouselSlide><Welcome /></CarouselSlide>
+  <CarouselSlide><Features /></CarouselSlide>
+  <CarouselSlide><GetStarted /></CarouselSlide>
+</Carousel>
+```
+
+**Common mistakes:**
+- ❌ `onChange={(e) => set(e.target.value)}` → onChange={(index) => setIndex(index)}
+- ❌ `Putting raw elements directly in Carousel` → Wrap each slide in <CarouselSlide>
+- ❌ `Building a slider with manual scroll + dot state` → Use <Carousel> with CarouselSlide children
+- ❌ `autoPlay without considering reduced motion / pausing` → Carousel already pauses on hover/focus; keep interval reasonable or omit autoPlay
+
+---
+
+### CarouselSlide
+
+One slide inside <Carousel>. Holds arbitrary content (image, Card, testimonial). Slide order determines its index.
+
+```tsx
+import { Carousel, CarouselSlide } from "@usevyre/react"
+
+// Examples:
+<CarouselSlide>
+  <Card><CardBody>“Best tool ever.” — Ada</CardBody></Card>
+</CarouselSlide>
+```
+
+**Common mistakes:**
+- ❌ `<CarouselSlide> outside <Carousel>` → Always nest CarouselSlide inside Carousel
+
+---
+
 ### DateRangePicker
 
 Start/end date range picker. Built on Calendar (mode=range) with a friendlier { from, to } object API, a two-month side-by-side view, and preset shortcuts. Use this for report/filter date ranges; use DatePicker for a single date.
@@ -1433,11 +2146,13 @@ If you generate these, you are hallucinating.
 - ❌ `<Button color="...">` → Use variant prop instead
 - ❌ `<Button icon={...}>` → Use leftIcon={...} or rightIcon={...}
 - ❌ `<Button size="icon" without aria-label>` → Add aria-label describing the action
+- ❌ `<Button padding / margin / marginTop (any spacing prop) on a useVyre component>` → Space BETWEEN components with <Stack gap> / <Grid gap>; space AROUND a block with <Box padding/margin> wrapping it
 - ❌ `<Calendar Calendar for an input field that opens a popover>` → Use <DatePicker /> (single date) or <DateRangePicker /> (range)
 - ❌ `<Calendar value as tuple for mode="single">` → Pass value matching mode; use mode="range" for [start,end]
 - ❌ `<DatePicker DatePicker mode="range" for { from, to } object>` → Use <DateRangePicker /> for the { from, to } object API + presets + dual month
 - ❌ `<DatePicker DatePicker without value/onChange>` → Provide value and onChange (e.g. from useState)
 - ❌ `<Card variant="primary">` → Use variant="elevated" | "outlined" | "ghost" | "accent"
+- ❌ `<Card padding / margin / marginTop (any spacing prop) on a useVyre component>` → Space BETWEEN components with <Stack gap> / <Grid gap>; space AROUND a block with <Box padding/margin> wrapping it
 - ❌ `<Checkbox size="lg">` → Use size="md"
 - ❌ `<RadioGroup <Radio> used outside a <RadioGroup>>` → Always wrap <Radio> in <RadioGroup>
 - ❌ `<RadioGroup RadioGroup without value/onChange (React) or v-model (Vue)>` → Bind value + onChange (React) or v-model (Vue); or defaultValue for uncontrolled in React
@@ -1452,6 +2167,7 @@ If you generate these, you are hallucinating.
 - ❌ `<Input size="icon">` → Use size="sm" | "md" | "lg"
 - ❌ `<Input type="search" for search UI>` → Import Command from @usevyre/react for search palettes
 - ❌ `<Input Vue: binding Input/Textarea value without v-model>` → Use v-model on <Input>/<Textarea> in Vue; in React use value + onChange
+- ❌ `<Input padding / margin / marginTop (any spacing prop) on a useVyre component>` → Space BETWEEN components with <Stack gap> / <Grid gap>; space AROUND a block with <Box padding/margin> wrapping it
 - ❌ `<Modal size="xl">` → Use size="lg" or size="full"
 - ❌ `<Popover placement="top-center">` → Use placement="top" for centered placement
 - ❌ `<Progress value > 100>` → Normalize your value to 0–100 range before passing
@@ -1488,6 +2204,59 @@ If you generate these, you are hallucinating.
 - ❌ `<Conversation Expecting Conversation to store/append messages>` → Append to your own state in onSend (or @send) and pass it back via value
 - ❌ `<Conversation composer without onSend (React) / @send (Vue)>` → Provide onSend / @send to append the message to value
 - ❌ `<Conversation Treating onSend as (text) only when using allowAttachments>` → Handle onSend(text, files) — map files to message attachments and append
+- ❌ `<Stack <div style={{ display: 'flex', gap: 12 }}>>` → Use <Stack gap="md"> — gap is a token
+- ❌ `<Stack gap={12} or gap="12px">` → Use gap="none|xs|sm|md|lg|xl|2xl"
+- ❌ `<Stack direction="vertical" / "horizontal">` → Use direction="row" or "column" (also row-reverse / column-reverse)
+- ❌ `<Stack style={{ width: "100%" }} / style={{ height: 320 }}>` → Use the width / height prop: width="full", width="md", height="screen", etc.
+- ❌ `<Grid <div style={{ display:'grid', gridTemplateColumns:'1fr 1fr 1fr' }}>>` → Use <Grid columns={3} gap="md">
+- ❌ `<Grid columns="3" (string)>` → Use columns={3} or columns="auto-fit"
+- ❌ `<Grid Nested div with inline grid-column for spanning>` → Wrap the cell in <GridItem colSpan={2}>
+- ❌ `<Grid style={{ width: "100%" }} / style={{ height: 320 }}>` → Use the width / height prop: width="full", width="md", height="screen", etc.
+- ❌ `<GridItem GridItem outside a Grid>` → Place <GridItem> directly inside <Grid>
+- ❌ `<Box <Box style={{ padding: 16 }}>>` → Use <Box padding="md"> (or paddingX/paddingTop/...)
+- ❌ `<Box Using Box for flex/grid layout>` → Use <Stack> or <Grid>
+- ❌ `<Box style={{ width: "100%" }} / style={{ height: 320 }}>` → Use the width / height prop: width="full", width="md", height="screen", etc.
+- ❌ `<Form Manually tracking each field's error state with useState>` → Wrap controls in <FormField name rules> and let Form manage errors
+- ❌ `<Form Adding a validation library (zod/yup) just for basic rules>` → Use rules={{ required, minLength, pattern, email, validate }}
+- ❌ `<Form <FormField> with multiple control children>` → Use one control per FormField (Input/Textarea/Select/etc.)
+- ❌ `<Form <FormField> outside a <Form>>` → Always nest FormField inside <Form>
+- ❌ `<FormField Putting onChange/value manually on the control inside FormField>` → Let FormField wire the control; only pass static props (type, placeholder)
+- ❌ `<NumberInput onChange={(e) => set(e.target.value)}>` → onChange={(value) => set(value)} — value is number | null
+- ❌ `<NumberInput Using <Input type="number"> for numeric fields>` → Use <NumberInput value onChange min max step />
+- ❌ `<NumberInput Parsing the value with Number() in form state>` → Store the value directly; it is already number | null
+- ❌ `<ToggleGroup onChange={(e) => set(e.target.value)}>` → onChange={(value) => set(value)} — string|null (single) or string[] (multiple)
+- ❌ `<ToggleGroup Using ToggleGroup for a single on/off setting>` → Use <Switch> for on/off; ToggleGroup is for choosing among options
+- ❌ `<ToggleGroup type="multiple" with a string value>` → value={['a','b']} and onChange receives string[]
+- ❌ `<ToggleGroup <ToggleItem> outside <ToggleGroup>>` → Always nest ToggleItem inside ToggleGroup (or use options)
+- ❌ `<ToggleItem Tracking selected state on ToggleItem yourself>` → Only set value; the group controls selected state
+- ❌ `<Stepper Using Tabs for a wizard / checkout flow>` → Use <Stepper> with StepperNav + Step + StepPanel
+- ❌ `<Stepper onChange={(e) => set(e.target.value)}>` → onChange={(index) => setStep(index)}
+- ❌ `<Stepper Manually toggling which panel is visible>` → Give each StepPanel an index; Stepper shows the active one
+- ❌ `<Stepper <Step> or <StepPanel> outside <Stepper>>` → Nest Step inside StepperNav, StepPanel inside Stepper
+- ❌ `<EmptyState Building an empty placeholder with a bare <div> + centered text>` → Use <EmptyState title description variant>
+- ❌ `<EmptyState action / cta prop>` → Put the Button as children of EmptyState
+- ❌ `<EmptyState Using EmptyState for a loading state>` → Use <Skeleton> while loading; EmptyState when the result set is empty
+- ❌ `<Stat Assuming trend flips the arrow direction>` → delta="-0.4%" always shows a down arrow; trend="up" just colors it green
+- ❌ `<Stat Building a KPI card with Card + manual layout>` → Use <Stat label value delta trend />
+- ❌ `<Stat Laying out a KPI row with custom flex + dividers>` → Wrap the Stats in <StatGroup>
+- ❌ `<StatGroup Putting non-Stat children in StatGroup>` → Only place <Stat> elements inside StatGroup
+- ❌ `<Timeline Building an activity log with a <ul> + manual dots/lines>` → Use <Timeline items={[...]} /> or TimelineItem children
+- ❌ `<Timeline Using Stepper for a history/audit feed>` → Use <Timeline> for logs/history; Stepper for wizards
+- ❌ `<Timeline Expecting Timeline to sort by time>` → Sort the array yourself (newest- or oldest-first)
+- ❌ `<TimelineItem <TimelineItem> outside <Timeline>>` → Always nest TimelineItem inside Timeline
+- ❌ `<Tree Rendering a nested <ul> tree by hand with manual expand state>` → Pass a nested `data` array to <Tree> and control expandedIds/selectedId
+- ❌ `<Tree onSelect={(e) => ...}>` → onSelect={(id) => setSelected(id)}
+- ❌ `<Tree Mutating the data array to expand/collapse>` → Track expandedIds in state (or use defaultExpandedIds)
+- ❌ `<Tree Using DropdownMenu submenus for a file tree>` → Use <Tree> for file explorers / nested nav
+- ❌ `<OTPInput onChange={(e) => set(e.target.value)}>` → onChange={(value) => setCode(value)}
+- ❌ `<OTPInput Six separate <Input> boxes wired by hand>` → Use <OTPInput length={6} value onChange />
+- ❌ `<OTPInput Reading completion by comparing length yourself>` → Use onComplete={(code) => verify(code)}
+- ❌ `<OTPInput type="password" to hide digits>` → Use mask (type stays numeric/alphanumeric)
+- ❌ `<Carousel onChange={(e) => set(e.target.value)}>` → onChange={(index) => setIndex(index)}
+- ❌ `<Carousel Putting raw elements directly in Carousel>` → Wrap each slide in <CarouselSlide>
+- ❌ `<Carousel Building a slider with manual scroll + dot state>` → Use <Carousel> with CarouselSlide children
+- ❌ `<Carousel autoPlay without considering reduced motion / pausing>` → Carousel already pauses on hover/focus; keep interval reasonable or omit autoPlay
+- ❌ `<CarouselSlide <CarouselSlide> outside <Carousel>>` → Always nest CarouselSlide inside Carousel
 - ❌ `<DateRangePicker value={[from, to]}>` → Use value={{ from, to }} and read range.from / range.to
 - ❌ `<DateRangePicker DateRangePicker for a single date>` → Use <DatePicker /> for a single date
 - ❌ `<DateRangePicker presets="true" (string)>` → Use the bare prop: presets  (or presets={true})