AI Context

Why it matters

AI agents don't read source code — they predict tokens. Without an explicit reference, they invent props by analogy: color="red", size="xl", type="error". These compile silently and fail at runtime.

// ❌ Without useVyre AI context
// Prompt: "Build a danger button with extra-large size"

<Button color="red" size="xl">Delete</Button>
//       ^^^^^^^^^^  ^^^^^^^^
//       'color' prop doesn't exist on Button
//       'xl' is not a valid size — max is 'lg'
// Result: TypeScript error + runtime warning

// ✅ With useVyre AI context
// Same prompt — agent reads context first

<Button variant="danger" size="lg">Delete</Button>
// Correct on the first try. No edits needed.

// ❌ Without context
// Prompt: "Add email validation to this field"

<Input type="email" error="Invalid email" />
//                  ^^^^^^^^^^^^^^^^^^^^
//  'error' prop doesn't exist. The pattern is:
//  Field wrapper with state + hint props.
// Result: prop silently ignored, no visual feedback

// ✅ With context
// Agent knows Field wraps Input and carries state

<Field label="Email" state="error" hint="Invalid email">
  <Input type="email" value={email} onChange={...} />
</Field>
// Correct validation UI, first try.

Setup

Option 1 — npx init (recommended)

Run once in your project root. Writes a ready-to-use context block into your agent's rules file. Re-run after upgrading @usevyre packages to pick up changes.

npx @usevyre/ai-context --claude
# → writes CLAUDE.md with full context
# Re-run after upgrading @usevyre packages to pick up changes

npx @usevyre/ai-context --cursor
# → writes .cursor/rules with full context
# Re-run after upgrading @usevyre packages to pick up changes

npx @usevyre/ai-context --windsurf
# → writes .windsurf/rules with full context
# Re-run after upgrading @usevyre packages to pick up changes

Option 2 — Paste manually

Copy the block below into CLAUDE.md, .cursor/rules, AGENTS.md, or .github/copilot-instructions.md.

# useVyre AI Context
# Paste into: CLAUDE.md · .cursor/rules · AGENTS.md · .github/copilot-instructions.md

## Design System: useVyre

### Token naming convention
--vyre-[category]-[subcategory]-[variant]

### Theme system
- Light theme: :root or [data-theme="light"]
- Dark theme: [data-theme="dark"]
- Auto: follows prefers-color-scheme when no data-theme is set
- Semantic tokens adapt automatically — never branch on theme manually

### Semantic color tokens (always use these, never primitive)
--vyre-color-semantic-background       — Page background
--vyre-color-semantic-surface          — Cards, panels
--vyre-color-semantic-surface-raised   — Dropdowns, popovers
--vyre-color-semantic-surface-overlay  — Modals, tooltips
--vyre-color-semantic-border           — Default borders
--vyre-color-semantic-border-subtle    — Low-contrast dividers
--vyre-color-semantic-border-strong    — Focus rings, selected
--vyre-color-semantic-text-primary     — Headings, body
--vyre-color-semantic-text-secondary   — Subtitles, descriptions
--vyre-color-semantic-text-muted       — Placeholders, helper text
--vyre-color-semantic-text-disabled    — Disabled state
--vyre-color-semantic-text-inverse     — Text on dark/accent bg
--vyre-color-semantic-accent           — Brand CTAs, focus rings
--vyre-color-semantic-accent-hover     — Hover on accent
--vyre-color-semantic-accent-foreground — Text on accent bg
--vyre-color-semantic-accent-subtle    — Badge backgrounds
--vyre-color-semantic-teal             — Secondary accent, code
--vyre-color-semantic-success          — Confirmations
--vyre-color-semantic-warning          — Warnings, beta
--vyre-color-semantic-danger           — Errors, destructive

### Styling rules
1. NEVER use --vyre-color-primitive-* in components
2. ALWAYS use semantic tokens for color decisions
3. Interactive hover states: use -hover suffix tokens
4. Low-opacity backgrounds: use -subtle suffix tokens
5. Text hierarchy: text-primary > text-secondary > text-muted > text-disabled
6. Text on colored bg: use text-inverse or accent-foreground

### Component data attributes
data-variant="primary|secondary|ghost|accent|teal|danger"
data-size="sm|md|lg|icon"
data-state="error|success|warning|idle"
data-checked — boolean presence attribute (Switch, Checkbox)
data-disabled — boolean presence attribute
data-indeterminate — boolean presence attribute (Checkbox)
data-placement="top|bottom|left|right" — Tooltip

### React import pattern
import { Button, Badge, Card, CardHeader, CardBody, CardFooter } from "@usevyre/react";
import { Input, Field, Textarea, Select } from "@usevyre/react";
import { Modal, ModalHeader, ModalBody, ModalFooter } from "@usevyre/react";
import { Tabs, TabList, Tab, TabPanels, TabPanel } from "@usevyre/react";
import { Tooltip, ToastProvider, useToast } from "@usevyre/react";
import { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from "@usevyre/react";
import { Avatar, Checkbox, Switch, Progress, Slider } from "@usevyre/react";
import { Separator, Label, Skeleton } from "@usevyre/react";

### Vue import pattern
import { Button, Badge, Card, CardHeader, CardBody, CardFooter } from "@usevyre/vue";
import { Input, Field, Textarea, Select } from "@usevyre/vue";
import { Modal, ModalHeader, ModalBody, ModalFooter } from "@usevyre/vue";
import { Tabs, TabList, Tab, TabPanels, TabPanel } from "@usevyre/vue";
import { Tooltip, ToastViewport, useToast } from "@usevyre/vue";
import { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from "@usevyre/vue";
import { Avatar, Checkbox, Switch, Progress, Slider } from "@usevyre/vue";
import { Separator, Label, Skeleton } from "@usevyre/vue";

### Key behavioral differences React vs Vue
- React: controlled state via value+onChange / checked+onCheckedChange / onValueChange
- Vue: controlled state via v-model (modelValue + update:modelValue)
- React: Toast needs <ToastProvider> wrapping the app
- Vue: Toast needs <ToastViewport> placed once in layout
- React: Modal closes via onClose prop
- Vue: Modal closes via @close event

Option 3 — Reference generated file (monorepo)

After building the tokens package, a full context file is written to packages/tokens/dist/ai-context.md. Reference it directly — it updates automatically when you rebuild.

# CLAUDE.md
# Reference the generated file — always stays up to date with package versions.
See @packages/tokens/dist/ai-context.md for the full token + component reference.

# .cursor/rules
# Reference or paste the contents of:
# packages/tokens/dist/ai-context.md

Validate AI-generated code

Run @usevyre/validate-ai-context after AI generation to catch any hallucinated props before they hit CI. Works as a one-off check or in a GitHub Actions workflow.

npx @usevyre/validate-ai-context src/

# ❌ dashboard.tsx:12
#    <Button> has no "color" prop
#    → Use variant prop instead
#
# ❌ dashboard.tsx:18
#    <Button size="xl"> — "xl" is not a valid value
#    → Valid: "sm" | "md" | "lg" | "icon"
#
# Scanned 4 files · 2 errors

See the validate-ai-context docs for CI integration and all available flags.

Keeping context up to date

The context block is versioned alongside the packages. When you upgrade @usevyre/react or @usevyre/vue, re-run the init command to pick up any new props, renamed variants, or removed anti-patterns.

# Re-generate context after upgrading @usevyre packages
npx @usevyre/ai-context --claude   # updates CLAUDE.md section in-place

# Or rebuild manually in a monorepo
pnpm --filter @usevyre/tokens build
# → packages/tokens/dist/ai-context.md is regenerated

You can also check the context version programmatically:

import { versionInfo } from "@usevyre/ai-context/version-info";

console.log(versionInfo.version);      // "0.2.1"
console.log(versionInfo.validFor);     // "@usevyre/react >= 0.1.2"
console.log(versionInfo.generatedAt);  // "2026-05-08T..."

Troubleshooting

# This project uses @usevyre/react. Ignore Vue patterns below.

<ThirdPartyButton color="red" /> {/* vyre-ignore */}

What the context covers