@usevyre/ai-context 1.2.2 → 1.3.0

package/dist/anti-patterns.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.2.0",
+  "version": "1.6.0",
   "rules": [
     {
       "component": "Accordion",
@@ -120,6 +120,13 @@
       "fix": "Add aria-label describing the action",
       "severity": "error"
     },
+    {
+      "component": "Button",
+      "pattern": "padding / margin / marginTop (any spacing prop) on a useVyre component",
+      "reason": "Components have NO spacing props by design — internal spacing is fixed by tokens for visual consistency",
+      "fix": "Space BETWEEN components with <Stack gap> / <Grid gap>; space AROUND a block with <Box padding/margin> wrapping it",
+      "severity": "error"
+    },
     {
       "component": "Calendar",
       "pattern": "Calendar for an input field that opens a popover",
@@ -155,6 +162,13 @@
       "fix": "Use variant=\"elevated\" | \"outlined\" | \"ghost\" | \"accent\"",
       "severity": "error"
     },
+    {
+      "component": "Card",
+      "pattern": "padding / margin / marginTop (any spacing prop) on a useVyre component",
+      "reason": "Components have NO spacing props by design — internal spacing is fixed by tokens for visual consistency",
+      "fix": "Space BETWEEN components with <Stack gap> / <Grid gap>; space AROUND a block with <Box padding/margin> wrapping it",
+      "severity": "error"
+    },
     {
       "component": "Checkbox",
       "pattern": "size=\"lg\"",
@@ -253,6 +267,13 @@
       "fix": "Use v-model on <Input>/<Textarea> in Vue; in React use value + onChange",
       "severity": "error"
     },
+    {
+      "component": "Input",
+      "pattern": "padding / margin / marginTop (any spacing prop) on a useVyre component",
+      "reason": "Components have NO spacing props by design — internal spacing is fixed by tokens for visual consistency",
+      "fix": "Space BETWEEN components with <Stack gap> / <Grid gap>; space AROUND a block with <Box padding/margin> wrapping it",
+      "severity": "error"
+    },
     {
       "component": "Modal",
       "pattern": "size=\"xl\"",
@@ -505,6 +526,90 @@
       "fix": "Handle onSend(text, files) — map files to message attachments and append",
       "severity": "error"
     },
+    {
+      "component": "Stack",
+      "pattern": "<div style={{ display: 'flex', gap: 12 }}>",
+      "reason": "Inline flex styles bypass the design system and use magic-number spacing",
+      "fix": "Use <Stack gap=\"md\"> — gap is a token",
+      "severity": "error"
+    },
+    {
+      "component": "Stack",
+      "pattern": "gap={12} or gap=\"12px\"",
+      "reason": "Stack gap is a closed token enum",
+      "fix": "Use gap=\"none|xs|sm|md|lg|xl|2xl\"",
+      "severity": "error"
+    },
+    {
+      "component": "Stack",
+      "pattern": "direction=\"vertical\" / \"horizontal\"",
+      "reason": "Stack mirrors CSS flex-direction names",
+      "fix": "Use direction=\"row\" or \"column\" (also row-reverse / column-reverse)",
+      "severity": "error"
+    },
+    {
+      "component": "Stack",
+      "pattern": "style={{ width: \"100%\" }} / style={{ height: 320 }}",
+      "reason": "Inline width/height bypass the design system and use magic numbers",
+      "fix": "Use the width / height prop: width=\"full\", width=\"md\", height=\"screen\", etc.",
+      "severity": "error"
+    },
+    {
+      "component": "Grid",
+      "pattern": "<div style={{ display:'grid', gridTemplateColumns:'1fr 1fr 1fr' }}>",
+      "reason": "Inline grid styles bypass the design system",
+      "fix": "Use <Grid columns={3} gap=\"md\">",
+      "severity": "error"
+    },
+    {
+      "component": "Grid",
+      "pattern": "columns=\"3\" (string)",
+      "reason": "columns is a number or the literal 'auto-fit'",
+      "fix": "Use columns={3} or columns=\"auto-fit\"",
+      "severity": "error"
+    },
+    {
+      "component": "Grid",
+      "pattern": "Nested div with inline grid-column for spanning",
+      "reason": "Spanning has a dedicated primitive",
+      "fix": "Wrap the cell in <GridItem colSpan={2}>",
+      "severity": "error"
+    },
+    {
+      "component": "Grid",
+      "pattern": "style={{ width: \"100%\" }} / style={{ height: 320 }}",
+      "reason": "Inline width/height bypass the design system and use magic numbers",
+      "fix": "Use the width / height prop: width=\"full\", width=\"md\", height=\"screen\", etc.",
+      "severity": "error"
+    },
+    {
+      "component": "GridItem",
+      "pattern": "GridItem outside a Grid",
+      "reason": "GridItem only has effect as a direct child of Grid",
+      "fix": "Place <GridItem> directly inside <Grid>",
+      "severity": "error"
+    },
+    {
+      "component": "Box",
+      "pattern": "<Box style={{ padding: 16 }}>",
+      "reason": "padding is a token prop; style is a last resort",
+      "fix": "Use <Box padding=\"md\"> (or paddingX/paddingTop/...)",
+      "severity": "error"
+    },
+    {
+      "component": "Box",
+      "pattern": "Using Box for flex/grid layout",
+      "reason": "Box is spacing-only and has no layout props",
+      "fix": "Use <Stack> or <Grid>",
+      "severity": "error"
+    },
+    {
+      "component": "Box",
+      "pattern": "style={{ width: \"100%\" }} / style={{ height: 320 }}",
+      "reason": "Inline width/height bypass the design system and use magic numbers",
+      "fix": "Use the width / height prop: width=\"full\", width=\"md\", height=\"screen\", etc.",
+      "severity": "error"
+    },
     {
       "component": "DateRangePicker",
       "pattern": "value={[from, to]}",

package/dist/cheat-sheets/box.md

@@ -0,0 +1,52 @@
+# Box — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**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`).**
+
+```ts
+import { Box } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `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"` | — |
+
+## Common AI 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.
+
+## Examples
+
+**Asymmetric padding**
+```tsx
+<Box as="section" paddingX="lg" paddingY="md">
+  <Heading>Settings</Heading>
+</Box>
+```
+
+**Vertical rhythm via margin-top**
+```tsx
+<Box marginTop="xl"><Separator /></Box>
+```

package/dist/cheat-sheets/button.md

@@ -28,6 +28,8 @@ import { Button } from "@usevyre/react"
   → 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
 
 ## Examples
 

package/dist/cheat-sheets/card.md

@@ -19,6 +19,8 @@ import { Card, CardHeader, CardBody, CardFooter } from "@usevyre/react"
 
 - ❌ `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
 
 ## Examples
 

package/dist/cheat-sheets/grid.md

@@ -0,0 +1,50 @@
+# Grid — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**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`).**
+
+```ts
+import { Grid, GridItem } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `flow` | `"row"` \| `"column"` \| `"dense"` \| `"row-dense"` \| `"column-dense"` | — |
+| `gap` | `"none"` \| `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` \| `"2xl"` | `md` |
+| `rowGap` | `"none"` \| `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` \| `"2xl"` | — |
+| `columnGap` | `"none"` \| `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` \| `"2xl"` | — |
+| `align` | `"start"` \| `"center"` \| `"end"` \| `"stretch"` | `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"` | — |
+
+## Common AI 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.
+
+## Examples
+
+**Three-column grid with a wide first cell**
+```tsx
+<Grid columns={3} gap="lg">
+  <GridItem colSpan={2}><Card>Wide</Card></GridItem>
+  <Card>Two</Card>
+  <Card>Three</Card>
+</Grid>
+```
+
+**Responsive auto-fit grid**
+```tsx
+<Grid columns="auto-fit" gap="md">
+  {items.map((i) => <Card key={i.id}>{i.title}</Card>)}
+</Grid>
+```

package/dist/cheat-sheets/griditem.md

@@ -0,0 +1,24 @@
+# GridItem — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Child placement inside <Grid>. Sets column/row span and start lines. Renders a plain <div> (or `as`).**
+
+```ts
+import { GridItem } from "@usevyre/react"
+```
+
+## Common AI Mistakes
+
+- ❌ `GridItem outside a Grid`
+  → Place <GridItem> directly inside <Grid>
+
+## Examples
+
+**Span two columns**
+```tsx
+<Grid columns={4} gap="md">
+  <GridItem colSpan={2}>Featured</GridItem>
+  <div>a</div>
+  <div>b</div>
+</Grid>
+```

package/dist/cheat-sheets/index.md

@@ -45,4 +45,8 @@ Quick reference for AI agents — one file per component.
 - [Item](item.md) — Layout primitive for list rows, settings rows, and notification rows. Denser than Card — use Item (not Card) for repeated list rows.
 - [Kanban](kanban.md) — Drag-and-drop board: cards move between columns (or reorder within a column). CONTROLLED & data-driven like DataGrid. While dragging, a placeholder shows the exact drop position. Each card is wrapped in a Card (variant="outlined"); renderCard (React) / #card slot (Vue) can render ANY content incl. complex components (Avatar/Badge/Progress). Columns and cards accept an optional semantic color tint. Native HTML5 DnD, zero deps.
 - [Conversation](conversation.md) — Chat / inbox message thread. CONTROLLED & data-driven like Kanban — you own `value` (messages array) and append in your own send handler; Conversation holds no message state. Consecutive messages from the same author are grouped (avatar + name shown once), day separators are inserted on date change, and outgoing messages (authorId === currentUserId) align right.
+- [Stack](stack.md) — 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`).
+- [Grid](grid.md) — 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`).
+- [GridItem](griditem.md) — Child placement inside <Grid>. Sets column/row span and start lines. Renders a plain <div> (or `as`).
+- [Box](box.md) — 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`).
 - [DateRangePicker](daterangepicker.md) — 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.

package/dist/cheat-sheets/input.md

@@ -21,6 +21,8 @@ import { Input } from "@usevyre/react"
   → 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
 
 ## Examples
 

package/dist/cheat-sheets/stack.md

@@ -0,0 +1,55 @@
+# Stack — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**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`).**
+
+```ts
+import { Stack } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `direction` | `"row"` \| `"column"` \| `"row-reverse"` \| `"column-reverse"` | `row` |
+| `gap` | `"none"` \| `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` \| `"2xl"` | `md` |
+| `rowGap` | `"none"` \| `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` \| `"2xl"` | — |
+| `columnGap` | `"none"` \| `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` \| `"2xl"` | — |
+| `align` | `"start"` \| `"center"` \| `"end"` \| `"stretch"` \| `"baseline"` | `stretch` |
+| `justify` | `"start"` \| `"center"` \| `"end"` \| `"between"` \| `"around"` \| `"evenly"` | `start` |
+| `alignContent` | `"start"` \| `"center"` \| `"end"` \| `"stretch"` \| `"between"` \| `"around"` \| `"evenly"` | — |
+| `alignSelf` | `"auto"` \| `"start"` \| `"center"` \| `"end"` \| `"stretch"` \| `"baseline"` | — |
+| `wrap` | `"nowrap"` \| `"wrap"` \| `"wrap-reverse"` | `nowrap` |
+| `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"` | — |
+| `inline` | `true` \| `false` | `false` |
+
+## Common AI 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.
+
+## Examples
+
+**Row, vertically centered, spaced apart**
+```tsx
+<Stack direction="row" gap="md" align="center" justify="between">
+  <Avatar src={user.avatar} />
+  <Text>{user.name}</Text>
+  <Button>Edit</Button>
+</Stack>
+```
+
+**Wrapping grid-ish gallery with per-axis gap**
+```tsx
+<Stack wrap="wrap" rowGap="lg" columnGap="md">
+  {tags.map((t) => <Tag key={t}>{t}</Tag>)}
+</Stack>
+```

package/dist/claude-context.md

@@ -1,5 +1,5 @@
 # useVyre Design System Context
-# Version: 1.2.0
+# Version: 1.6.0
 
 You are working in a codebase that uses the useVyre design system.
 Follow the rules below strictly when writing any UI code.
@@ -345,6 +345,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
 
 ---
 
@@ -430,6 +431,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
 
 ---
 
@@ -641,6 +643,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
 
 ---
 
@@ -1383,6 +1386,157 @@ 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.
+
+---
+
 ### 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.
@@ -1436,11 +1590,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
@@ -1455,6 +1611,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
@@ -1491,6 +1648,18 @@ 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.
 - ❌ `<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})