@usevyre/ai-context 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,81 @@
+# @usevyre/ai-context
+
+> Inject useVyre design system context into your AI agent — eliminates UI hallucinations in Cursor, Claude, Windsurf, and Copilot.
+
+[![npm](https://img.shields.io/npm/v/@usevyre/ai-context)](https://www.npmjs.com/package/@usevyre/ai-context)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](../../LICENSE)
+
+## Installation
+
+```bash
+npm install @usevyre/ai-context
+# or
+pnpm add @usevyre/ai-context
+```
+
+## Usage
+
+### Cursor — `.cursor/rules/usevyre.mdc`
+
+```bash
+node -e "
+const { cursorRules } = require('@usevyre/ai-context');
+require('fs').writeFileSync('.cursor/rules/usevyre.mdc', cursorRules);
+"
+```
+
+### Claude — `CLAUDE.md`
+
+```bash
+node -e "
+const { claudeContext } = require('@usevyre/ai-context');
+require('fs').appendFileSync('CLAUDE.md', '\n\n' + claudeContext);
+"
+```
+
+### Windsurf — `.windsurf/rules/usevyre.md`
+
+```bash
+node -e "
+const { windsurfRules } = require('@usevyre/ai-context');
+require('fs').writeFileSync('.windsurf/rules/usevyre.md', windsurfRules);
+"
+```
+
+### GitHub Copilot — `.github/copilot-instructions.md`
+
+```bash
+node -e "
+const { copilotInstructions } = require('@usevyre/ai-context');
+require('fs').writeFileSync('.github/copilot-instructions.md', copilotInstructions);
+"
+```
+
+### JavaScript / TypeScript — inject into system prompt
+
+```ts
+import { fullContext } from "@usevyre/ai-context";
+
+const response = await anthropic.messages.create({
+  model: "claude-opus-4-7",
+  system: fullContext,
+  messages: [{ role: "user", content: "Build a login form" }],
+});
+```
+
+## Exports
+
+| Export | Path | Description |
+|--------|------|-------------|
+| `fullContext` | `@usevyre/ai-context` | Full context string for system prompts |
+| Cursor rules file | `@usevyre/ai-context/cursor` | `.cursor/rules` formatted markdown |
+| Claude context file | `@usevyre/ai-context/claude` | `CLAUDE.md` formatted markdown |
+| Windsurf rules file | `@usevyre/ai-context/windsurf` | `.windsurf/rules` formatted markdown |
+| Copilot instructions file | `@usevyre/ai-context/copilot` | `.github/copilot-instructions.md` formatted markdown |
+| Full context file | `@usevyre/ai-context/full` | Raw markdown file |
+
+Full setup guide → [usevyre.com/docs/ai-context](https://usevyre.com/docs/ai-context)
+
+## License
+
+MIT © [Gapra](https://gapra.dev)

package/dist/anti-patterns.json

@@ -0,0 +1,222 @@
+{
+  "version": "0.2.0",
+  "rules": [
+    {
+      "component": "Accordion",
+      "pattern": "Accordion without AccordionItem",
+      "reason": "Accordion requires AccordionItem as direct child",
+      "fix": "Always compose: Accordion > AccordionItem > AccordionTrigger + AccordionContent",
+      "severity": "error"
+    },
+    {
+      "component": "Alert",
+      "pattern": "variant=\"error\"",
+      "reason": "No 'error' variant exists",
+      "fix": "Use variant=\"danger\"",
+      "severity": "error"
+    },
+    {
+      "component": "Alert",
+      "pattern": "variant=\"primary\"",
+      "reason": "Alert uses severity variants, not brand variants",
+      "fix": "Use variant=\"info\" | \"success\" | \"warning\" | \"danger\"",
+      "severity": "error"
+    },
+    {
+      "component": "Avatar",
+      "pattern": "size=\"xs\"",
+      "reason": "Minimum size is 'sm'",
+      "fix": "Use size=\"sm\"",
+      "severity": "error"
+    },
+    {
+      "component": "Avatar",
+      "pattern": "size=\"2xl\"",
+      "reason": "Maximum size is 'xl'",
+      "fix": "Use size=\"xl\"",
+      "severity": "error"
+    },
+    {
+      "component": "Badge",
+      "pattern": "variant=\"primary\"",
+      "reason": "Badge has no 'primary' variant",
+      "fix": "Use variant=\"accent\" for brand color",
+      "severity": "error"
+    },
+    {
+      "component": "Badge",
+      "pattern": "variant=\"error\"",
+      "reason": "No 'error' variant exists",
+      "fix": "Use variant=\"danger\"",
+      "severity": "error"
+    },
+    {
+      "component": "Badge",
+      "pattern": "variant=\"info\"",
+      "reason": "No 'info' variant on Badge (use Alert for info messages)",
+      "fix": "Use variant=\"teal\" for info-like styling",
+      "severity": "error"
+    },
+    {
+      "component": "Breadcrumb",
+      "pattern": "Using plain <a> tags inside Breadcrumb",
+      "reason": "Use BreadcrumbLink for correct styling and accessibility",
+      "fix": "Use BreadcrumbItem > BreadcrumbLink for each crumb",
+      "severity": "error"
+    },
+    {
+      "component": "Button",
+      "pattern": "variant=\"blue\"",
+      "reason": "No 'blue' variant exists",
+      "fix": "Use variant=\"accent\" for brand amber, or variant=\"teal\" for teal",
+      "severity": "error"
+    },
+    {
+      "component": "Button",
+      "pattern": "size=\"xl\"",
+      "reason": "Maximum size is 'lg'",
+      "fix": "Use size=\"lg\"",
+      "severity": "error"
+    },
+    {
+      "component": "Button",
+      "pattern": "color=\"...\"",
+      "reason": "No color prop exists on Button",
+      "fix": "Use variant prop instead",
+      "severity": "error"
+    },
+    {
+      "component": "Button",
+      "pattern": "icon={...}",
+      "reason": "No 'icon' prop for inserting icons",
+      "fix": "Use leftIcon={...} or rightIcon={...}",
+      "severity": "error"
+    },
+    {
+      "component": "Button",
+      "pattern": "size=\"icon\" without aria-label",
+      "reason": "Icon-only buttons have no visible text — screen readers need aria-label",
+      "fix": "Add aria-label describing the action",
+      "severity": "error"
+    },
+    {
+      "component": "Calendar",
+      "pattern": "Using Calendar for time selection",
+      "reason": "Calendar handles date only, not time",
+      "fix": "Combine with a separate time Input if time selection is needed",
+      "severity": "error"
+    },
+    {
+      "component": "Card",
+      "pattern": "variant=\"primary\"",
+      "reason": "Card has no 'primary' variant",
+      "fix": "Use variant=\"elevated\" | \"outlined\" | \"ghost\" | \"accent\"",
+      "severity": "error"
+    },
+    {
+      "component": "Checkbox",
+      "pattern": "size=\"lg\"",
+      "reason": "Maximum size is 'md'",
+      "fix": "Use size=\"md\"",
+      "severity": "error"
+    },
+    {
+      "component": "Command",
+      "pattern": "Using Input type=\"search\" for search UI",
+      "reason": "Command component is the correct pattern for search-first UI",
+      "fix": "Use Command + CommandInput + CommandList + CommandItem",
+      "severity": "error"
+    },
+    {
+      "component": "DropdownMenu",
+      "pattern": "DropdownItem variant=\"primary\"",
+      "reason": "DropdownItem only has 'default' and 'danger' variants",
+      "fix": "Use variant=\"danger\" for destructive items only",
+      "severity": "error"
+    },
+    {
+      "component": "Field",
+      "pattern": "Applying state prop directly to Input",
+      "reason": "state belongs on Field, not on the Input itself",
+      "fix": "Wrap Input in <Field state=\"error\"> to apply validation styling",
+      "severity": "error"
+    },
+    {
+      "component": "Input",
+      "pattern": "size=\"icon\"",
+      "reason": "'icon' size is only valid for Button, not Input",
+      "fix": "Use size=\"sm\" | \"md\" | \"lg\"",
+      "severity": "error"
+    },
+    {
+      "component": "Input",
+      "pattern": "type=\"search\" for search UI",
+      "reason": "Use Command component for search-first interfaces",
+      "fix": "Import Command from @usevyre/react for search palettes",
+      "severity": "error"
+    },
+    {
+      "component": "Modal",
+      "pattern": "size=\"xl\"",
+      "reason": "Maximum size is 'full'",
+      "fix": "Use size=\"lg\" or size=\"full\"",
+      "severity": "error"
+    },
+    {
+      "component": "Popover",
+      "pattern": "placement=\"top-center\"",
+      "reason": "No 'top-center' — center alignment is the default when no suffix is given",
+      "fix": "Use placement=\"top\" for centered placement",
+      "severity": "error"
+    },
+    {
+      "component": "Progress",
+      "pattern": "value > 100",
+      "reason": "Value is clamped to 0–100",
+      "fix": "Normalize your value to 0–100 range before passing",
+      "severity": "error"
+    },
+    {
+      "component": "Select",
+      "pattern": "Passing strings directly as children",
+      "reason": "Select uses options prop, not children",
+      "fix": "Pass options={[{ value: 'a', label: 'Option A' }]}",
+      "severity": "error"
+    },
+    {
+      "component": "Toast",
+      "pattern": "Rendering <Toast> directly in JSX",
+      "reason": "Toast is triggered via the useToast hook, not rendered directly",
+      "fix": "Use: const { toast } = useToast(); then toast({ title, variant })",
+      "severity": "error"
+    },
+    {
+      "component": "Toast",
+      "pattern": "variant=\"error\"",
+      "reason": "No 'error' variant",
+      "fix": "Use variant=\"danger\"",
+      "severity": "error"
+    },
+    {
+      "component": "Toast",
+      "pattern": "variant=\"info\"",
+      "reason": "No 'info' variant on Toast",
+      "fix": "Use variant=\"default\"",
+      "severity": "error"
+    },
+    {
+      "component": "Tooltip",
+      "pattern": "Using Tooltip for rich content (forms, buttons, etc.)",
+      "reason": "Tooltip is for short text labels only",
+      "fix": "Use Popover for rich interactive content",
+      "severity": "error"
+    },
+    {
+      "component": "Typography",
+      "pattern": "Using raw <h1>, <p> tags instead of Typography components",
+      "reason": "Typography components apply the correct token-based styles",
+      "fix": "Use <Heading>, <Text>, <Lead> from @usevyre/react",
+      "severity": "error"
+    }
+  ]
+}

package/dist/cheat-sheets/accordion.md

@@ -0,0 +1,25 @@
+# Accordion — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Vertically stacked collapsible sections. Compose with AccordionItem, AccordionTrigger, AccordionContent.**
+
+```ts
+import { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from "@usevyre/react"
+```
+
+## Common AI Mistakes
+
+- ❌ `Accordion without AccordionItem`
+  → Always compose: Accordion > AccordionItem > AccordionTrigger + AccordionContent
+
+## Examples
+
+**Basic accordion**
+```tsx
+<Accordion>
+  <AccordionItem value="item-1">
+    <AccordionTrigger>Section Title</AccordionTrigger>
+    <AccordionContent>Content goes here.</AccordionContent>
+  </AccordionItem>
+</Accordion>
+```

package/dist/cheat-sheets/alert.md

@@ -0,0 +1,35 @@
+# Alert — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Inline feedback message for info, success, warning, or danger states.**
+
+```ts
+import { Alert } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `variant` | `"info"` \| `"success"` \| `"warning"` \| `"danger"` | `info` |
+
+## Common AI Mistakes
+
+- ❌ `variant="error"`
+  → Use variant="danger"
+- ❌ `variant="primary"`
+  → Use variant="info" | "success" | "warning" | "danger"
+
+## Examples
+
+**Warning with close button**
+```tsx
+<Alert variant="warning" title="Heads up" onClose={() => setOpen(false)}>
+  This action cannot be undone.
+</Alert>
+```
+
+**Success state**
+```tsx
+<Alert variant="success" title="Saved!">Your changes have been saved.</Alert>
+```

package/dist/cheat-sheets/avatar.md

@@ -0,0 +1,34 @@
+# Avatar — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**User profile image with fallback initials or icon.**
+
+```ts
+import { Avatar } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `size` | `"sm"` \| `"md"` \| `"lg"` \| `"xl"` | `md` |
+| `status` | `"online"` \| `"offline"` \| `"busy"` \| `"away"` | — |
+
+## Common AI Mistakes
+
+- ❌ `size="xs"`
+  → Use size="sm"
+- ❌ `size="2xl"`
+  → Use size="xl"
+
+## Examples
+
+**Avatar with image and online status**
+```tsx
+<Avatar src="/user.png" alt="Jane Doe" size="lg" status="online" />
+```
+
+**Fallback initials**
+```tsx
+<Avatar fallback="JD" size="md" />
+```

package/dist/cheat-sheets/badge.md

@@ -0,0 +1,41 @@
+# Badge — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Small label for status, category, or count. Use dot prop for live status indicator.**
+
+```ts
+import { Badge } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `variant` | `"default"` \| `"accent"` \| `"teal"` \| `"success"` \| `"warning"` \| `"danger"` | `default` |
+| `dot` | `true` \| `false` | `false` |
+
+## Common AI Mistakes
+
+- ❌ `variant="primary"`
+  → Use variant="accent" for brand color
+- ❌ `variant="error"`
+  → Use variant="danger"
+- ❌ `variant="info"`
+  → Use variant="teal" for info-like styling
+
+## Examples
+
+**Live status with dot**
+```tsx
+<Badge variant="success" dot>Online</Badge>
+```
+
+**Warning badge**
+```tsx
+<Badge variant="warning">Beta</Badge>
+```
+
+**Danger badge**
+```tsx
+<Badge variant="danger">Error</Badge>
+```

package/dist/cheat-sheets/breadcrumb.md

@@ -0,0 +1,26 @@
+# Breadcrumb — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Navigation trail showing current page location in hierarchy.**
+
+```ts
+import { Breadcrumb, BreadcrumbItem, BreadcrumbLink, BreadcrumbSeparator } from "@usevyre/react"
+```
+
+## Common AI Mistakes
+
+- ❌ `Using plain <a> tags inside Breadcrumb`
+  → Use BreadcrumbItem > BreadcrumbLink for each crumb
+
+## Examples
+
+**Basic breadcrumb**
+```tsx
+<Breadcrumb>
+  <BreadcrumbItem><BreadcrumbLink href="/">Home</BreadcrumbLink></BreadcrumbItem>
+  <BreadcrumbSeparator />
+  <BreadcrumbItem><BreadcrumbLink href="/docs">Docs</BreadcrumbLink></BreadcrumbItem>
+  <BreadcrumbSeparator />
+  <BreadcrumbItem aria-current="page">Button</BreadcrumbItem>
+</Breadcrumb>
+```

package/dist/cheat-sheets/button.md

@@ -0,0 +1,63 @@
+# Button — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Triggers actions and navigation. The most commonly used interactive element.**
+
+```ts
+import { Button } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `variant` | `"primary"` \| `"secondary"` \| `"ghost"` \| `"accent"` \| `"teal"` \| `"danger"` | `secondary` |
+| `size` | `"sm"` \| `"md"` \| `"lg"` \| `"icon"` | `md` |
+| `loading` | `true` \| `false` | `false` |
+| `disabled` | `true` \| `false` | `false` |
+
+## Common AI Mistakes
+
+- ❌ `variant="blue"`
+  → Use variant="accent" for brand amber, or variant="teal" for teal
+- ❌ `size="xl"`
+  → Use size="lg"
+- ❌ `color="..."`
+  → Use variant prop instead
+- ❌ `icon={...}`
+  → Use leftIcon={...} or rightIcon={...}
+- ❌ `size="icon" without aria-label`
+  → Add aria-label describing the action
+
+## Examples
+
+**Primary CTA**
+```tsx
+<Button variant="primary">Get Started</Button>
+```
+
+**Large accent button**
+```tsx
+<Button variant="accent" size="lg">Launch App</Button>
+```
+
+**Loading state**
+```tsx
+<Button variant="danger" loading>Deleting...</Button>
+```
+
+**Link button**
+```tsx
+<Button as="a" href="/docs" variant="secondary">Read Docs</Button>
+```
+
+**Icon-only button**
+```tsx
+<Button variant="ghost" size="icon" aria-label="Close">
+  <X size={16} />
+</Button>
+```
+
+## Accessibility
+
+- Always add aria-label when using size='icon' (no visible text)

package/dist/cheat-sheets/calendar.md

@@ -0,0 +1,27 @@
+# Calendar — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Date picker calendar widget for selecting single dates or ranges.**
+
+```ts
+import { Calendar } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `disabled` | `true` \| `false` | `false` |
+
+## Common AI Mistakes
+
+- ❌ `Using Calendar for time selection`
+  → Combine with a separate time Input if time selection is needed
+
+## Examples
+
+**Controlled date picker**
+```tsx
+const [date, setDate] = useState(null);
+<Calendar value={date} onChange={setDate} />
+```

package/dist/cheat-sheets/card.md

@@ -0,0 +1,37 @@
+# Card — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Content container with optional header, body, and footer sections.**
+
+```ts
+import { Card, CardHeader, CardBody, CardFooter } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `variant` | `"default"` \| `"elevated"` \| `"outlined"` \| `"ghost"` \| `"accent"` | `default` |
+| `hoverable` | `true` \| `false` | `false` |
+| `clickable` | `true` \| `false` | `false` |
+
+## Common AI Mistakes
+
+- ❌ `variant="primary"`
+  → Use variant="elevated" | "outlined" | "ghost" | "accent"
+
+## Examples
+
+**Elevated card with sections**
+```tsx
+<Card variant="elevated">
+  <CardHeader><Badge variant="teal">New</Badge></CardHeader>
+  <CardBody>
+    <h3>Card Title</h3>
+    <p>Description text.</p>
+  </CardBody>
+  <CardFooter>
+    <Button variant="ghost" size="sm">Learn more</Button>
+  </CardFooter>
+</Card>
+```

package/dist/cheat-sheets/checkbox.md

@@ -0,0 +1,32 @@
+# Checkbox — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Binary toggle for boolean form values.**
+
+```ts
+import { Checkbox } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `size` | `"sm"` \| `"md"` | `md` |
+| `checked` | `true` \| `false` | — |
+| `disabled` | `true` \| `false` | `false` |
+| `indeterminate` | `true` \| `false` | `false` |
+
+## Common AI Mistakes
+
+- ❌ `size="lg"`
+  → Use size="md"
+
+## Examples
+
+**Labeled checkbox**
+```tsx
+<label style={{ display: 'flex', alignItems: 'center', gap: 'var(--vyre-spacing-2)' }}>
+  <Checkbox checked={agreed} onChange={e => setAgreed(e.target.checked)} />
+  I agree to the terms
+</label>
+```

package/dist/cheat-sheets/command.md

@@ -0,0 +1,29 @@
+# Command — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Command palette / search dialog. Use for search-first navigation or quick actions.**
+
+```ts
+import { Command, CommandInput, CommandList, CommandEmpty, CommandGroup, CommandItem, CommandDialog } from "@usevyre/react"
+```
+
+## Common AI Mistakes
+
+- ❌ `Using Input type="search" for search UI`
+  → Use Command + CommandInput + CommandList + CommandItem
+
+## Examples
+
+**Basic command palette**
+```tsx
+<Command>
+  <CommandInput placeholder="Search..." />
+  <CommandList>
+    <CommandEmpty>No results found.</CommandEmpty>
+    <CommandGroup heading="Suggestions">
+      <CommandItem onSelect={() => handleSelect('dashboard')}>Dashboard</CommandItem>
+      <CommandItem onSelect={() => handleSelect('settings')}>Settings</CommandItem>
+    </CommandGroup>
+  </CommandList>
+</Command>
+```

package/dist/cheat-sheets/dropdownmenu.md

@@ -0,0 +1,25 @@
+# DropdownMenu — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Contextual menu triggered by a button. Supports items, separators, checkbox items, radio groups, and sub-menus.**
+
+```ts
+import { DropdownMenu, DropdownItem, DropdownSeparator, DropdownCheckboxItem, DropdownRadioGroup, DropdownRadioItem, DropdownSub } from "@usevyre/react"
+```
+
+## Common AI Mistakes
+
+- ❌ `DropdownItem variant="primary"`
+  → Use variant="danger" for destructive items only
+
+## Examples
+
+**Dropdown with danger item**
+```tsx
+<DropdownMenu trigger={<Button variant="secondary">Options</Button>}>
+  <DropdownItem onSelect={() => handleEdit()}>Edit</DropdownItem>
+  <DropdownItem onSelect={() => handleDuplicate()}>Duplicate</DropdownItem>
+  <DropdownSeparator />
+  <DropdownItem variant="danger" onSelect={() => handleDelete()}>Delete</DropdownItem>
+</DropdownMenu>
+```