@usevyre/ai-context 0.1.0 → 0.2.0

package/dist/cursor-rules.md

@@ -3,294 +3,288 @@ description: useVyre design system rules — follow these when writing UI code
 alwaysApply: true
 ---
 
-# useVyre Design System — AI Context
-# Version: 0.1.0
-# Include this file in your AI agent's system prompt, .cursor/rules, or CLAUDE.md
-# Source: https://usevyre.com/ai-context
+# useVyre Design System — Cursor Rules
+# Version: 0.2.0
 
----
+You are working in a project using the useVyre design system (@usevyre/react).
+Follow these rules strictly when generating any UI code.
 
-## What is useVyre?
+## Critical Rules
+- NEVER use color/size values that are not in the valid prop lists below
+- ALWAYS use semantic tokens (--vyre-color-semantic-*), never hardcode colors
+- ALWAYS add aria-label to Button size="icon" (no visible text)
+- NEVER render <Toast> directly — use useToast() hook
+- NEVER use <Input type="search"> for search UI — use Command component
 
-useVyre is an AI-native design system for React and Vue. It uses CSS custom properties
-(variables) as its single source of truth, making it inherently AI-friendly — no magic,
-no runtime transforms, just semantic token names that describe intent.
+## Component Rules
 
----
+## Accordion
+Vertically stacked collapsible sections. Compose with AccordionItem, AccordionTrigger, AccordionContent.
+Import: `import { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from "@usevyre/react"`
 
-## Installation
+Never do:
+- ❌ Accordion without AccordionItem → ✅ Always compose: Accordion > AccordionItem > AccordionTrigger + AccordionContent
 
-```bash
-# Tokens (required by everything)
-pnpm add @usevyre/tokens
+## Alert
+Inline feedback message for info, success, warning, or danger states.
+Import: `import { Alert } from "@usevyre/react"`
 
-# React components
-pnpm add @usevyre/react
+Valid props:
+- variant: "info" | "success" | "warning" | "danger" [default: info]
 
-# Vue components
-pnpm add @usevyre/vue
-```
+Never do:
+- ❌ variant="error" → ✅ Use variant="danger"
+- ❌ variant="primary" → ✅ Use variant="info" | "success" | "warning" | "danger"
 
-## CSS Setup
+## Avatar
+User profile image with fallback initials or icon.
+Import: `import { Avatar } from "@usevyre/react"`
 
-```css
-/* In your global CSS entry point */
-@import "@usevyre/tokens/css";      /* design tokens */
-@import "@usevyre/react/styles";    /* component styles (React) */
-/* or */
-@import "@usevyre/vue/styles";      /* component styles (Vue) */
-```
+Valid props:
+- size: "sm" | "md" | "lg" | "xl" [default: md]
+- status: "online" | "offline" | "busy" | "away"
 
----
+Never do:
+- ❌ size="xs" → ✅ Use size="sm"
+- ❌ size="2xl" → ✅ Use size="xl"
 
-## Token Naming Convention
+## Badge
+Small label for status, category, or count. Use dot prop for live status indicator.
+Import: `import { Badge } from "@usevyre/react"`
 
-ALL tokens follow this pattern:
-```
---vyre-[category]-[subcategory]-[variant]
-```
+Valid props:
+- variant: "default" | "accent" | "teal" | "success" | "warning" | "danger" [default: default]
 
-Examples:
-- `--vyre-color-semantic-accent`          ✅ Use this
-- `--vyre-color-primitive-amber-400`      ❌ Never use primitives in components
-- `--vyre-spacing-4`                      ✅ 16px spacing
-- `--vyre-typography-font-size-sm`        ✅ 13px font size
+Never do:
+- ❌ variant="primary" → ✅ Use variant="accent" for brand color
+- ❌ variant="error" → ✅ Use variant="danger"
+- ❌ variant="info" → ✅ Use variant="teal" for info-like styling
 
----
+## Breadcrumb
+Navigation trail showing current page location in hierarchy.
+Import: `import { Breadcrumb, BreadcrumbItem, BreadcrumbLink, BreadcrumbSeparator } from "@usevyre/react"`
 
-## Semantic Color Tokens (use these in ALL component styling)
-
-### Surface layers (background → foreground)
-- `--vyre-color-semantic-background`      Page background. Deepest layer.
-- `--vyre-color-semantic-surface`         Cards, panels, sidebars.
-- `--vyre-color-semantic-surface-raised`  Dropdowns, inputs, elevated cards.
-- `--vyre-color-semantic-surface-overlay` Modals, tooltips.
-
-### Borders
-- `--vyre-color-semantic-border-subtle`   Dividers, subtle separators.
-- `--vyre-color-semantic-border`          Default card/input borders.
-- `--vyre-color-semantic-border-strong`   Focus rings, selected states.
-
-### Text hierarchy
-- `--vyre-color-semantic-text-primary`    Headings, body text.
-- `--vyre-color-semantic-text-secondary`  Subtitles, descriptions.
-- `--vyre-color-semantic-text-muted`      Placeholders, helper text.
-- `--vyre-color-semantic-text-disabled`   Disabled state text.
-- `--vyre-color-semantic-text-inverse`    Text on light/accent backgrounds.
-
-### Brand colors
-- `--vyre-color-semantic-accent`          Primary CTA, highlights. (amber)
-- `--vyre-color-semantic-accent-hover`    Hover for accent elements.
-- `--vyre-color-semantic-accent-subtle`   Low-opacity accent backgrounds.
-- `--vyre-color-semantic-teal`            Secondary accent. Code, success. (teal)
-- `--vyre-color-semantic-teal-hover`      Hover for teal elements.
-- `--vyre-color-semantic-teal-subtle`     Low-opacity teal backgrounds.
-
-### Semantic status colors
-- `--vyre-color-semantic-success`         Confirmations, complete states.
-- `--vyre-color-semantic-success-subtle`  Success badge backgrounds.
-- `--vyre-color-semantic-warning`         Warnings, beta indicators.
-- `--vyre-color-semantic-warning-subtle`  Warning badge backgrounds.
-- `--vyre-color-semantic-danger`          Errors, destructive actions.
-- `--vyre-color-semantic-danger-hover`    Hover for danger elements.
-- `--vyre-color-semantic-danger-subtle`   Error badge backgrounds.
+Never do:
+- ❌ Using plain <a> tags inside Breadcrumb → ✅ Use BreadcrumbItem > BreadcrumbLink for each crumb
 
----
+## Button
+Triggers actions and navigation. The most commonly used interactive element.
+Import: `import { Button } from "@usevyre/react"`
 
-## Typography Tokens
-
-### Font families
-- `--vyre-typography-font-family-display`  Headlines, hero text (serif)
-- `--vyre-typography-font-family-body`     UI text, labels, body copy (sans-serif)
-- `--vyre-typography-font-family-mono`     Code, tokens, technical text (monospace)
-
-### Font sizes
-- `--vyre-typography-font-size-2xs`  10px — tiny labels
-- `--vyre-typography-font-size-xs`   11px — badge text, captions
-- `--vyre-typography-font-size-sm`   13px — default UI text, buttons
-- `--vyre-typography-font-size-md`   15px — body text
-- `--vyre-typography-font-size-lg`   18px — large body, small headings
-- `--vyre-typography-font-size-xl`   22px — section headings
-- `--vyre-typography-font-size-2xl`  28px — page headings
-- `--vyre-typography-font-size-3xl`  36px — large headings
-- `--vyre-typography-font-size-4xl`  48px — hero headings
-- `--vyre-typography-font-size-5xl`  64px — display headings
-
-### Font weights
-- `--vyre-typography-font-weight-light`    300
-- `--vyre-typography-font-weight-regular`  400
-- `--vyre-typography-font-weight-medium`   500
-- `--vyre-typography-font-weight-semibold` 600
-- `--vyre-typography-font-weight-bold`     700
+Valid props:
+- variant: "primary" | "secondary" | "ghost" | "accent" | "teal" | "danger" [default: secondary]
+- size: "sm" | "md" | "lg" | "icon" [default: md]
 
----
+Never do:
+- ❌ 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
 
-## Spacing Tokens (4px base grid)
-
-- `--vyre-spacing-1`   4px
-- `--vyre-spacing-2`   8px
-- `--vyre-spacing-3`   12px
-- `--vyre-spacing-4`   16px
-- `--vyre-spacing-5`   20px
-- `--vyre-spacing-6`   24px
-- `--vyre-spacing-8`   32px
-- `--vyre-spacing-10`  40px
-- `--vyre-spacing-12`  48px
-- `--vyre-spacing-16`  64px
-- `--vyre-spacing-20`  80px
-- `--vyre-spacing-24`  96px
+## Calendar
+Date picker calendar widget for selecting single dates or ranges.
+Import: `import { Calendar } from "@usevyre/react"`
 
----
+Valid props:
 
-## Border Radius Tokens
+Never do:
+- ❌ Using Calendar for time selection → ✅ Combine with a separate time Input if time selection is needed
 
-- `--vyre-border-radius-none`  0
-- `--vyre-border-radius-sm`    4px   — tight corners
-- `--vyre-border-radius-md`    8px   — default components
-- `--vyre-border-radius-lg`    12px  — cards, panels
-- `--vyre-border-radius-xl`    16px  — large cards
-- `--vyre-border-radius-2xl`   24px  — modals, sheets
-- `--vyre-border-radius-full`  9999px — badges, pills, avatars
+## Card
+Content container with optional header, body, and footer sections.
+Import: `import { Card, CardHeader, CardBody, CardFooter } from "@usevyre/react"`
 
----
+Valid props:
+- variant: "default" | "elevated" | "outlined" | "ghost" | "accent" [default: default]
 
-## Component API Reference
-
-### Button
-
-```tsx
-import { Button } from "@usevyre/react"
-
-// Props:
-// variant  = "primary" | "secondary" | "ghost" | "accent" | "teal" | "danger"
-// size     = "sm" | "md" | "lg" | "icon"
-// loading  = boolean
-// disabled = boolean
-// as       = React.ElementType (default: "button")
-// leftIcon = ReactNode
-// rightIcon = ReactNode
-
-// Examples:
-<Button variant="accent" size="lg">Get Started</Button>
-<Button variant="ghost" size="sm">Cancel</Button>
-<Button variant="danger" loading>Deleting...</Button>
-<Button as="a" href="/docs" variant="secondary">Read Docs</Button>
-```
-
-### Badge
-
-```tsx
-import { Badge } from "@usevyre/react"
-
-// Props:
-// variant = "default" | "accent" | "teal" | "success" | "warning" | "danger"
-// dot     = boolean (live status indicator dot)
-
-// Examples:
-<Badge variant="success" dot>Online</Badge>
-<Badge variant="warning">Beta</Badge>
-<Badge variant="danger">Error</Badge>
-```
-
-### Card
-
-```tsx
-import { Card, CardHeader, CardBody, CardFooter } from "@usevyre/react"
-
-// Card props:
-// variant   = "default" | "elevated" | "outlined" | "ghost" | "accent"
-// hoverable = boolean
-// clickable = boolean
-
-// Examples:
-<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>
-```
-
-### Field + Input + Textarea
-
-```tsx
-import { Field, Input, Textarea } from "@usevyre/react"
-
-// Field props:
-// label    = string
-// hint     = string
-// state    = "idle" | "error" | "success" | "warning"
-// required = boolean
-
-// Input props:
-// size         = "sm" | "md" | "lg"
-// leftElement  = ReactNode
-// rightElement = ReactNode
-// + all native input props
-
-// Examples:
-<Field label="Email" state="error" hint="Invalid format">
-  <Input type="email" placeholder="you@example.com" />
-</Field>
-
-<Field label="Search">
-  <Input leftElement={<SearchIcon />} placeholder="Search..." />
-</Field>
-
-<Field label="Bio">
-  <Textarea rows={4} placeholder="Tell us about yourself..." />
-</Field>
-```
+Never do:
+- ❌ variant="primary" → ✅ Use variant="elevated" | "outlined" | "ghost" | "accent"
 
----
+## Checkbox
+Binary toggle for boolean form values.
+Import: `import { Checkbox } from "@usevyre/react"`
 
-## Styling Rules for AI Agents
+Valid props:
+- size: "sm" | "md" [default: md]
 
-1. ALWAYS use semantic tokens (`--vyre-color-semantic-*`), never primitive tokens
-2. NEVER hardcode colors — every color decision has a semantic token
-3. Text hierarchy: `text-primary` → `text-secondary` → `text-muted` → `text-disabled`
-4. Interactive hover states: add `-hover` suffix to base token
-5. Low-opacity backgrounds: use `-subtle` suffix tokens
-6. Spacing: always use `--vyre-spacing-*` — never raw px values in component code
-7. Transitions: use `--vyre-transition-duration-*` and `--vyre-transition-easing-*`
+Never do:
+- ❌ size="lg" → ✅ Use size="md"
 
----
+## Command
+Command palette / search dialog. Use for search-first navigation or quick actions.
+Import: `import { Command, CommandInput, CommandList, CommandEmpty, CommandGroup, CommandItem, CommandDialog } from "@usevyre/react"`
+
+Never do:
+- ❌ Using Input type="search" for search UI → ✅ Use Command + CommandInput + CommandList + CommandItem
+
+## DropdownMenu
+Contextual menu triggered by a button. Supports items, separators, checkbox items, radio groups, and sub-menus.
+Import: `import { DropdownMenu, DropdownItem, DropdownSeparator, DropdownCheckboxItem, DropdownRadioGroup, DropdownRadioItem, DropdownSub } from "@usevyre/react"`
+
+Valid props:
+
+Never do:
+- ❌ DropdownItem variant="primary" → ✅ Use variant="danger" for destructive items only
+
+## Field
+Form field wrapper providing label, hint text, and validation state for Input or Textarea.
+Import: `import { Field, Input, Textarea } from "@usevyre/react"`
+
+Valid props:
+- state: "idle" | "error" | "success" | "warning" [default: idle]
+
+Never do:
+- ❌ Applying state prop directly to Input → ✅ Wrap Input in <Field state="error"> to apply validation styling
+
+## Input
+Text input field. Wrap in Field for labels and validation. Use leftElement/rightElement for icons.
+Import: `import { Input } from "@usevyre/react"`
+
+Valid props:
+- size: "sm" | "md" | "lg" [default: md]
+
+Never do:
+- ❌ size="icon" → ✅ Use size="sm" | "md" | "lg"
+- ❌ type="search" for search UI → ✅ Import Command from @usevyre/react for search palettes
+
+## Label
+Accessible form label. Associate with input via htmlFor.
+Import: `import { Label } from "@usevyre/react"`
+
+Valid props:
+
+## Modal
+Dialog overlay for confirmations, forms, or focused content.
+Import: `import { Modal, ModalHeader, ModalBody, ModalFooter } from "@usevyre/react"`
+
+Valid props:
+- size: "sm" | "md" | "lg" | "full" [default: md]
+
+Never do:
+- ❌ size="xl" → ✅ Use size="lg" or size="full"
+
+## Pagination
+Page navigation for paginated lists or tables.
+Import: `import { Pagination } from "@usevyre/react"`
+
+Valid props:
+
+## Popover
+Floating content panel anchored to a trigger element. For simple labels use Tooltip instead.
+Import: `import { Popover } from "@usevyre/react"`
+
+Valid props:
+- placement: "top" | "top-start" | "top-end" | "bottom" | "bottom-start" | "bottom-end" | "left" | "left-start" | "left-end" | "right" | "right-start" | "right-end" [default: bottom]
+
+Never do:
+- ❌ placement="top-center" → ✅ Use placement="top" for centered placement
+
+## Progress
+Visual progress indicator for tasks, uploads, or completion status.
+Import: `import { Progress } from "@usevyre/react"`
+
+Valid props:
+- size: "sm" | "md" | "lg" [default: md]
+- variant: "default" | "accent" | "teal" | "success" | "danger" [default: default]
+
+Never do:
+- ❌ value > 100 → ✅ Normalize your value to 0–100 range before passing
+
+## Select
+Dropdown for selecting one option from a list.
+Import: `import { Select } from "@usevyre/react"`
+
+Valid props:
+- size: "sm" | "md" | "lg" [default: md]
+
+Never do:
+- ❌ Passing strings directly as children → ✅ Pass options={[{ value: 'a', label: 'Option A' }]}
+
+## Separator
+Horizontal or vertical divider line.
+Import: `import { Separator } from "@usevyre/react"`
+
+Valid props:
+- orientation: "horizontal" | "vertical" [default: horizontal]
+
+## Sheet
+Side panel (drawer) that slides in from the edge. For forms, detail views, or settings.
+Import: `import { Sheet, SheetHeader, SheetBody, SheetFooter } from "@usevyre/react"`
+
+Valid props:
+- size: "sm" | "md" | "lg" | "full" [default: md]
+- side: "left" | "right" [default: right]
+
+## Sidebar
+App navigation sidebar. Use AppLayout as the root layout wrapper.
+Import: `import { AppLayout, Sidebar, SidebarHeader, SidebarContent, SidebarSection, SidebarItem, SidebarFooter } from "@usevyre/react"`
+
+Valid props:
+- variant: "default" | "floating" [default: default]
+
+## Skeleton
+Loading placeholder that mimics the shape of content while data loads.
+Import: `import { Skeleton } from "@usevyre/react"`
+
+Valid props:
+- variant: "rect" | "circle" | "text" [default: rect]
+
+## Slider
+Range input for selecting a numeric value within a range.
+Import: `import { Slider } from "@usevyre/react"`
+
+Valid props:
+- size: "sm" | "md" [default: md]
+
+## Switch
+Toggle switch for boolean on/off settings.
+Import: `import { Switch } from "@usevyre/react"`
+
+Valid props:
+- size: "sm" | "md" [default: md]
+
+## Table
+Data table with optional sorting. Compose with TableHeader, TableRow, TableCell.
+Import: `import { Table, TableHead, TableBody, TableRow, TableHeader, TableCell } from "@usevyre/react"`
+
+## Tabs
+Tabbed navigation for switching between content panels.
+Import: `import { Tabs, TabList, Tab, TabPanels, TabPanel } from "@usevyre/react"`
+
+Valid props:
+
+## Toast
+Transient notification. Use the useToast hook to trigger toasts imperatively.
+Import: `import { useToast, ToastProvider } from "@usevyre/react"`
+
+Valid props:
+- variant: "default" | "success" | "warning" | "danger" [default: default]
+
+Never do:
+- ❌ Rendering <Toast> directly in JSX → ✅ Use: const { toast } = useToast(); then toast({ title, variant })
+- ❌ variant="error" → ✅ Use variant="danger"
+- ❌ variant="info" → ✅ Use variant="default"
+
+## Tooltip
+Short label that appears on hover/focus. For rich content use Popover instead.
+Import: `import { Tooltip } from "@usevyre/react"`
+
+Valid props:
+- placement: "top" | "bottom" | "left" | "right" [default: top]
+
+Never do:
+- ❌ Using Tooltip for rich content (forms, buttons, etc.) → ✅ Use Popover for rich interactive content
+
+## Typography
+Text rendering components with semantic scale. Includes Text, Heading, Lead, Code, Blockquote.
+Import: `import { Text, Heading, Lead, Code, Blockquote } from "@usevyre/react"`
+
+Never do:
+- ❌ Using raw <h1>, <p> tags instead of Typography components → ✅ Use <Heading>, <Text>, <Lead> from @usevyre/react
+
+## Token Rules
 
-## Common Patterns
-
-### Page layout with sidebar
-```tsx
-<div style={{ display: "grid", gridTemplateColumns: "260px 1fr", minHeight: "100vh" }}>
-  <aside style={{ background: "var(--vyre-color-semantic-surface)", borderRight: "1px solid var(--vyre-color-semantic-border-subtle)" }}>
-    {/* sidebar content */}
-  </aside>
-  <main style={{ padding: "var(--vyre-spacing-12)" }}>
-    {/* main content */}
-  </main>
-</div>
-```
-
-### Form with validation
-```tsx
-<form>
-  <Field label="Email" state={errors.email ? "error" : "idle"} hint={errors.email}>
-    <Input type="email" value={email} onChange={e => setEmail(e.target.value)} />
-  </Field>
-  <Button variant="accent" type="submit" loading={isSubmitting}>
-    Submit
-  </Button>
-</form>
-```
-
-### Status badge with live indicator
-```tsx
-<Badge variant="success" dot>Live</Badge>
-<Badge variant="danger" dot>Offline</Badge>
-<Badge variant="warning">Beta</Badge>
-```
+Use --vyre-color-semantic-* for all colors. Never use primitive tokens.
+Use --vyre-spacing-* for all spacing. Never use raw px in component code.
+Use --vyre-border-radius-* for border radius.