# Frontend Design System

## UI Components (`@{{PROJECT_NAME}}/ui`)

Available components from `packages/ui`:

| Component | Import | Variants |
|-----------|--------|----------|
| Button | `Button` | default, destructive, outline, secondary, ghost, link |
| Card | `Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter` | - |
| Input | `Input` | - |
| Label | `Label` | - |
| Badge | `Badge` | default, secondary, outline, success, warning, error, info |
| Dialog | `Dialog, DialogTrigger, DialogContent, DialogHeader, DialogTitle, DialogDescription, DialogFooter, DialogClose` | - |
| Table | `Table, TableHeader, TableBody, TableRow, TableHead, TableCell` | - |
| Select | `Select, SelectTrigger, SelectContent, SelectItem, SelectValue` | - |
| Checkbox | `Checkbox` | - |
| Alert | `Alert, AlertTitle, AlertDescription` | default, destructive, success, warning |
| Textarea | `Textarea` | - |
| DropdownMenu | `DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem, ...` | - |
| Sheet | `Sheet, SheetTrigger, SheetContent, SheetHeader, SheetTitle, SheetDescription, SheetFooter` | side: top, right, bottom, left |

Usage:
```tsx
import { Button, Badge, Card, CardContent } from '@{{PROJECT_NAME}}/ui';

<Card>
  <CardContent>
    <Badge variant="success">Active</Badge>
    <Button variant="outline">Edit</Button>
  </CardContent>
</Card>
```

## CSS Tokens

All components use CSS custom properties for theming. Define these in your app's globals.css:

### Colors
- `--background` - Page background
- `--surface-100` - Card/input backgrounds
- `--surface-200` - Hover states, secondary surfaces
- `--text-primary` - Main text
- `--text-secondary` - Secondary text
- `--text-muted` - Placeholder, hint text
- `--accent` - Primary accent color
- `--accent-foreground` - Text on accent
- `--border` - Border color

### Semantic Colors
- `--success`, `--success-bg`, `--success-border` - Success states
- `--warning`, `--warning-bg`, `--warning-border` - Warning states
- `--error`, `--error-bg`, `--error-border` - Error states
- `--info`, `--info-bg`, `--info-border` - Info states

### Z-Index
- `--z-popover` - Dropdowns, tooltips
- `--z-modal` - Dialogs, sheets

Import base tokens: `import '@{{PROJECT_NAME}}/ui/styles';`

## Layout (`@{{PROJECT_NAME}}/layout`)

DashboardShell provides the standard app layout:

```tsx
import { DashboardShell, Sidebar, Header } from '@{{PROJECT_NAME}}/layout';

<DashboardShell
  sidebar={<Sidebar items={navItems} />}
  header={<Header title="Dashboard" />}
>
  {children}
</DashboardShell>
```

## Auth (`@{{PROJECT_NAME}}/auth`)

AuthProvider and ProtectedRoute for client-side auth:

```tsx
import { AuthProvider, ProtectedRoute, useAuth } from '@{{PROJECT_NAME}}/auth';

// Wrap app in AuthProvider
<AuthProvider>
  <App />
</AuthProvider>

// Protect routes
<ProtectedRoute>
  <DashboardPage />
</ProtectedRoute>

// Access auth state
const { user, isAuthenticated, login, logout } = useAuth();
```

## API Client (`@{{PROJECT_NAME}}/api-client`)

Typed API client with auth:

```tsx
import { createAPIClient } from '@{{PROJECT_NAME}}/api-client';

const api = createAPIClient({
  baseURL: process.env.NEXT_PUBLIC_API_URL,
});

// Use in server actions or client components
const items = await api.examples.list();
const item = await api.examples.get(id);
await api.examples.create({ name: 'New Item' });
```

## Icons

Re-exported from lucide-react via `@{{PROJECT_NAME}}/ui`:

```tsx
import { Plus, Search, Settings, Trash2, User } from '@{{PROJECT_NAME}}/ui';
```

## Dark Theme

All components default to dark theme using CSS variables. The design system is dark-first with surface layering (surface-100 lighter than background, surface-200 lighter than surface-100).
