@neynar/ui/docs/llm/colors.md

React UI component library built on shadcn/ui and Tailwind CSS

# 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