@usevyre/ai-context 1.2.2 → 1.4.0

package/dist/anti-patterns.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.2.0",
+  "version": "1.16.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,377 @@
       "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": "Form",
+      "pattern": "Manually tracking each field's error state with useState",
+      "reason": "Form already validates and maps errors into Field automatically",
+      "fix": "Wrap controls in <FormField name rules> and let Form manage errors",
+      "severity": "error"
+    },
+    {
+      "component": "Form",
+      "pattern": "Adding a validation library (zod/yup) just for basic rules",
+      "reason": "Form ships zero-dependency built-in rules",
+      "fix": "Use rules={{ required, minLength, pattern, email, validate }}",
+      "severity": "error"
+    },
+    {
+      "component": "Form",
+      "pattern": "<FormField> with multiple control children",
+      "reason": "FormField clones a single child to inject name/value/onChange",
+      "fix": "Use one control per FormField (Input/Textarea/Select/etc.)",
+      "severity": "error"
+    },
+    {
+      "component": "Form",
+      "pattern": "<FormField> outside a <Form>",
+      "reason": "FormField reads form context",
+      "fix": "Always nest FormField inside <Form>",
+      "severity": "error"
+    },
+    {
+      "component": "FormField",
+      "pattern": "Putting onChange/value manually on the control inside FormField",
+      "reason": "FormField already injects them; manual props can desync from form state",
+      "fix": "Let FormField wire the control; only pass static props (type, placeholder)",
+      "severity": "error"
+    },
+    {
+      "component": "NumberInput",
+      "pattern": "onChange={(e) => set(e.target.value)}",
+      "reason": "NumberInput emits a number, not an event — there is no e.target",
+      "fix": "onChange={(value) => set(value)} — value is number | null",
+      "severity": "error"
+    },
+    {
+      "component": "NumberInput",
+      "pattern": "Using <Input type=\"number\"> for numeric fields",
+      "reason": "Native number input has no token-styled stepper, no clamp, returns a string",
+      "fix": "Use <NumberInput value onChange min max step />",
+      "severity": "error"
+    },
+    {
+      "component": "NumberInput",
+      "pattern": "Parsing the value with Number() in form state",
+      "reason": "NumberInput already emits a real number (or null)",
+      "fix": "Store the value directly; it is already number | null",
+      "severity": "error"
+    },
+    {
+      "component": "ToggleGroup",
+      "pattern": "onChange={(e) => set(e.target.value)}",
+      "reason": "ToggleGroup emits the value, not an event",
+      "fix": "onChange={(value) => set(value)} — string|null (single) or string[] (multiple)",
+      "severity": "error"
+    },
+    {
+      "component": "ToggleGroup",
+      "pattern": "Using ToggleGroup for a single on/off setting",
+      "reason": "That is a boolean toggle",
+      "fix": "Use <Switch> for on/off; ToggleGroup is for choosing among options",
+      "severity": "error"
+    },
+    {
+      "component": "ToggleGroup",
+      "pattern": "type=\"multiple\" with a string value",
+      "reason": "multiple mode requires an array value",
+      "fix": "value={['a','b']} and onChange receives string[]",
+      "severity": "error"
+    },
+    {
+      "component": "ToggleGroup",
+      "pattern": "<ToggleItem> outside <ToggleGroup>",
+      "reason": "ToggleItem reads group context",
+      "fix": "Always nest ToggleItem inside ToggleGroup (or use options)",
+      "severity": "error"
+    },
+    {
+      "component": "ToggleItem",
+      "pattern": "Tracking selected state on ToggleItem yourself",
+      "reason": "Selection is owned by ToggleGroup",
+      "fix": "Only set value; the group controls selected state",
+      "severity": "error"
+    },
+    {
+      "component": "Stepper",
+      "pattern": "Using Tabs for a wizard / checkout flow",
+      "reason": "Tabs are peer panels; a step flow is ordered with completed/current/upcoming state",
+      "fix": "Use <Stepper> with StepperNav + Step + StepPanel",
+      "severity": "error"
+    },
+    {
+      "component": "Stepper",
+      "pattern": "onChange={(e) => set(e.target.value)}",
+      "reason": "Stepper emits the index number, not an event",
+      "fix": "onChange={(index) => setStep(index)}",
+      "severity": "error"
+    },
+    {
+      "component": "Stepper",
+      "pattern": "Manually toggling which panel is visible",
+      "reason": "StepPanel renders itself only when its index === active",
+      "fix": "Give each StepPanel an index; Stepper shows the active one",
+      "severity": "error"
+    },
+    {
+      "component": "Stepper",
+      "pattern": "<Step> or <StepPanel> outside <Stepper>",
+      "reason": "They read Stepper context",
+      "fix": "Nest Step inside StepperNav, StepPanel inside Stepper",
+      "severity": "error"
+    },
+    {
+      "component": "EmptyState",
+      "pattern": "Building an empty placeholder with a bare <div> + centered text",
+      "reason": "Inconsistent spacing/typography; AI reinvents it each time",
+      "fix": "Use <EmptyState title description variant>",
+      "severity": "error"
+    },
+    {
+      "component": "EmptyState",
+      "pattern": "action / cta prop",
+      "reason": "There is no action prop; the CTA is composed",
+      "fix": "Put the Button as children of EmptyState",
+      "severity": "error"
+    },
+    {
+      "component": "EmptyState",
+      "pattern": "Using EmptyState for a loading state",
+      "reason": "EmptyState is for no-data, not in-progress",
+      "fix": "Use <Skeleton> while loading; EmptyState when the result set is empty",
+      "severity": "error"
+    },
+    {
+      "component": "Stat",
+      "pattern": "Assuming trend flips the arrow direction",
+      "reason": "Arrow direction comes from the delta sign; trend only sets color",
+      "fix": "delta=\"-0.4%\" always shows a down arrow; trend=\"up\" just colors it green",
+      "severity": "error"
+    },
+    {
+      "component": "Stat",
+      "pattern": "Building a KPI card with Card + manual layout",
+      "reason": "Inconsistent value/label/delta styling; AI reinvents it",
+      "fix": "Use <Stat label value delta trend />",
+      "severity": "error"
+    },
+    {
+      "component": "Stat",
+      "pattern": "Laying out a KPI row with custom flex + dividers",
+      "reason": "StatGroup already splits evenly with dividers",
+      "fix": "Wrap the Stats in <StatGroup>",
+      "severity": "error"
+    },
+    {
+      "component": "StatGroup",
+      "pattern": "Putting non-Stat children in StatGroup",
+      "reason": "Dividers/equal-split styling target .vyre-stat",
+      "fix": "Only place <Stat> elements inside StatGroup",
+      "severity": "error"
+    },
+    {
+      "component": "Timeline",
+      "pattern": "Building an activity log with a <ul> + manual dots/lines",
+      "reason": "Inconsistent markers/spacing; AI reinvents it each time",
+      "fix": "Use <Timeline items={[...]} /> or TimelineItem children",
+      "severity": "error"
+    },
+    {
+      "component": "Timeline",
+      "pattern": "Using Stepper for a history/audit feed",
+      "reason": "Stepper is an ordered flow with completed/current/upcoming; a feed is just past events",
+      "fix": "Use <Timeline> for logs/history; Stepper for wizards",
+      "severity": "error"
+    },
+    {
+      "component": "Timeline",
+      "pattern": "Expecting Timeline to sort by time",
+      "reason": "Timeline renders items in given order",
+      "fix": "Sort the array yourself (newest- or oldest-first)",
+      "severity": "error"
+    },
+    {
+      "component": "TimelineItem",
+      "pattern": "<TimelineItem> outside <Timeline>",
+      "reason": "Marker/connector layout assumes the Timeline list context",
+      "fix": "Always nest TimelineItem inside Timeline",
+      "severity": "error"
+    },
+    {
+      "component": "Tree",
+      "pattern": "Rendering a nested <ul> tree by hand with manual expand state",
+      "reason": "Reinvents recursion, keyboard nav, and a11y roles every time",
+      "fix": "Pass a nested `data` array to <Tree> and control expandedIds/selectedId",
+      "severity": "error"
+    },
+    {
+      "component": "Tree",
+      "pattern": "onSelect={(e) => ...}",
+      "reason": "Tree emits the node id, not an event",
+      "fix": "onSelect={(id) => setSelected(id)}",
+      "severity": "error"
+    },
+    {
+      "component": "Tree",
+      "pattern": "Mutating the data array to expand/collapse",
+      "reason": "Expansion is controlled via expandedIds, not the data",
+      "fix": "Track expandedIds in state (or use defaultExpandedIds)",
+      "severity": "error"
+    },
+    {
+      "component": "Tree",
+      "pattern": "Using DropdownMenu submenus for a file tree",
+      "reason": "Submenus are transient menus; a tree is persistent hierarchical content",
+      "fix": "Use <Tree> for file explorers / nested nav",
+      "severity": "error"
+    },
+    {
+      "component": "OTPInput",
+      "pattern": "onChange={(e) => set(e.target.value)}",
+      "reason": "OTPInput emits the code string, not an event — there is no e.target",
+      "fix": "onChange={(value) => setCode(value)}",
+      "severity": "error"
+    },
+    {
+      "component": "OTPInput",
+      "pattern": "Six separate <Input> boxes wired by hand",
+      "reason": "Reinvents paste, auto-advance, backspace and focus management",
+      "fix": "Use <OTPInput length={6} value onChange />",
+      "severity": "error"
+    },
+    {
+      "component": "OTPInput",
+      "pattern": "Reading completion by comparing length yourself",
+      "reason": "onComplete already fires when the code is full",
+      "fix": "Use onComplete={(code) => verify(code)}",
+      "severity": "error"
+    },
+    {
+      "component": "OTPInput",
+      "pattern": "type=\"password\" to hide digits",
+      "reason": "There is no type=password; masking is a dedicated prop",
+      "fix": "Use mask (type stays numeric/alphanumeric)",
+      "severity": "error"
+    },
+    {
+      "component": "Carousel",
+      "pattern": "onChange={(e) => set(e.target.value)}",
+      "reason": "Carousel emits the slide index number, not an event",
+      "fix": "onChange={(index) => setIndex(index)}",
+      "severity": "error"
+    },
+    {
+      "component": "Carousel",
+      "pattern": "Putting raw elements directly in Carousel",
+      "reason": "Slides must be CarouselSlide so snap/indices/aria work",
+      "fix": "Wrap each slide in <CarouselSlide>",
+      "severity": "error"
+    },
+    {
+      "component": "Carousel",
+      "pattern": "Building a slider with manual scroll + dot state",
+      "reason": "Reinvents snap, keyboard, autoplay-pause and a11y roles",
+      "fix": "Use <Carousel> with CarouselSlide children",
+      "severity": "error"
+    },
+    {
+      "component": "Carousel",
+      "pattern": "autoPlay without considering reduced motion / pausing",
+      "reason": "Autoplay can be an accessibility problem if it never pauses",
+      "fix": "Carousel already pauses on hover/focus; keep interval reasonable or omit autoPlay",
+      "severity": "error"
+    },
+    {
+      "component": "CarouselSlide",
+      "pattern": "<CarouselSlide> outside <Carousel>",
+      "reason": "Snap/measurement/aria depend on the Carousel context",
+      "fix": "Always nest CarouselSlide inside Carousel",
+      "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/carousel.md

@@ -0,0 +1,50 @@
+# Carousel — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**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).**
+
+```ts
+import { Carousel, CarouselSlide } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `loop` | `true` \| `false` | `false` |
+| `autoPlay` | `true` \| `false` | `false` |
+| `showArrows` | `true` \| `false` | `true` |
+| `showIndicators` | `true` \| `false` | `true` |
+
+## Common AI 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
+
+## Examples
+
+**Image gallery with loop**
+```tsx
+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>
+```
+
+**Onboarding, autoplay, no arrows**
+```tsx
+<Carousel autoPlay interval={4000} showArrows={false}>
+  <CarouselSlide><Welcome /></CarouselSlide>
+  <CarouselSlide><Features /></CarouselSlide>
+  <CarouselSlide><GetStarted /></CarouselSlide>
+</Carousel>
+```

package/dist/cheat-sheets/carouselslide.md

@@ -0,0 +1,22 @@
+# CarouselSlide — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**One slide inside <Carousel>. Holds arbitrary content (image, Card, testimonial). Slide order determines its index.**
+
+```ts
+import { Carousel, CarouselSlide } from "@usevyre/react"
+```
+
+## Common AI Mistakes
+
+- ❌ `<CarouselSlide> outside <Carousel>`
+  → Always nest CarouselSlide inside Carousel
+
+## Examples
+
+**Card slide**
+```tsx
+<CarouselSlide>
+  <Card><CardBody>“Best tool ever.” — Ada</CardBody></Card>
+</CarouselSlide>
+```

package/dist/cheat-sheets/emptystate.md

@@ -0,0 +1,48 @@
+# EmptyState — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**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.**
+
+```ts
+import { EmptyState } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `variant` | `"default"` \| `"search"` \| `"error"` | `default` |
+| `size` | `"sm"` \| `"md"` \| `"lg"` | `md` |
+
+## Common AI 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
+
+## Examples
+
+**Empty search results with a reset CTA**
+```tsx
+<EmptyState
+  variant="search"
+  title="No results"
+  description="Try a different search term."
+>
+  <Button variant="secondary" onClick={reset}>Clear filters</Button>
+</EmptyState>
+```
+
+**Full-page empty list**
+```tsx
+<EmptyState
+  size="lg"
+  title="No projects yet"
+  description="Create your first project to get started."
+>
+  <Button variant="primary">New project</Button>
+</EmptyState>
+```

package/dist/cheat-sheets/form.md

@@ -0,0 +1,50 @@
+# Form — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**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.**
+
+```ts
+import { Form, FormField } from "@usevyre/react"
+```
+
+## Common AI 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>
+
+## Examples
+
+**Controlled sign-in form with built-in rules**
+```tsx
+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>
+```
+
+**Custom cross-field validation**
+```tsx
+<FormField
+  name="confirm"
+  label="Confirm password"
+  rules={{
+    required: true,
+    validate: (v, all) => v === all.password ? null : "Passwords do not match",
+  }}
+>
+  <Input type="password" />
+</FormField>
+```