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

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

# @neynar/ui Composition Guide

Essential patterns for building interfaces with @neynar/ui components. Focus on practical composition techniques and TypeScript best practices.

## Import Patterns

```typescript
// ✅ Correct - named imports with alias
import { Button, Card, CardContent, CardHeader, CardTitle } from "@neynar/ui"
import { useIsMobile, cn } from "@neynar/ui"

// ❌ Avoid - relative imports or default exports
import { Button } from "./ui/button"
import Button from "@neynar/ui"
```

## Component Composition

### Card-Based Layouts
Cards are the primary container component. Always use sub-components for structure:

```typescript
import { Card, CardHeader, CardTitle, CardContent, CardFooter, Button } from "@neynar/ui"

function UserProfile() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>User Settings</CardTitle>
      </CardHeader>
      <CardContent>
        <p>Manage your account preferences</p>
      </CardContent>
      <CardFooter>
        <Button>Save Changes</Button>
      </CardFooter>
    </Card>
  )
}
```

### Form Patterns
Combine form components with consistent spacing:

```typescript
import { Label, Input, Button, Card, CardContent } from "@neynar/ui"

function LoginForm() {
  return (
    <Card className="w-96">
      <CardContent className="space-y-4 pt-6">
        <div className="space-y-2">
          <Label htmlFor="email">Email</Label>
          <Input id="email" type="email" placeholder="Enter email" />
        </div>
        <div className="space-y-2">
          <Label htmlFor="password">Password</Label>
          <Input id="password" type="password" />
        </div>
        <Button className="w-full">Sign In</Button>
      </CardContent>
    </Card>
  )
}
```

## Responsive Patterns

Use `useIsMobile` for adaptive layouts:

```typescript
import { useIsMobile, Dialog, Sheet, Button } from "@neynar/ui"

function ResponsiveModal({ children }) {
  const isMobile = useIsMobile()
  
  const Wrapper = isMobile ? Sheet : Dialog
  
  return (
    <Wrapper>
      <Button>Open Modal</Button>
      {children}
    </Wrapper>
  )
}
```

## Data Display

Combine table components for structured data:

```typescript
import { Table, TableHeader, TableBody, TableRow, TableHead, TableCell } from "@neynar/ui"

function UserTable({ users }) {
  return (
    <Table>
      <TableHeader>
        <TableRow>
          <TableHead>Name</TableHead>
          <TableHead>Email</TableHead>
        </TableRow>
      </TableHeader>
      <TableBody>
        {users.map(user => (
          <TableRow key={user.id}>
            <TableCell>{user.name}</TableCell>
            <TableCell>{user.email}</TableCell>
          </TableRow>
        ))}
      </TableBody>
    </Table>
  )
}
```

## TypeScript Patterns

Always use function declarations and type definitions:

```typescript
import { Button, type ButtonProps } from "@neynar/ui"

// ✅ Function declaration with types
function CustomButton({ variant = "default", ...props }: ButtonProps) {
  return <Button variant={variant} {...props} />
}

// ❌ Avoid const/arrow functions for components
const CustomButton = ({ variant = "default", ...props }: ButtonProps) => {
  return <Button variant={variant} {...props} />
}
```

## Utility Usage

Use `cn()` for conditional styling:

```typescript
import { Button, cn } from "@neynar/ui"

function StatusButton({ isActive, children }) {
  return (
    <Button 
      className={cn(
        "transition-colors",
        isActive && "bg-green-500 hover:bg-green-600"
      )}
    >
      {children}
    </Button>
  )
}
```

## Common Patterns Summary

1. **Always use named imports** from `@neynar/ui`
2. **Function declarations** for all components
3. **Type definitions** instead of interfaces
4. **Composition over configuration** - combine simple components
5. **Use `useIsMobile`** for responsive behavior
6. **Leverage `cn()`** for conditional classes
7. **Structure with Cards** for most layouts
8. **Consistent spacing** with Tailwind classes like `space-y-4`