@neynar/ui 0.1.1

package/docs/llm/colors.md

@@ -0,0 +1,273 @@
+# Colors - LLM Reference Guide
+
+This document provides AI assistants with precise Tailwind CSS class references for the @neynar/ui design system colors.
+
+## Available Tailwind Classes
+
+### Background Colors
+
+#### Core Backgrounds
+```
+bg-background           /* Primary page background */
+bg-foreground           /* High contrast background (rare use) */
+bg-card                 /* Elevated container background */
+bg-popover              /* Overlay/dropdown background */
+```
+
+#### Brand & Action Colors
+```
+bg-primary              /* Farcaster Purple - primary actions */
+bg-secondary            /* Secondary actions, subtle emphasis */
+bg-muted                /* Subtle backgrounds, disabled states */
+bg-accent               /* Subtle accent backgrounds */
+```
+
+#### State Colors
+```
+bg-destructive          /* Error states, dangerous actions */
+bg-success              /* Success states, confirmations */
+bg-warning              /* Warning states, cautions */
+```
+
+#### Interactive Elements
+```
+bg-input                /* Form field backgrounds */
+bg-border               /* Not typically used as background */
+```
+
+#### Chart Colors
+```
+bg-chart-1              /* Data visualization - Blue 1 */
+bg-chart-2              /* Data visualization - Blue 2 */
+bg-chart-3              /* Data visualization - Purple 1 */
+bg-chart-4              /* Data visualization - Purple 2 */
+bg-chart-5              /* Data visualization - Violet */
+```
+
+#### Sidebar Colors
+```
+bg-sidebar              /* Sidebar container background */
+bg-sidebar-primary      /* Active sidebar items */
+bg-sidebar-accent       /* Sidebar accent backgrounds */
+```
+
+### Text Colors
+
+#### Core Text Colors
+```
+text-foreground         /* Primary text color */
+text-background         /* Inverse text (rare use) */
+text-card-foreground    /* Text on card backgrounds */
+text-popover-foreground /* Text on popover backgrounds */
+```
+
+#### Brand & Action Text Colors
+```
+text-primary            /* Primary color text (not on backgrounds) */
+text-primary-foreground /* Text on primary backgrounds */
+text-secondary          /* Secondary color text (not on backgrounds) */
+text-secondary-foreground /* Text on secondary backgrounds */
+text-muted-foreground   /* Muted text, secondary information */
+text-accent-foreground  /* Text on accent backgrounds */
+```
+
+#### State Text Colors
+```
+text-destructive        /* Error text (not on backgrounds) */
+text-destructive-foreground /* Text on destructive backgrounds */
+text-success            /* Success text (not on backgrounds) */
+text-success-foreground /* Text on success backgrounds */
+text-warning            /* Warning text (not on backgrounds) */
+text-warning-foreground /* Text on warning backgrounds */
+```
+
+#### Sidebar Text Colors
+```
+text-sidebar-foreground /* Text in sidebar */
+text-sidebar-primary-foreground /* Text on active sidebar items */
+text-sidebar-accent-foreground  /* Text on sidebar accent backgrounds */
+```
+
+### Border Colors
+
+```
+border-border           /* Default border color */
+border-input            /* Form field borders */
+border-ring             /* Not typically used for borders */
+border-primary          /* Primary color borders */
+border-secondary        /* Secondary color borders */
+border-muted            /* Muted borders */
+border-accent           /* Accent borders */
+border-destructive      /* Error borders */
+border-success          /* Success borders */
+border-warning          /* Warning borders */
+border-sidebar-border   /* Sidebar borders */
+```
+
+### Ring Colors (Focus States)
+
+```
+ring-ring               /* Default focus ring */
+ring-primary            /* Primary focus ring */
+ring-destructive        /* Error focus ring */
+ring-success            /* Success focus ring */
+ring-warning            /* Warning focus ring */
+ring-sidebar-ring       /* Sidebar focus ring */
+```
+
+## Usage Patterns
+
+### Proper Color Pairing
+
+**Always pair backgrounds with their corresponding foreground colors:**
+
+```tsx
+// ✅ Correct pairing
+<div className="bg-primary text-primary-foreground">Primary button</div>
+<div className="bg-secondary text-secondary-foreground">Secondary button</div>
+<div className="bg-card text-card-foreground">Card content</div>
+<div className="bg-muted text-muted-foreground">Muted content</div>
+
+// ❌ Incorrect pairing (poor contrast)
+<div className="bg-primary text-foreground">Bad contrast</div>
+<div className="bg-secondary text-primary">Wrong pairing</div>
+```
+
+### Common Component Patterns
+
+#### Buttons
+```tsx
+/* Primary button */
+<button className="bg-primary text-primary-foreground hover:bg-primary/90">
+  Primary Action
+</button>
+
+/* Secondary button */
+<button className="bg-secondary text-secondary-foreground hover:bg-secondary/80">
+  Secondary Action
+</button>
+
+/* Destructive button */
+<button className="bg-destructive text-destructive-foreground hover:bg-destructive/90">
+  Delete
+</button>
+```
+
+#### Cards
+```tsx
+/* Standard card */
+<div className="bg-card text-card-foreground border border-border rounded-lg">
+  Card content
+</div>
+
+/* Muted card */
+<div className="bg-muted text-muted-foreground rounded-lg">
+  Subtle card
+</div>
+```
+
+#### Form Fields
+```tsx
+/* Input field */
+<input className="bg-input text-foreground border border-input rounded-md focus:ring-2 focus:ring-ring" />
+
+/* Error state */
+<input className="bg-input text-foreground border border-destructive rounded-md focus:ring-2 focus:ring-destructive" />
+```
+
+#### Status Messages
+```tsx
+/* Success message */
+<div className="bg-success text-success-foreground p-4 rounded-lg">
+  Success message
+</div>
+
+/* Error message */
+<div className="bg-destructive text-destructive-foreground p-4 rounded-lg">
+  Error message
+</div>
+
+/* Warning message */
+<div className="bg-warning text-warning-foreground p-4 rounded-lg">
+  Warning message
+</div>
+```
+
+### Text-Only Color Usage
+
+For text that isn't on a colored background, use these classes:
+
+```tsx
+/* Primary color text */
+<span className="text-primary">Primary link</span>
+
+/* Muted text */
+<span className="text-muted-foreground">Secondary information</span>
+
+/* Error text */
+<span className="text-destructive">Error message</span>
+
+/* Success text */
+<span className="text-success">Success message</span>
+
+/* Warning text */
+<span className="text-warning">Warning message</span>
+```
+
+## Color Opacity Modifiers
+
+Use opacity modifiers for hover states and variations:
+
+```tsx
+/* Hover states */
+<button className="bg-primary hover:bg-primary/90">Button</button>
+<button className="bg-secondary hover:bg-secondary/80">Button</button>
+
+/* Subtle backgrounds */
+<div className="bg-primary/10 text-primary">Subtle primary background</div>
+<div className="bg-destructive/10 text-destructive">Subtle error background</div>
+```
+
+## Theme Adaptation
+
+All colors automatically adapt between light and dark themes. No additional classes needed:
+
+```tsx
+/* This automatically uses light colors in light mode, dark colors in dark mode */
+<div className="bg-background text-foreground">
+  Content adapts to theme
+</div>
+
+<div className="bg-card text-card-foreground border border-border">
+  Card adapts to theme
+</div>
+```
+
+## Color Hierarchy
+
+Use this hierarchy for importance:
+
+1. **Primary** - Most important actions, brand elements
+2. **Secondary** - Secondary actions, less prominent elements
+3. **Accent** - Subtle emphasis, information highlights
+4. **Muted** - Background elements, disabled states
+5. **Foreground/Background** - Base content
+
+## Accessibility Notes
+
+- All color combinations maintain WCAG AA contrast ratios (4.5:1 minimum)
+- Always use foreground colors with their corresponding backgrounds
+- Use state colors (destructive, success, warning) appropriately for user feedback
+- Focus rings provide clear visual focus indicators
+
+## Quick Reference
+
+**Most Common Classes:**
+- `bg-background text-foreground` - Page content
+- `bg-card text-card-foreground` - Cards, containers
+- `bg-primary text-primary-foreground` - Primary buttons
+- `bg-secondary text-secondary-foreground` - Secondary buttons
+- `text-muted-foreground` - Secondary text
+- `border-border` - Default borders
+- `bg-destructive text-destructive-foreground` - Error states
+- `bg-success text-success-foreground` - Success states

package/docs/llm/components/buttons.md

@@ -0,0 +1,68 @@
+# Button Components
+
+## Button
+
+Primary interactive element with multiple variants and sizes.
+
+```tsx
+import { Button } from "@neynar/ui"
+
+// Basic usage
+<Button onClick={() => console.log("clicked")}>Click me</Button>
+
+// Variants
+<Button variant="default">Default</Button>
+<Button variant="destructive">Delete</Button>
+<Button variant="outline">Outline</Button>
+<Button variant="secondary">Secondary</Button>
+<Button variant="ghost">Ghost</Button>
+<Button variant="link">Link</Button>
+
+// Sizes
+<Button size="sm">Small</Button>
+<Button size="default">Default</Button>
+<Button size="lg">Large</Button>
+<Button size="icon">🔥</Button>
+
+// AsChild pattern - renders as different element
+<Button asChild>
+  <a href="/profile">Go to Profile</a>
+</Button>
+```
+
+## Toggle
+
+Single toggle state component for on/off interactions.
+
+```tsx
+import { Toggle } from "@neynar/ui"
+
+<Toggle pressed={isPressed} onPressedChange={setIsPressed}>
+  Bold
+</Toggle>
+
+<Toggle variant="outline" size="sm">
+  Italic
+</Toggle>
+```
+
+## ToggleGroup
+
+Group of related toggles with single or multiple selection.
+
+```tsx
+import { ToggleGroup, ToggleGroupItem } from "@neynar/ui"
+
+// Single selection
+<ToggleGroup type="single" value={align} onValueChange={setAlign}>
+  <ToggleGroupItem value="left">Left</ToggleGroupItem>
+  <ToggleGroupItem value="center">Center</ToggleGroupItem>
+  <ToggleGroupItem value="right">Right</ToggleGroupItem>
+</ToggleGroup>
+
+// Multiple selection
+<ToggleGroup type="multiple" value={features} onValueChange={setFeatures}>
+  <ToggleGroupItem value="bold">Bold</ToggleGroupItem>
+  <ToggleGroupItem value="italic">Italic</ToggleGroupItem>
+</ToggleGroup>
+```

package/docs/llm/components/cards.md

@@ -0,0 +1,53 @@
+# Cards
+
+Card components for structured content with semantic sections.
+
+## Components
+
+```typescript
+import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from "@neynar/ui"
+```
+
+## Basic Structure
+
+```tsx
+<Card>
+  <CardHeader>
+    <CardTitle>Card Title</CardTitle>
+    <CardDescription>Optional description text</CardDescription>
+  </CardHeader>
+  <CardContent>
+    Main content area
+  </CardContent>
+  <CardFooter>
+    Footer actions or metadata
+  </CardFooter>
+</Card>
+```
+
+## Composition Patterns
+
+```tsx
+// Profile card
+<Card>
+  <CardHeader>
+    <CardTitle>@username</CardTitle>
+    <CardDescription>User bio text</CardDescription>
+  </CardHeader>
+  <CardContent>
+    <Avatar />
+    <p>Additional profile details</p>
+  </CardContent>
+  <CardFooter>
+    <Button>Follow</Button>
+  </CardFooter>
+</Card>
+
+// Data card with minimal sections
+<Card>
+  <CardContent>
+    <h3>Analytics</h3>
+    <p>Key metrics and data</p>
+  </CardContent>
+</Card>
+```

package/docs/llm/components/display.md

@@ -0,0 +1,134 @@
+# Display Components
+
+## Avatar
+User profile pictures with fallbacks and status indicators.
+
+```tsx
+import { Avatar, AvatarImage, AvatarFallback } from "@neynar/ui"
+
+// Basic avatar with fallback
+<Avatar>
+  <AvatarImage src="/user.jpg" alt="User" />
+  <AvatarFallback>JD</AvatarFallback>
+</Avatar>
+
+// Sizes: sm, default, lg
+<Avatar className="h-6 w-6">
+  <AvatarImage src="/user.jpg" />
+  <AvatarFallback>U</AvatarFallback>
+</Avatar>
+```
+
+## Typography
+Consistent text styling with semantic variants and accessibility features.
+
+```tsx
+import { Typography } from "@neynar/ui"
+
+// Basic usage with semantic variants
+<Typography variant="heading" as="h1">
+  Main Page Title
+</Typography>
+
+<Typography variant="subheading" as="h2">
+  Section Header
+</Typography>
+
+<Typography variant="body">
+  Standard paragraph text content with proper line height and spacing.
+</Typography>
+
+<Typography variant="bodyEmphasized">
+  Emphasized text for important information.
+</Typography>
+
+// Color and styling options
+<Typography variant="body" color="muted">
+  Secondary information in muted color
+</Typography>
+
+<Typography variant="details" color="destructive">
+  Error or warning text
+</Typography>
+
+// Form field labels
+<Typography variant="field" as="label" htmlFor="email">
+  Email Address
+</Typography>
+
+// Code snippets
+<Typography variant="code" as="code">
+  const example = "Hello, world!";
+</Typography>
+
+// Table content
+<Typography variant="tableHeader" as="th">
+  Column Header
+</Typography>
+
+<Typography variant="tableCell" as="td">
+  Cell content
+</Typography>
+
+// Microcopy for fine print
+<Typography variant="microcopy" color="muted">
+  Terms and conditions apply
+</Typography>
+
+// Advanced styling
+<Typography 
+  variant="body" 
+  color="accent" 
+  italic 
+  underline 
+  align="center"
+>
+  Styled text with multiple options
+</Typography>
+
+// Truncated text
+<Typography variant="body" truncate className="max-w-xs">
+  Long text that will be truncated with ellipsis
+</Typography>
+
+// Screen reader only content
+<Typography variant="details" srOnly>
+  Additional context for accessibility
+</Typography>
+```
+
+## Chart
+Data visualization using Recharts with consistent theming.
+
+```tsx
+import { ChartContainer, ChartTooltip, ChartTooltipContent } from "@neynar/ui"
+import { Bar, BarChart, ResponsiveContainer } from "recharts"
+
+<ChartContainer config={{ value: { label: "Value", color: "hsl(var(--chart-1))" } }}>
+  <BarChart data={data}>
+    <Bar dataKey="value" fill="var(--color-value)" />
+    <ChartTooltip content={<ChartTooltipContent />} />
+  </BarChart>
+</ChartContainer>
+```
+
+## Carousel
+Image/content slideshows with navigation controls.
+
+```tsx
+import { Carousel, CarouselContent, CarouselItem, CarouselPrevious, CarouselNext } from "@neynar/ui"
+
+<Carousel className="w-full max-w-xs">
+  <CarouselContent>
+    {items.map((item, index) => (
+      <CarouselItem key={index}>
+        <div className="p-1">
+          <img src={item.image} alt={item.title} />
+        </div>
+      </CarouselItem>
+    ))}
+  </CarouselContent>
+  <CarouselPrevious />
+  <CarouselNext />
+</Carousel>
+```

package/docs/llm/components/feedback.md

@@ -0,0 +1,96 @@
+# Feedback Components
+
+Components for providing user feedback, status updates, and progress indicators.
+
+## Alert
+
+Display important messages with different severity levels.
+
+```tsx
+import { Alert, AlertDescription, AlertTitle } from "@neynar/ui"
+import { AlertCircle, CheckCircle2 } from "lucide-react"
+
+// Error alert
+<Alert variant="destructive">
+  <AlertCircle className="h-4 w-4" />
+  <AlertTitle>Error</AlertTitle>
+  <AlertDescription>Failed to load cast data.</AlertDescription>
+</Alert>
+
+// Success alert
+<Alert>
+  <CheckCircle2 className="h-4 w-4" />
+  <AlertTitle>Success</AlertTitle>
+  <AlertDescription>Cast published successfully.</AlertDescription>
+</Alert>
+```
+
+## Badge
+
+Show status, categories, or metadata with colored labels.
+
+```tsx
+import { Badge } from "@neynar/ui"
+
+<Badge variant="default">Active</Badge>
+<Badge variant="secondary">Draft</Badge>
+<Badge variant="destructive">Failed</Badge>
+<Badge variant="outline">Pending</Badge>
+```
+
+## Progress
+
+Visual progress indicators for loading states and operations.
+
+```tsx
+import { Progress } from "@neynar/ui"
+
+<Progress value={65} className="w-full" />
+<Progress value={uploadProgress} max={100} />
+```
+
+## Skeleton
+
+Loading placeholders that match content structure.
+
+```tsx
+import { Skeleton } from "@neynar/ui"
+
+// Loading cast card
+<div className="space-y-3">
+  <Skeleton className="h-4 w-[250px]" />
+  <Skeleton className="h-4 w-[200px]" />
+  <Skeleton className="h-16 w-full" />
+</div>
+```
+
+## EmptyState
+
+Handle empty data scenarios with helpful messaging.
+
+```tsx
+import { EmptyState } from "@neynar/ui"
+
+<EmptyState 
+  title="No casts found"
+  description="Try adjusting your search criteria"
+  action={<Button>Refresh</Button>}
+/>
+```
+
+## Sonner (Toast)
+
+Non-blocking notifications for actions and events.
+
+```tsx
+import { toast } from "sonner"
+
+// Success toast
+toast.success("Cast published successfully")
+
+// Error toast
+toast.error("Failed to publish cast")
+
+// Loading toast
+toast.loading("Publishing cast...")
+```