f2:"ExplicitChatIdProvider" f3:I[903690,["$2c","$2d","$2e","$2f","$30","$31","$32","$33","$34","$35","$36","$37","$38","$39","$3a","$3b","$3c","$3d","$3e","$3f","$40","$41","$42","$43","$44","$45","$46","$47","$48","$49","$4a","$4b","$4c","$4d","$4e","$4f","$50","$51","$61","$62","$63","$64","$65","$66","$67","$68","$69","$6a","$6b","$6c","$6d","$6e","$6f","$70","$71"],"$f2"] f4:I[838238,["$2c","$2d","$2e","$2f","$30","$31","$32","$33","$34","$35","$36","$37","$38","$39","$3a","$3b","$3c","$3d","$3e","$3f","$40","$41","$42","$43","$44","$45","$46","$47","$48","$49","$4a","$4b","$4c","$4d","$4e","$4f","$50","$51","$61","$62","$63","$64","$65","$66","$67","$68","$69","$6a","$6b","$6c","$6d","$6e","$6f","$70","$71"],"SWRDataProvider"] f5:T26842,[V0_FILE]typescriptreact:file="app/preview-vWTYRgNuls6/page.tsx" type="code-project" import { Input } from '@vercel/geistcn/components/input' import { Button } from '@vercel/geistcn/components/button' export default function Page() { return (

) } [V0_FILE]css:file="app/globals.css" @import "tailwindcss"; @import '@vercel/geistcn/tailwind.css'; @import '@vercel/geistcn/styles.css'; /* Tell Tailwind to scan the geistcn package for class usage */ @source "../node_modules/@vercel/geistcn"; [V0_FILE]typescriptreact:file="app/layout.tsx" import type React from 'react' import type { Metadata } from 'next' import { Geist, Geist_Mono } from 'next/font/google' import { Analytics } from '@vercel/analytics/next' import { Providers } from './providers' import './globals.css' const _geist = Geist({ subsets: ['latin'] }) const _geistMono = Geist_Mono({ subsets: ['latin'] }) export const metadata: Metadata = { title: 'v0 App', description: 'Created with v0', generator: 'v0.app', } export default function RootLayout({ children, }: Readonly<{ children: React.ReactNode }>) { return ( {children} ) } [V0_FILE]typescriptreact:file="app/providers.tsx" 'use client' import type React from 'react' // ts-ignore-next-line import { GeistProvider } from '@vercel/geistcn/core/provider' export function Providers({ children }: { children: React.ReactNode }) { return {children} } [V0_FILE]javascript:file="postcss.config.mjs" export default { plugins: { '@tailwindcss/postcss': {}, }, } [V0_FILE]json:file="package.json" url="https://hebbkx1anhila5yf.public.blob.vercel-storage.com/package-Ds8g5coJgZ2NPwgytYgtdEcw3Oojbs.json" [V0_FILE]javascript:file="next.config.mjs" /** @type {import('next').NextConfig} */ const nextConfig = { typescript: { ignoreBuildErrors: true, }, images: { unoptimized: true, }, transpilePackages: [ '@vercel/geistcn', '@vercel/geist-test-utils', '@vercel/next-themes', ], experimental: { cssChunking: 'strict', }, modularizeImports: { '@vercel/geistcn/components': { transform: '@vercel/geist/components/{{ kebabCase member }}', skipDefaultConversion: true, }, '@vercel/geistcn/logos': { transform: '@vercel/geist/logos/{{ kebabCase member }}', skipDefaultConversion: true, }, }, } export default nextConfig [V0_FILE]plaintext:file="docs/.gitkeep" [V0_FILE]markdown:file="docs/available-components.md" # @vercel/geistcn Available Components This document lists all available exports from the `@vercel/geistcn` package. > **Note:** geistcn is a subset of @vercel/geist with ~86 components. Some components from the original geist package are not available. See the "Not Available" section at the end. ## Import Patterns ```tsx // Components - use modularized imports import { Button } from '@vercel/geistcn/components' import { Input } from '@vercel/geistcn/components/input' // Icons import { ArrowRight } from '@vercel/geistcn/icons' // Logos import { VercelLogo } from '@vercel/geistcn/logos' // Provider import { GeistProvider } from '@vercel/geistcn/core/provider' // Styles - use styles.css for all projects import '@vercel/geistcn/styles.css' ``` ## Components (86 Total) ### Avatar Components - `Avatar` - User avatar component - `AvatarGroup` - Group multiple avatars - `AvatarWithIcon` - Avatar with icon overlay - `GenericAvatar` - Generic avatar component - `GitHubAvatar` / `GitLabAvatar` / `BitbucketAvatar` - Service-specific avatars ### Form Components - `Button` - Primary button component (uses `variant` for style, `type` for HTML type) - `ButtonLink` - Button styled as a link - `CustomButton` - Custom button variant - `CustomButtonLink` - Custom button link variant - `Input` - Text input field - `ClearableInput` - Input with clear button - `SearchInput` - Search input field - `Checkbox` - Checkbox input - `Radio` - Radio button - `RadioGroup` - Radio button group with `useRadio` hook - `Select` - Dropdown select - `Textarea` - Multi-line text input - `Toggle` - Toggle switch - `Switch` - Switch component (Radix UI based) - `Combobox` - Searchable select with `ComboBoxHandle` - `MultiSelectRoot` / `MultiSelectTrigger` / `MultiSelectContent` / `MultiSelectRow` - Multi-select components ### Layout Components - `Grid` - Grid layout with responsive utilities - `Separator` - Separator/divider component (Radix-based) - `Fieldset` - Form fieldset with related components: - `FieldsetContent` - `FieldsetFooter` - `FieldsetSubtitle` - `FieldsetTabs` - `FieldsetTitle` - `DisabledWall` - `ErrorText` - `WarningText` ### Navigation Components - `Menu` - Dropdown menu with `useMenu` hook - `MenuButton` - `MenuContainer` - `MenuDivider` - `MenuItem` - `MenuItemLocked` - `MenuLink` - `MenuSection` - `InnerMenu` - `InnerMenuItem` - `DotsMenu` - Three dots menu component - `Tabs` - Tab navigation - `Breadcrumbs` - Breadcrumb navigation - `Link` - Link component - `Sidebar` - Sidebar navigation - `SidebarLink` - Sidebar link item - `SidebarSection` - Sidebar section - `ScrollToSidebar` - Scroll to sidebar utility - `SkipNavLink` - Skip navigation link - `SkipNavContent` - Skip navigation content target ### Display Components - `Badge` - Status badge - `Card` - Card container - `ContextCard` - Context-aware card - `ErrorCard` - Error display card - `Code` / `InlineCode` - Code display - `CodeBlock` / `CodeBlockServer` - Code block with syntax highlighting - `Table` - Table components: - `TableRoot` - `TableHeader` - `TableHead` - `TableBody` - `TableFooter` - `TableRow` - `TableCell` - `TableCellLink` - `TableColgroup` - `TableCol` - `Text` - Text component - `Note` - Note/callout component - `Snippet` - Code snippet - `Tooltip` - Tooltip component - `TooltipContext` - Tooltip context provider - `Description` - Description text - `Kbd` - Keyboard key display - `StatusDot` - Status indicator dot - `Banner` - Banner component - `EmptyState` - Empty state display - `Gauge` - Gauge/progress indicator - `Image` - Image component - `PixelIcon` - Pixel icon component - `DeploymentStatus` - Deployment status indicator ### Feedback Components - `Toast` / `Toaster` - Toast notifications - `LoadingDots` - Loading dots indicator - `Spinner` - Spinner component - `Skeleton` - Skeleton loader - `Error` - Error component - `Feedback` - Feedback component ### Overlay Components - `Modal` - Modal dialog with subcomponents: - `Modal.Action` - `Modal.Actions` - `Modal.ButtonActions` - `Modal.Title` - `Modal.Subtitle` - `Modal.Body` - `Modal.Header` - `Modal.P` - `Modal.Error` - `Modal.Inset` - `Modal.Outset` - `Dialog` - Dialog component (Radix UI based) - `Drawer` - Slide-out drawer - `Sheet` - Sheet component - `ContextMenu` - Context menu component ### Interactive Components - `Collapse` - Collapsible content with `useCollapse` hook - `CollapseGroup` - Group of collapsible items - `CommandMenu` - Command palette with `useCommandMenu` hook - `CommandMenuPage` - `CommandMenuItemProps` - `SplitButton` - Split button with menu - `SplitButtonMenuItem` - `ShowMore` - Show more/less toggle - `ClickOutside` - Click outside detector - `CopyButton` - Copy to clipboard button - `TextWithCopyButton` - Text with copy button - `LoadMoreButton` - Load more button - `Slider` - Slider input component ### File Tree Components - `Tree` - File tree root - `Folder` - Folder in tree - `File` - File in tree ### Date & Time Components - `Calendar` - Calendar picker with types: - `CalendarTypes` - `CalendarProps` - `DateValue` - `Preset` / `Presets` - `RelativeTimeCard` - Relative time display ### Browser & Media Components - `Browser` - Browser mockup with components: - `Browser.Root` - `Browser.Header` - `Browser.AddressBar` - `Browser.HeaderRoot` - `Browser.HeaderItem` - `Browser.Dots` - `Browser.Controls` - `Video` - Video player component - `Phone` - Phone mockup component ### Project & Entity Components - `ProjectBanner` - Project banner component - `ProjectBannerLink` - Project banner link - `Entity` - Entity display component with subcomponents ### Utility Components - `ChoiceboxGroup` - Choice box group - `Keyboard` - Keyboard input handler - `Label` - Label component - `Pagination` - Pagination component - `ThemeSwitcher` - Theme switcher component (storybook variant available) ## Components NOT Available in geistcn The following components from @vercel/geist are **not available** in geistcn: - `Container` - Content container - `ContentWrapper` - Content wrapper - `Stack` / `ContainerStack` - Stack layouts - `Spacer` - Spacing component - `Divider` - Use `Separator` instead - `FragmentLink` - Fragment/anchor link - `Material` - Material component - `Book` - Book component - `Progress` - Progress bar - `SuspenseImage` - Image with suspense - `Scroller` - Scroll container ## Icons Import icons from `@vercel/geistcn/icons`: ```tsx import { ArrowRight, Check, X, Plus, Minus } from '@vercel/geistcn/icons' ``` Available utilities: - `getIconByName` - Get icon component by name - `nameToIcon` - Convert name to icon - Icon names list available at `@vercel/geistcn/icons/icon-names` The package includes 500+ icons covering: - Arrows and navigation - Actions and controls - Status indicators - File types and formats - Social media platforms - Developer tools - And many more... ## Logos Import logos from `@vercel/geistcn/logos`: ```tsx import { VercelLogo, NextjsLogo, TurboLogo, TurbopackLogo, V0Logo, AiSdkLogo, } from '@vercel/geistcn/logos' ``` Available logo formats: - Mark (icon only) - Wordmark (full logo with text) Also available: - `@vercel/geistcn/symbols/logos/*` - Logo symbols - `@vercel/geistcn/symbols/pixel/*` - Pixel logos - Logo names list and utilities ## Core ### Provider ```tsx import { GeistProvider } from '@vercel/geistcn/core/provider' // Wrap your app ; ``` ### Hooks - `useDisabledContext` - Access disabled context from `@vercel/geistcn/core/use-disabled-context` ## Styles ```tsx // Base styles - recommended for all projects import '@vercel/geistcn/styles.css' // Design system styles import '@vercel/geistcn/styles/design-system.css' // Syntax highlighting theme import '@vercel/geistcn/styles/syntax-theme.module.css' // Tailwind CSS base import '@vercel/geistcn/tailwind.css' ``` ## Configuration ### Tailwind Config ```js // Import Tailwind config import config from '@vercel/geistcn/config/tailwindcss' // With plugins import plugins from '@vercel/geistcn/config/tailwindcss-plugins' ``` ### PostCSS Config ```js // Base PostCSS config import postcssConfig from '@vercel/geistcn/config/postcss' // With Tailwind import postcssWithTailwind from '@vercel/geistcn/config/postcss/with-tailwindcss' ``` ## Types & Utils ```tsx // Import types import type { ButtonProps, InputProps } from '@vercel/geistcn/types' // Import utilities import { cn, useType } from '@vercel/geistcn/utils' ``` ### Available Utilities - `cn` - Class name merger (clsx + tailwind-merge) - `useType` - Type utility hook - `toEm` / `toPixels` - Unit conversion - `useMediaQuery` - Media query hook - `useId` - Unique ID hook - `useIsomorphicLayoutEffect` - SSR-safe layout effect - `usePrefersReducedMotion` - Reduced motion preference - `useDelayedRender` - Delayed render hook - `useAwaitPaintSelectState` - Paint state hook - `forwardRef` - Enhanced forward ref - `withIcon` / `withLogo` / `withPixelIcon` - HOCs for icons - `withBlurBase64` - Blur placeholder HOC - `withType` - Type HOC - `responsiveProp` - Responsive prop utility - `canPrefetch` - Prefetch utility - `browsers` - Browser detection - `color` - Color utilities - `dateTime` - Date/time utilities - `sizing` - Sizing utilities - `cleanUrl` - URL cleaning utility ## Legacy ```tsx // Legacy components (deprecated, scheduled for removal) import { LegacyComponent } from '@vercel/geistcn/components/legacy' ``` **Note:** Legacy components use the `_legacy` suffix and are deprecated. Avoid using them in new code. ## Notes - All component imports support modularized imports via Next.js config - Use `GeistProvider` wrapper for proper context and theming - Styles must be imported in your root layout - Icons and logos are tree-shakeable when imported individually - Components use Radix UI primitives where applicable for accessibility - TypeScript definitions are included for all components - The package is designed for use with Next.js 15+ and React 19 ## Package Information - **Package:** `@vercel/geistcn` - **Type:** ES Module - **Side Effects:** false (tree-shakeable) - **Peer Dependencies:** React 19.2.0, Next.js >= 15.4.2-canary.47 [V0_FILE]markdown:file="docs/common-mistakes.md" # Common Mistakes & Anti-Patterns Guide to avoiding common mistakes when using Geist Design System. ## ❌ Wrong Import Paths ### Don't use shadcn/ui or other UI library paths ```tsx // ❌ WRONG import { Button } from '@/components/ui/button' import { Badge } from '@/components/ui/badge' import { Avatar } from '@/components/ui/avatar' // ✅ CORRECT import { Button } from '@vercel/geistcn/components/button' import { Badge } from '@vercel/geistcn/components/badge' import { Avatar } from '@vercel/geistcn/components/avatar' ``` **Why it's wrong:** Geist is not shadcn/ui or any other component library. Always import directly from `@vercel/geistcn`. ## ❌ Wrong Icon Library ### Don't use lucide-react, heroicons, or other icon libraries ```tsx // ❌ WRONG import { SearchIcon, ChevronDownIcon, MessageCircleIcon } from 'lucide-react' import { XMarkIcon } from '@heroicons/react/24/outline' // ✅ CORRECT import { Search, ChevronDown, MessageCircle, X } from '@vercel/geistcn/icons' ``` **Why it's wrong:** Geist has 550+ built-in icons specifically designed for the design system. Using external icons breaks visual consistency. **See:** [Icons Reference](./icons-reference.md) for all available icons. ## ✅ Using Tailwind with Geist Design Tokens ### Geist's Tailwind Config Maps Design Tokens When using Geist with Tailwind, the color classes are **already mapped** to design tokens automatically! ```tsx // ✅ CORRECT - Geist's Tailwind classes (mapped to design tokens)

// ✅ ALSO CORRECT - Direct CSS custom properties

// ✅ BEST - Use Geist components when possible {/* Already has correct styling */} // ✅ CORRECT ``` **Available Button types:** `primary`, `secondary`, `success`, `warning`, `error`, `abort` ### Badge: Use `type` not `variant` ```tsx // ❌ WRONG Status Status // ✅ CORRECT Status Active Failed Pending ``` **Available Badge types:** `default`, `success`, `error`, `warning` ### Input: No `variant` prop ```tsx // ❌ WRONG // ✅ CORRECT ``` ## ❌ Inline SVG Instead of Icons ### Don't manually write SVG, use Geist icons ```tsx // ❌ WRONG ; // ✅ CORRECT import { External } from '@vercel/geistcn/icons' ; ``` **Why it's wrong:** Geist icons are optimized, consistent, and tree-shakeable. Manual SVG adds unnecessary code. ## ❌ Wrong Spacing Approach ### Don't use arbitrary px values ```tsx // ❌ WRONG

// ✅ CORRECT - Use design tokens

// ✅ ALSO CORRECT - Use Geist components Content ``` ## ❌ Missing GeistProvider ### Always wrap your app with GeistProvider ```tsx // ❌ WRONG - Missing provider export default function RootLayout({ children }) { return ( {children} ) } // ✅ CORRECT import { GeistProvider } from '@vercel/geistcn/core/provider' import '@vercel/geistcn/styles.css' export default function RootLayout({ children }) { return ( {children} ) } ``` ## ❌ Missing Styles Import ### Always import Geist styles ```tsx // ❌ WRONG - No styles imported import { Button } from '@vercel/geistcn/components/button' export default function Page() { return // Will have no styling! } // ✅ CORRECT - Import in root layout // app/layout.tsx import '@vercel/geistcn/styles.css' import { GeistProvider } from '@vercel/geistcn/core/provider' export default function RootLayout({ children }) { return ( {children} ) } ``` ## ❌ Not Using Component Variants ### Use built-in component types instead of custom styling ```tsx // ❌ WRONG - Custom styling for standard variants // ✅ CORRECT - Use type prop // ❌ WRONG

Success

// ✅ CORRECT Success ``` ## ❌ Using className for Colors ### Prefer design tokens over Tailwind classes for colors ```tsx // ❌ SUBOPTIMAL - Tailwind classes

// ✅ BETTER - Design tokens

// ✅ BEST - Component variants or CSS custom properties

``` ## ❌ Not Using 'use client' Directive ### Add 'use client' when using hooks or interactivity ```tsx // ❌ WRONG - Missing directive import { useState } from 'react' import { useToasts } from '@vercel/geistcn/components/toast' export function MyComponent() { const [count, setCount] = useState(0) // Error! const toasts = useToasts() // Error! // ... } // ✅ CORRECT ;('use client') import { useState } from 'react' import { useToasts } from '@vercel/geistcn/components/toast' export function MyComponent() { const [count, setCount] = useState(0) // Works! const toasts = useToasts() // Works! // ... } ``` ## ✅ Correct Pattern Example Here's how the Support Center code should be written: ```tsx 'use client' import { useState } from 'react' import { Button } from '@vercel/geistcn/components/button' import { Input } from '@vercel/geistcn/components/input' import { Badge } from '@vercel/geistcn/components/badge' import { Avatar } from '@vercel/geistcn/components/avatar' import { Tabs } from '@vercel/geistcn/components/tabs' import { Card } from '@vercel/geistcn/components/card' import { Text } from '@vercel/geistcn/components/text' import { Search, MessageCircle, MessageSquare, ChevronDown, External, } from '@vercel/geistcn/icons' export function SupportCenter() { const [searchQuery, setSearchQuery] = useState('') const [activeTab, setActiveTab] = useState('all') return (

{/* Header */}

Support Center

Create and view support cases for your projects.{' '} Learn more

{/* Main Content */}

{/* Search and Filters */}

setSearchQuery(e.target.value)} className="pl-10" />

All Open Transferred Closed

{/* Tickets List */}

{mockTickets.map((ticket) => (

{ticket.status} Severity {ticket.severity} {ticket.title} {ticket.comments > 0 && (

{ticket.comments}

)}

{ticket.id} {ticket.assignee} {ticket.date}

))}

) } ``` **Key points:** - Uses Tailwind classes: `bg-background-100`, `text-gray-700`, `border-gray-alpha-200` - These are automatically mapped to design tokens by Geist's Tailwind config - Works with dark mode automatically - Cleaner than inline styles for most cases ## Quick Checklist Before using Geist, verify: - [ ] ✅ Importing from `@vercel/geistcn/*` (not shadcn/ui) - [ ] ✅ Using Geist icons from `@vercel/geistcn/icons` (not lucide-react) - [ ] ✅ Using design tokens `var(--ds-*)` (not hardcoded colors) - [ ] ✅ Using component `type` prop (not `variant`) - [ ] ✅ Imported `@vercel/geistcn/styles.css` in root layout - [ ] ✅ Wrapped app with `` - [ ] ✅ Added `'use client'` when using hooks - [ ] ✅ Using Geist components instead of custom divs ## See Also - [Getting Started](./getting-started.md) - Setup guide - [Icons Reference](./icons-reference.md) - All 550+ icons - [Tailwind Integration](./tailwind-integration.md) - **How to use Tailwind classes correctly** - [Styling Guide](./styling-guide.md) - Design tokens and colors - [Common Patterns](./common-patterns.md) - Correct usage examples [V0_FILE]markdown:file="docs/common-patterns.md" # Common Patterns and Recipes Real-world examples and patterns for using Geist components effectively. ## Form Patterns ### Basic Form with Validation ```tsx 'use client' import { Button } from '@vercel/geistcn/components/button' import { Input } from '@vercel/geistcn/components/input' import { Fieldset, FieldsetContent, FieldsetFooter, } from '@vercel/geistcn/components/fieldset' import { useToasts } from '@vercel/geistcn/components/toast' import { useState } from 'react' export default function ContactForm() { const { success, error } = useToasts() const [loading, setLoading] = useState(false) async function handleSubmit(e: React.FormEvent) { e.preventDefault() setLoading(true) try { const formData = new FormData(e.currentTarget) await fetch('/api/contact', { method: 'POST', body: JSON.stringify(Object.fromEntries(formData)), }) success('Message sent successfully!') } catch (err) { error('Failed to send message') } finally { setLoading(false) } } return (

</FieldsetContent>
        <FieldsetFooter>
          <Button type="submit" loading={loading}>
            Send Message
          </Button>
        </FieldsetFooter>
      </Fieldset>
    </form>
  )
}
```

### Form with Field Groups

```tsx
import {
  Fieldset,
  FieldsetTitle,
  FieldsetContent,
} from '@vercel/geistcn/components/fieldset'
import { Input } from '@vercel/geistcn/components/input'
import { Select } from '@vercel/geistcn/components/select'
import { Checkbox } from '@vercel/geistcn/components/checkbox'

export function SettingsForm() {
  return (
    <div>
      <Fieldset>
        <FieldsetTitle>Personal Information</FieldsetTitle>
        <FieldsetContent>
          <Input label="First Name" />
          <Input label="Last Name" />
          <Input type="email" label="Email" />
        </FieldsetContent>
      </Fieldset>

<Fieldset>
        <FieldsetTitle>Preferences</FieldsetTitle>
        <FieldsetContent>
          <Select label="Language">
            <option value="en">English</option>
            <option value="es">Spanish</option>
          </Select>
          <Checkbox>Enable notifications</Checkbox>
        </FieldsetContent>
      </Fieldset>
    </div>
  )
}
```

## Modal Patterns

### Confirmation Dialog

```tsx
'use client'

import { Modal } from '@vercel/geistcn/components/modal'
import { Button } from '@vercel/geistcn/components/button'
import { useState } from 'react'

export function DeleteButton() {
  const [isOpen, setIsOpen] = useState(false)

async function handleDelete() {
    await fetch('/api/delete', { method: 'DELETE' })
    setIsOpen(false)
  }

return (
    <>
      <Button onClick={() => setIsOpen(true)} type="error">
        Delete
      </Button>

<Modal open={isOpen} onOpenChange={setIsOpen}>
        <Modal.Title>Confirm Deletion</Modal.Title>
        <Modal.Body>
          <Modal.P>
            Are you sure you want to delete this item? This action cannot be
            undone.
          </Modal.P>
        </Modal.Body>
        <Modal.Actions>
          <Modal.Action passive onClick={() => setIsOpen(false)}>
            Cancel
          </Modal.Action>
          <Modal.Action onClick={handleDelete}>Delete</Modal.Action>
        </Modal.Actions>
      </Modal>
    </>
  )
}
```

### Form Modal

```tsx
'use client'

import { Modal } from '@vercel/geistcn/components/modal'
import { Input } from '@vercel/geistcn/components/input'
import { Textarea } from '@vercel/geistcn/components/textarea'

export function CreateModal({ open, onOpenChange }) {
  function handleSubmit(e: React.FormEvent) {
    e.preventDefault()
    // Handle form submission
    onOpenChange(false)
  }

return (
    <Modal open={open} onOpenChange={onOpenChange}>
      <Modal.Title>Create New Item</Modal.Title>
      <form onSubmit={handleSubmit}>
        <Modal.Body>
          <Input label="Name" required />
          <Textarea label="Description" />
        </Modal.Body>
        <Modal.ButtonActions>
          <Modal.Action
            type="button"
            passive
            onClick={() => onOpenChange(false)}
          >
            Cancel
          </Modal.Action>
          <Modal.Action type="submit">Create</Modal.Action>
        </Modal.ButtonActions>
      </form>
    </Modal>
  )
}
```

## Toast Notifications

### Success/Error Feedback

```tsx
'use client'

import { Button } from '@vercel/geistcn/components/button'
import { useToasts } from '@vercel/geistcn/components/toast'

export function SaveButton() {
  const toasts = useToasts()

async function handleSave() {
    try {
      await fetch('/api/save', { method: 'POST' })
      toasts.success('Saved successfully!')
    } catch (error) {
      toasts.error('Failed to save changes')
    }
  }

return <Button onClick={handleSave}>Save</Button>
}
```

### Custom Toast with Actions

```tsx
import { useToasts } from '@vercel/geistcn/components/toast'
import { Button } from '@vercel/geistcn/components/button'

export function UndoableAction() {
  const toasts = useToasts()

function handleDelete(id: string) {
    // Perform delete
    deleteItem(id)

// Show toast with undo
    toasts.message({
      text: 'Item deleted',
      actions: [
        {
          label: 'Undo',
          onClick: () => restoreItem(id),
        },
      ],
    })
  }

return <Button onClick={() => handleDelete('123')}>Delete</Button>
}
```

## Navigation Patterns

### Breadcrumb Navigation

```tsx
import { Breadcrumbs } from '@vercel/geistcn/components/breadcrumbs'
import { Link } from '@vercel/geistcn/components/link'

export function PageBreadcrumbs({ segments }) {
  return (
    <Breadcrumbs>
      <Link href="/">Home</Link>
      {segments.map((segment, i) => (
        <Link key={i} href={segment.href}>
          {segment.label}
        </Link>
      ))}
    </Breadcrumbs>
  )
}
```

### Tabs Navigation

```tsx
'use client'

import { Tabs } from '@vercel/geistcn/components/tabs'
import { usePathname, useRouter } from 'next/navigation'

export function NavigationTabs() {
  const pathname = usePathname()
  const router = useRouter()

const tabs = [
    { label: 'Overview', value: '/dashboard' },
    { label: 'Analytics', value: '/dashboard/analytics' },
    { label: 'Settings', value: '/dashboard/settings' },
  ]

return (
    <Tabs value={pathname} onChange={(value) => router.push(value)}>
      {tabs.map((tab) => (
        <Tabs.Item key={tab.value} value={tab.value}>
          {tab.label}
        </Tabs.Item>
      ))}
    </Tabs>
  )
}
```

### Sidebar Navigation

```tsx
import {
  Sidebar,
  SidebarSection,
  SidebarLink,
} from '@vercel/geistcn/components/sidebar'
import { Home, Settings, Users } from '@vercel/geistcn/icons'

export function AppSidebar() {
  return (
    <Sidebar>
      <SidebarSection>
        <SidebarLink href="/dashboard" icon={<Home />}>
          Dashboard
        </SidebarLink>
        <SidebarLink href="/users" icon={<Users />}>
          Users
        </SidebarLink>
        <SidebarLink href="/settings" icon={<Settings />}>
          Settings
        </SidebarLink>
      </SidebarSection>
    </Sidebar>
  )
}
```

## Menu Patterns

### Dropdown Menu

```tsx
'use client'

import { Menu, MenuItem, MenuDivider } from '@vercel/geistcn/components/menu'
import { DotsMenu } from '@vercel/geistcn/components/dots-menu'
import { Edit, Trash, Copy } from '@vercel/geistcn/icons'

export function ActionsMenu() {
  return (
    <Menu trigger={<DotsMenu />}>
      <MenuItem onClick={() => console.log('Edit')}>
        <Edit size={16} />
        Edit
      </MenuItem>
      <MenuItem onClick={() => console.log('Duplicate')}>
        <Copy size={16} />
        Duplicate
      </MenuItem>
      <MenuDivider />
      <MenuItem onClick={() => console.log('Delete')} type="error">
        <Trash size={16} />
        Delete
      </MenuItem>
    </Menu>
  )
}
```

### Context Menu

```tsx
import { ContextMenu } from '@vercel/geistcn/components/context-menu'

export function FileItem({ file }) {
  return (
    <ContextMenu
      items={[
        { label: 'Open', onClick: () => open(file) },
        { label: 'Rename', onClick: () => rename(file) },
        { type: 'divider' },
        { label: 'Delete', onClick: () => delete file, type: 'error' },
      ]}
    >
      <div className="file-item">{file.name}</div>
    </ContextMenu>
  )
}
```

## Table Patterns

### Data Table with Actions

```tsx
import {
  Table,
  TableRoot,
  TableHeader,
  TableHead,
  TableBody,
  TableRow,
  TableCell,
} from '@vercel/geistcn/components/table'
import { Badge } from '@vercel/geistcn/components/badge'
import { Button } from '@vercel/geistcn/components/button'

export function UsersTable({ users }) {
  return (
    <TableRoot>
      <Table>
        <TableHeader>
          <TableRow>
            <TableHead>Name</TableHead>
            <TableHead>Email</TableHead>
            <TableHead>Status</TableHead>
            <TableHead>Actions</TableHead>
          </TableRow>
        </TableHeader>
        <TableBody>
          {users.map((user) => (
            <TableRow key={user.id}>
              <TableCell>{user.name}</TableCell>
              <TableCell>{user.email}</TableCell>
              <TableCell>
                <Badge type={user.active ? 'success' : 'default'}>
                  {user.active ? 'Active' : 'Inactive'}
                </Badge>
              </TableCell>
              <TableCell>
                <Button size="small">Edit</Button>
              </TableCell>
            </TableRow>
          ))}
        </TableBody>
      </Table>
    </TableRoot>
  )
}
```

## Loading States

### Skeleton Loading

```tsx
import { Skeleton } from '@vercel/geistcn/components/skeleton'
import { Card } from '@vercel/geistcn/components/card'

export function LoadingCard() {
  return (
    <Card>
      <Skeleton width="60%" height={24} />
      <Skeleton width="100%" height={16} />
      <Skeleton width="100%" height={16} />
      <Skeleton width="80%" height={16} />
    </Card>
  )
}
```

### Loading Button

```tsx
'use client'

import { Button } from '@vercel/geistcn/components/button'
import { useState } from 'react'

export function SubmitButton() {
  const [loading, setLoading] = useState(false)

async function handleClick() {
    setLoading(true)
    await performAction()
    setLoading(false)
  }

return (
    <Button onClick={handleClick} loading={loading}>
      Submit
    </Button>
  )
}
```

### Spinner Overlay

```tsx
import { Spinner } from '@vercel/geistcn/components/spinner'

export function LoadingOverlay({ isLoading, children }) {
  return (
    <div style={{ position: 'relative' }}>
      {children}
      {isLoading && (
        <div
          style={{
            position: 'absolute',
            inset: 0,
            display: 'flex',
            alignItems: 'center',
            justifyContent: 'center',
            background: 'rgba(255, 255, 255, 0.8)',
          }}
        >
          <Spinner />
        </div>
      )}
    </div>
  )
}
```

## Command Menu Pattern

```tsx
'use client'

import {
  CommandMenu,
  useCommandMenu,
} from '@vercel/geistcn/components/command-menu'
import { useEffect } from 'react'

export function GlobalCommandMenu() {
  const { isOpen, setIsOpen } = useCommandMenu()

useEffect(() => {
    function handleKeyDown(e: KeyboardEvent) {
      if ((e.metaKey || e.ctrlKey) && e.key === 'k') {
        e.preventDefault()
        setIsOpen(true)
      }
    }

window.addEventListener('keydown', handleKeyDown)
    return () => window.removeEventListener('keydown', handleKeyDown)
  }, [setIsOpen])

return (
    <CommandMenu
      open={isOpen}
      onOpenChange={setIsOpen}
      items={[
        { label: 'Home', value: 'home', onSelect: () => navigate('/') },
        {
          label: 'Settings',
          value: 'settings',
          onSelect: () => navigate('/settings'),
        },
      ]}
    />
  )
}
```

## Empty States

```tsx
import { EmptyState } from '@vercel/geistcn/components/empty-state'
import { Button } from '@vercel/geistcn/components/button'
import { Plus } from '@vercel/geistcn/icons'

export function NoResults() {
  return (
    <EmptyState
      title="No items found"
      description="Get started by creating your first item"
      action={<Button prefix={<Plus />}>Create Item</Button>}
    />
  )
}
```

## Responsive Patterns

### Mobile-Responsive Layout

```tsx
import { Container } from '@vercel/geistcn/components/container'
import { Stack } from '@vercel/geistcn/components/stack'
import { Grid } from '@vercel/geistcn/components/grid'

export function ResponsiveLayout({ children }) {
  return (
    <Container>
      <Stack gap={4}>
        <Grid columns={{ xs: 1, md: 2, lg: 3 }} gap={4}>
          {children}
        </Grid>
      </Stack>
    </Container>
  )
}
```

### Responsive Navigation

```tsx
import { Drawer } from '@vercel/geistcn/components/drawer'
import { Button } from '@vercel/geistcn/components/button'
import { Menu } from '@vercel/geistcn/icons'
import { useMediaQuery } from '@vercel/geistcn/utils/use-media-query'

export function Navigation() {
  const isMobile = useMediaQuery('(max-width: 768px)')

if (isMobile) {
    return (
      <Drawer trigger={<Button icon={<Menu />} />}>
        <NavigationItems />
      </Drawer>
    )
  }

return <NavigationItems />
}
```

## Accessibility Patterns

### Skip Navigation

```tsx
import {
  SkipNavLink,
  SkipNavContent,
} from '@vercel/geistcn/components/skip-nav'

export function Layout({ children }) {
  return (
    <>
      <SkipNavLink />
      <header>...</header>
      <main>
        <SkipNavContent />
        {children}
      </main>
    </>
  )
}
```

### Keyboard Navigation

```tsx
import { Kbd } from '@vercel/geistcn/components/kbd'
import { Text } from '@vercel/geistcn/components/text'

export function ShortcutHint() {
  return (
    <Text>
      Press <Kbd>⌘</Kbd> <Kbd>K</Kbd> to open command menu
    </Text>
  )
}
```

These patterns demonstrate common use cases and best practices for building applications with Geist.
[V0_FILE]markdown:file="docs/component-categories.md"
# Component Categories

Quick reference guide organizing GeistCN components by their purpose and use case.

> **Note:** GeistCN has a subset of components compared to @vercel/geist. Some components like `Container`, `Spacer`, `Progress`, `Gauge`, `SuspenseImage`, and `Scroller` are not available in GeistCN.

## When to Use Which Component

### Input & Forms

**Use for:** Collecting user input and data entry

| Component              | Best For                      | Key Features                          |
| ---------------------- | ----------------------------- | ------------------------------------- |
| `Input`                | Single-line text input        | Standard text, email, password fields |
| `Textarea`             | Multi-line text input         | Long form content, descriptions       |
| `Select`               | Single choice from list       | Dropdown menus, option selection      |
| `Checkbox`             | Multiple selections           | Toggle options, agreements            |
| `Radio` / `RadioGroup` | Single choice from group      | Mutually exclusive options            |
| `Toggle` / `Switch`    | Binary on/off state           | Feature toggles, settings             |
| `Combobox`             | Searchable select             | Large option lists with search        |
| `MultiSelect`          | Multiple selections from list | Tags, categories, filters             |
| `ClearableInput`       | Input with clear button       | Search fields, filters                |
| `SearchInput`          | Search-specific input         | Search bars, filters                  |
| `Slider`               | Numeric range input           | Volume, brightness, ranges            |
| `Calendar`             | Date selection                | Date pickers, scheduling              |

### Buttons & Actions

**Use for:** Triggering actions and navigation

| Component        | Best For                          | Key Features                     |
| ---------------- | --------------------------------- | -------------------------------- |
| `Button`         | Primary actions                   | Click handlers, form submission  |
| `ButtonLink`     | Navigation that looks like button | Internal/external links          |
| `CustomButton`   | Specialized button styling        | Custom branded buttons           |
| `SplitButton`    | Primary action + menu             | Default action with alternatives |
| `LoadMoreButton` | Pagination                        | Loading more content             |
| `CopyButton`     | Copy to clipboard                 | Copying text, code, URLs         |

### Layout & Structure

**Use for:** Page structure and content organization

| Component   | Best For                    | Key Features                     |
| ----------- | --------------------------- | -------------------------------- |
| `Stack`     | Vertical/horizontal spacing | Consistent gaps between elements |
| `Grid`      | Multi-column layouts        | Responsive grids                 |
| `Separator` | Visual separation           | Horizontal/vertical dividers     |
| `Card`      | Grouped content             | Bordered, elevated containers    |
| `Fieldset`  | Form sections               | Form grouping, titles, footers   |

> **Note:** Use Tailwind classes like `max-w-7xl mx-auto` for container/page-level width constraints.

### Navigation

**Use for:** Moving between pages and sections

| Component                        | Best For                | Key Features                  |
| -------------------------------- | ----------------------- | ----------------------------- |
| `Link`                           | Text links              | Internal/external navigation  |
| `Breadcrumbs`                    | Hierarchical navigation | Path to current page          |
| `Tabs`                           | Section switching       | Content switching within page |
| `Menu`                           | Dropdown menus          | Action lists, navigation      |
| `Sidebar`                        | Persistent navigation   | App-level navigation          |
| `SidebarLink` / `SidebarSection` | Sidebar items           | Organized navigation items    |
| `Pagination`                     | Multi-page navigation   | Page number navigation        |
| `SkipNavLink` / `SkipNavContent` | Accessibility           | Skip to main content          |

### Overlays & Dialogs

**Use for:** Focused interactions and temporary content

| Component     | Best For                 | Key Features                |
| ------------- | ------------------------ | --------------------------- |
| `Modal`       | Important user decisions | Blocking dialogs, forms     |
| `Dialog`      | Simple dialogs           | Radix-based dialogs         |
| `Drawer`      | Side panel content       | Mobile menus, forms         |
| `Sheet`       | Bottom sheet             | Mobile-optimized overlays   |
| `Tooltip`     | Contextual help          | Hover information           |
| `Popover`     | Non-blocking overlays    | Additional info, mini forms |
| `ContextMenu` | Right-click menus        | Contextual actions          |
| `CommandMenu` | Command palette          | Quick actions, search       |

### Display & Content

**Use for:** Presenting information to users

| Component             | Best For                 | Key Features               |
| --------------------- | ------------------------ | -------------------------- |
| `Text`                | Formatted text           | Typography, sizing, colors |
| `Description`         | Descriptive text         | Subtitles, captions        |
| `Badge`               | Status indicators        | Labels, counts, statuses   |
| `StatusDot`           | Status indicators        | Online/offline, health     |
| `Note`                | Important messages       | Info, warning, error boxes |
| `Banner`              | Page-level announcements | Alerts, notifications      |
| `Code` / `InlineCode` | Inline code display      | Code snippets in text      |
| `CodeBlock`           | Multi-line code          | Syntax-highlighted code    |
| `Snippet`             | Copyable code            | Code examples with copy    |
| `Kbd`                 | Keyboard shortcuts       | Key combinations           |
| `Table`               | Tabular data             | Data tables, lists         |

### Feedback & Status

**Use for:** Showing system state and user feedback

| Component          | Best For                | Key Features                  |
| ------------------ | ----------------------- | ----------------------------- |
| `Toasts`           | Temporary notifications | Success, error, info messages |
| `Spinner`          | Indeterminate loading   | Loading indicators            |
| `LoadingDots`      | Subtle loading          | Animated dots                 |
| `Skeleton`         | Content placeholders    | Loading skeletons             |
| `EmptyState`       | No content states       | Empty lists, no results       |
| `Error`            | Error display           | Error messages                |
| `ErrorCard`        | Detailed errors         | Error cards with details      |
| `Feedback`         | User feedback widget    | Feedback collection           |
| `DeploymentStatus` | Deployment indicators   | Build/deploy status           |

> **Note:** `Progress` and `Gauge` are not available in GeistCN. Use Tailwind with custom CSS for progress bars.

### Media & Assets

**Use for:** Displaying images, videos, and graphics

| Component     | Best For         | Key Features                  |
| ------------- | ---------------- | ----------------------------- |
| `Image`       | Images           | Next.js Image wrapper         |
| `Video`       | Video content    | Video players                 |
| `Avatar`      | User avatars     | Profile pictures              |
| `AvatarGroup` | Multiple avatars | User groups                   |
| `Browser`     | Browser mockups  | Screenshot frames             |
| `PixelIcon`   | Pixel art icons  | Retro-style icons             |
| `FileTree`    | File structure   | Tree, Folder, File components |

### Interactive

**Use for:** Advanced interactions and animations

| Component       | Best For             | Key Features           |
| --------------- | -------------------- | ---------------------- |
| `Collapse`      | Expandable sections  | Accordion items        |
| `CollapseGroup` | Multiple collapsible | Accordions             |
| `ShowMore`      | Truncated content    | Expandable text        |
| `ClickOutside`  | Click detection      | Close on outside click |

### Icons & Branding

**Use for:** Visual elements and brand assets

| Component    | Best For         | Key Features                  |
| ------------ | ---------------- | ----------------------------- |
| Icons (550+) | UI icons         | Arrows, actions, status, etc. |
| `VercelLogo` | Vercel branding  | Logo marks and wordmarks      |
| `NextjsLogo` | Next.js branding | Logo marks and wordmarks      |
| `TurboLogo`  | Turbo branding   | Logo marks and wordmarks      |

### Forms & Validation

**Use for:** Complex form structures

| Component         | Best For          | Key Features                  |
| ----------------- | ----------------- | ----------------------------- |
| `Fieldset`        | Form sections     | Grouping, titles              |
| `FieldsetTitle`   | Section titles    | Form section headers          |
| `FieldsetContent` | Form content area | Field grouping                |
| `FieldsetFooter`  | Form actions      | Submit buttons                |
| `ErrorText`       | Field errors      | Validation messages           |
| `WarningText`     | Field warnings    | Warning messages              |
| `DisabledWall`    | Disabled states   | Overlay for disabled sections |
| `Label`           | Input labels      | Accessible labels             |

### Specialized

**Use for:** Specific use cases

| Component            | Best For             | Key Features             |
| -------------------- | -------------------- | ------------------------ |
| `Entity`             | Complex entities     | Projects, resources      |
| `ContextCard`        | Rich context         | Detailed info cards      |
| `RelativeTimeCard`   | Time display         | Relative timestamps      |
| `Material`           | Material design      | Material-styled elements |
| `Book`               | Documentation        | Book-style layouts       |
| `ProjectBanner`      | Project headers      | Project banners          |
| `ChoiceboxGroup`     | Custom choice groups | Specialized selections   |
| `DotsMenu`           | Three-dot menus      | Common menu trigger      |
| `TextWithCopyButton` | Copyable text        | Text with copy action    |

### Theme & Configuration

**Use for:** Theming and appearance

| Component       | Best For      | Key Features           |
| --------------- | ------------- | ---------------------- |
| `GeistProvider` | Theme context | Required wrapper       |
| `ThemeSwitcher` | Theme toggle  | Dark/light mode switch |

### Utilities

**Use for:** Helper components and utilities

| Component         | Best For              | Key Features        |
| ----------------- | --------------------- | ------------------- |
| `Show`            | Conditional rendering | Show/hide logic     |
| `Keyboard`        | Keyboard handling     | Key event handling  |
| `ScrollToSidebar` | Scroll behavior       | Scroll-to utilities |
| `FragmentLink`    | Fragment navigation   | Anchor links        |
| `ContentWrapper`  | Content wrapping      | Generic wrappers    |

## Component Selection Guide

### Need a form?

→ Start with `Fieldset`, add `Input`/`Textarea`/`Select`, use `Button` for submission

### Need to show data?

→ Use `Table` for structured data, `Card` for items, `Badge` for status

### Need navigation?

→ Use `Link` for text, `Tabs` for sections, `Menu` for actions, `Sidebar` for apps

### Need feedback?

→ Use `Toasts` for notifications, `Modal` for confirmations, `Spinner` for loading

### Need to show state?

→ Use `Skeleton` while loading, `EmptyState` for no data, `Error` for failures

### Need interactive content?

→ Use `Collapse` for expandables, `Tooltip` for hints, `ContextMenu` for actions

### Need layout?

→ Use Tailwind's `max-w-*` for pages, `Stack` for spacing, `Grid` for columns

## Compound Components

Some components use the compound component pattern:

```tsx
// Modal
<Modal>
  <Modal.Title />
  <Modal.Body />
  <Modal.Actions />
</Modal>

// Table
<Table>
  <TableHeader>
    <TableRow>
      <TableHead />
    </TableRow>
  </TableHeader>
  <TableBody>
    <TableRow>
      <TableCell />
    </TableRow>
  </TableBody>
</Table>

// Browser
<Browser>
  <Browser.Header />
  {/* content */}
</Browser>
```

## Hook-Based Components

Components that provide hooks for programmatic control:

- `useToasts()` - Control toasts programmatically
- `useMenu()` - Menu state management
- `useCollapse()` - Collapse state management
- `useCommandMenu()` - Command menu control
- `useRadio()` - Radio group control
- `useMediaQuery()` - Responsive utilities
- `useDisabledContext()` - Disabled state context

## Related Components

Components that work well together:

| Primary   | Works Well With                 |
| --------- | ------------------------------- |
| `Input`   | `Label`, `ErrorText`, `Button`  |
| `Modal`   | `Button`, `Input`, `Fieldset`   |
| `Table`   | `Badge`, `Button`, `Menu`       |
| `Card`    | `Text`, `Badge`, `Button`       |
| `Menu`    | `MenuItem`, `MenuDivider`       |
| `Sidebar` | `SidebarLink`, `SidebarSection` |
| `Avatar`  | `AvatarGroup`, `Badge`          |

This categorization helps you quickly find the right component for your use case.
[V0_FILE]markdown:file="docs/getting-started.md"
# Getting Started with @vercel/geistcn

Complete guide to installing and setting up the GeistCN Design System in your project.

> **Note:** GeistCN is Vercel's next-generation design system using Tailwind CSS v4 with OKLCH colors for wide gamut display support.

## Installation

```bash
# Using pnpm (recommended)
pnpm add @vercel/geistcn

# Using npm
npm install @vercel/geistcn

# Using yarn
yarn add @vercel/geistcn
```

## Peer Dependencies

Geist requires the following peer dependencies:

```json
{
  "react": "19.2.0",
  "next": ">= 15.4.2-canary.47"
}
```

Make sure these are installed in your project.

## Basic Setup

### 1. Import Styles

Add the Geist styles to your root layout file:

```tsx
// app/layout.tsx
import '@vercel/geistcn/styles.css'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  )
}
```

### 2. Add GeistProvider (Recommended)

Wrap your application with the `GeistProvider` for proper context and theming:

```tsx
// app/layout.tsx
import '@vercel/geistcn/styles.css'
import { GeistProvider } from '@vercel/geistcn/core/provider'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        <GeistProvider>{children}</GeistProvider>
      </body>
    </html>
  )
}
```

### 3. Configure Next.js (Optional but Recommended)

For optimal bundle size with modularized imports, configure Next.js:

```js
// next.config.js
const nextConfig = {
  transpilePackages: ['@vercel/geistcn'],
  experimental: {
    optimizePackageImports: ['@vercel/geistcn'],
  },
}

module.exports = nextConfig
```

## Using Components

### Basic Component Import

```tsx
import { Button } from '@vercel/geistcn/components'

export default function Page() {
  return <Button>Click me</Button>
}
```

### Modularized Imports

For better tree-shaking, import from specific component paths:

```tsx
import { Button } from '@vercel/geistcn/components/button'
import { Input } from '@vercel/geistcn/components/input'
import { Card } from '@vercel/geistcn/components/card'
```

### Using Icons

```tsx
import { ArrowRight, Check, X } from '@vercel/geistcn/icons'

export default function Page() {
  return (
    <div>
      <ArrowRight size={24} />
      <Check color="green" />
      <X color="red" />
    </div>
  )
}
```

### Using Logos

```tsx
import { VercelLogo, NextjsLogo } from '@vercel/geistcn/logos'

export default function Page() {
  return (
    <div>
      <VercelLogo height={32} />
      <NextjsLogo height={32} />
    </div>
  )
}
```

## Tailwind CSS v4 Integration

GeistCN uses Tailwind CSS v4 with CSS-first configuration. Import the pre-configured theme:

```tsx
// app/layout.tsx
import '@vercel/geistcn/tailwind.css'
import '@vercel/geistcn/styles.css'
import { GeistProvider } from '@vercel/geistcn/core/provider'

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <GeistProvider>{children}</GeistProvider>
      </body>
    </html>
  )
}
```

The `tailwind.css` file includes:

- Full Tailwind v4 theme configuration
- OKLCH color tokens for wide gamut displays
- Custom breakpoints, shadows, and spacing
- `dark-theme:` and `light-theme:` custom variants

## PostCSS Integration

```js
// postcss.config.mjs
export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
}
```

Or use GeistCN's preconfigured PostCSS:

```js
// postcss.config.mjs
export default require('@vercel/geistcn/config/postcss')
```

## TypeScript Support

Geist includes full TypeScript definitions. No additional setup required.

```tsx
import type { ButtonProps } from '@vercel/geistcn/types'

const MyButton: React.FC<ButtonProps> = (props) => {
  return <Button {...props} />
}
```

## Toast Notifications Setup

For toast notifications, wrap your app with `withToasts` or add the `Toasts` component:

```tsx
// Using withToasts HOC
import { withToasts } from '@vercel/geistcn/components/toast'

function MyApp() {
  return <div>My App</div>
}

export default withToasts(MyApp)

// Or manually add Toasts component
import { Toasts } from '@vercel/geistcn/components/toast'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Toasts />
      </body>
    </html>
  )
}
```

## Font Setup (Optional)

Geist includes Geist Sans and Geist Mono fonts. Import them if needed:

```tsx
import { GeistSans } from '@vercel/geistcn/fonts'
import { GeistMono } from '@vercel/geistcn/fonts'

export default function RootLayout({ children }) {
  return (
    <html lang="en" className={`${GeistSans.variable} ${GeistMono.variable}`}>
      <body>{children}</body>
    </html>
  )
}
```

## Verification

Test your setup with a simple page:

```tsx
// app/page.tsx
import { Button } from '@vercel/geistcn/components/button'
import { Card } from '@vercel/geistcn/components/card'
import { ArrowRight } from '@vercel/geistcn/icons'

export default function Home() {
  return (
    <Card>
      <h1>Welcome to Geist</h1>
      <Button suffix={<ArrowRight />}>Get Started</Button>
    </Card>
  )
}
```

## Common Issues

### Module Not Found

If you see module not found errors, ensure:

- Dependencies are installed: `pnpm install`
- Next.js is configured to transpile the package
- You're using the correct import paths

### Styles Not Loading

If styles aren't applied:

- Verify `@vercel/geistcn/styles.css` is imported in your root layout
- Check that CSS imports are supported in your Next.js config
- Clear `.next` cache and rebuild

### TypeScript Errors

If you see TypeScript errors:

- Ensure React 19 types are installed: `@types/react@19.2.2`
- Check that TypeScript version is 5.6.3 or higher
- Restart your TypeScript server

## Next Steps

- Explore [Available Components](./available-components.md)
- Learn about [Import Patterns](./import-patterns.md)
- Check out [Common Patterns](./common-patterns.md)
- Review [Styling Guide](./styling-guide.md)
- See [Component Categories](./component-categories.md)

## Support

For issues and questions:

- Check the [Geist documentation](https://vercel.com/geist)
- Review component examples in the docs
- Refer to the source code in `packages/geist/src`
[V0_FILE]markdown:file="docs/icons-reference.md"
# Icons Reference

Complete reference for all 550+ icons available in the Geist Design System.

## Overview

Geist provides **550+ professionally designed icons** covering:

- UI actions and controls
- Navigation elements
- Status indicators
- File types
- Developer tools
- Social media platforms
- Cloud services
- Frameworks and technologies

All icons are:

- **16x16px base size** (scalable)
- **Consistent stroke weight**
- **Optimized for clarity**
- **Tree-shakeable**
- **Accessible** with proper ARIA labels

## Usage

### Basic Import

```tsx
import { ArrowRight } from '@vercel/geistcn/icons'

;<ArrowRight />
```

### With Props

```tsx
<ArrowRight
  size={24} // Size in pixels (default: 16)
  color="blue" // Color (default: currentColor)
  strokeWidth={2} // Stroke width (default: 1.5)
  className="my-icon" // Additional classes
/>
```

### All Props

| Prop          | Type            | Default        | Description                  |
| ------------- | --------------- | -------------- | ---------------------------- |
| `size`        | `number`        | `16`           | Icon size in pixels          |
| `color`       | `string`        | `currentColor` | Icon color (CSS color value) |
| `strokeWidth` | `number`        | `1.5`          | Stroke width                 |
| `className`   | `string`        | -              | Additional CSS classes       |
| `style`       | `CSSProperties` | -              | Inline styles                |

## Icon Categories

### UI Actions (50+ icons)

Common actions: `Plus`, `Minus`, `Cross`, `Check`, `Edit` (`Pencil`, `PencilEdit`, `Pen`), `Trash`, `Archive`, `Copy`, `Download`, `Upload`, `Save` (`FloppyDisk`), `Refresh` (`RefreshClockwise`, `RefreshCounterClockwise`), `Search` (`MagnifyingGlass`, `MagnifyingGlassPlus`, `MagnifyingGlassMinus`)

### Navigation (40+ icons)

**Arrows:** `ArrowRight`, `ArrowLeft`, `ArrowUp`, `ArrowDown`, `ArrowCircle*`, `ArrowUpRight`, `ArrowDownLeft`, etc., `ArrowLeftRight`, `ArrowUpDown`

**Chevrons:** `ChevronRight`, `ChevronLeft`, `ChevronUp`, `ChevronDown` (also Small, Double, and Circle variants)

**Corners:** `CornerDownRight`, `CornerUpRight`, `CornerLeftDown`, `CornerRightUp`, etc.

**Other:** `External`, `ExternalSmall`, `Menu`, `MenuAlt`, `MoreHorizontal`, `MoreVertical`

### Status & Indicators (30+ icons)

**Status:** `Check*` (Circle, Square, Fill variants), `Cross*`, `Warning*`, `Information*`, `Question*`, `Stop*`, `Status*`

**Progress:** `LoaderCircle`, `LoaderDots`, `Clock*`, `Stopwatch*` (Fast, Unread variants)

### User & Social (25+ icons)

**Users:** `User`, `Users`, `UserPlus`, `UserMinus`, `UserCross`, `UserCheck`, `UserSettings`, `UserLink`, `UserScreen`, `UserPasskey*`

**Faces:** `FaceHappy`, `FaceSmile`, `FacePlus`, `FaceUnhappy`, `FaceMeh`, `FaceSad`

**Social:** `ThumbUp`, `ThumbDown`, `Heart`, `HeartFill`

**Visibility:** `Eye`, `EyeDashed`, `EyeOff`, `EyeAllSeeing`

### Files & Folders (20+ icons)

**Folders:** `FolderClosed`, `FolderOpen`, `FolderPlus`, `FolderMinus`, `FolderDependent`, `FolderDependency`

**Files:** `File`, `FileText`, `FileZip`, `FileDependent`, `FileDependency`

**Documents:** `BookClosed`, `BookOpen`, `Notebook`, `Notes`, `Invoice`, `Clipboard`, `Presentation`

### Communication (15+ icons)

`Message`, `MessageTyping`, `Email`, `Envelope`, `Phone`, `Bell*` (Small, Off variants), `Notification`, `SupportFloat`, `SupportHeadset`

### Developer & Code (40+ icons)

**Code:** `Code`, `CodeBracket`, `CodeBlock`, `CodeWrap`, `Terminal`, `TerminalWindow`

**Git:** `GitBranch*`, `GitMerge`, `GitPullRequest`, `GitCommit`

**Functions:** `Function`, `Lambda`, `FunctionEdge`, `FunctionMiddleware`, `FunctionNode`, `FunctionPython`, `FunctionRuby`, `FunctionGo`, `FunctionN`

**Web:** `Api`, `Webhook`, `Monorepo`, `Repositories`, `Router`, `Servers`

**Acronyms:** `AcronymApi`, `AcronymHttp`, `AcronymJson`, `AcronymCsv`, `AcronymTs`, `AcronymJs`, `AcronymGif`, `AcronymJpg`, `AcronymSvg`, `AcronymMarkdown`, `AcronymPage`, `AcronymPpr`, `AcronymIsr`, `AcronymSsr`, `AcronymSsg`

### Cloud & Infrastructure (25+ icons)

**Cloud:** `Cloud`, `CloudUpload`, `CloudDownload`

**Vercel Services:** `Blob`, `Kv`, `EdgeConfig`, `Postgres`, `AiSdk`, `Edge`, `EdgeCache`, `DataCache`, `Cache`, `FluidCompute`, `Fluid`

**Security:** `Shield*`, `Firewall*`, `SecureConnection`, `Lock*` (Closed, Open, Small variants), `Key`, `KeyOld`

**Network:** `Globe*`, `NetworkDevice`, `Connection`, `Database`, `Cpu`

### Design & Layout (25+ icons)

**Layout:** `Layout*`, `Window*` (Variable, Critical, Advanced), `SidebarLeft`, `SidebarRight`, `Header`, `Footer`, `Toolbar`

**Display:** `Display`, `Tabs`

**Text:** `TextFormat`, `TextTitle`, `TextBold`, `TextItalic`, `TextStrikethrough`, `TextHeading`, `TextUppercase`

**Design Tools:** `BezierCurve`, `FillSquare`, `StrokeWeight`, `Crop`, `Glyphs`, `Languages`

### Media & Content (30+ icons)

**Images:** `Image`, `Camera`, `Webcam`, `WebcamOff`

**Video:** `Video`, `Play*`, `Pause`, `Skip*`, `StopCircle`, `Rewind10Seconds`, `Forward10Seconds10`, `Fullscreen*`, `ClosedCaptions`, `Shareplay`, `PictureInPicture`

**Audio:** `Music`, `MusicalNotes`, `Microphone*`, `Speaker*` (Fill, Off, Volume variants)

### Settings & Tools (20+ icons)

**Settings:** `SettingsGear*`, `SettingsSliders`, `SettingsSlider`

**Toggles:** `ToggleOn*`, `ToggleOff*` (Alt, AltUnread variants)

**Tools:** `Wrench`, `Pencil`, `Pen`, `Filter*`, `Calculator`, `Compass`

**Control:** `Command`, `Shift`, `Option`, `Tab`, `Backspace`

### Data & Analytics (15+ icons)

**Charts:** `ChartBar*` (Random, Middle, Peak), `ChartPie`, `ChartTrending*`, `ChartActivity`, `Analytics`, `Monitoring`

**Data:** `DataPoint*` (Low, Medium), `Gauge`

### Devices (10+ icons)

`DeviceDesktop*` (Alternate, AlternateSmall), `DevicePhone`, `DeviceTablet`

### Weather & Nature (10+ icons)

`Sun*` (Small, Alternate), `Moon*` (Small, Alternate), `Star*`, `Sparkles`, `Lightning`, `Droplet`, `PlantSprout`

### Brand Logos (100+ icons)

**Vercel Ecosystem:**

- `LogoVercel`, `LogoVercelFill`, `LogoVercelCircle`, `LogoVercelApi`
- `LogoNext`, `LogoTurborepo`, `LogoTurbopack`
- `LogoV0`, `LogoV0Wide`
- `LogoGeist`, `LogoHyper`, `LogoAcme`

**Social Media:**

- `LogoTwitter`, `LogoTwitterX`, `LogoTwitterXSmall`
- `LogoGithub`, `LogoGithubSmall`
- `LogoLinkedin`, `LogoLinkedinSmall`
- `LogoDiscord`, `LogoDiscordSmall`
- `LogoFacebook`, `LogoFacebookMessenger`
- `LogoReddit`, `LogoTiktok`
- `LogoYoutube`, `LogoYoutubeSmall`
- `LogoWhatsapp`, `LogoSlack`

**Frameworks:**

- `LogoReact`, `LogoVue`, `LogoAngular`
- `LogoSvelte`, `LogoNuxt`, `LogoRemix`, `LogoSolidstart`
- `LogoGatsby`, `LogoEmber`, `LogoAstro`, `LogoRedwoodjs`
- `LogoVite`, `LogoWebpack`

**Languages:**

- `LogoNode`, `LogoPython`, `LogoRuby`, `LogoRust`, `LogoGo`

**Cloud Platforms:**

- `LogoAws`, `LogoAzure`, `LogoAzureDevops`, `LogoGoogleCloudPlatform`

**Services:** `LogoGitlab`, `LogoBitbucket`, `LogoFigma`, `LogoLinear`, `LogoJira`, `LogoOpenai`, `LogoOkta`, `LogoLaunchdarkly`, `LogoMongodb`, `LogoContentful`, `LogoSanity`, `LogoDatocms`, `LogoBigcommerce`, `LogoSalesforce`, `LogoShopify`, `LogoWordpress`, `LogoStripe`, `LogoAmex`, `LogoVisa`, `LogoMastercard`, `LogoDatadog`, `LogoNewRelic`, `LogoSentry`, `LogoCheckly`, `LogoOtel`, `LogoMeta`, `LogoGoogle`, `LogoYCombinator`, `LogoSplitbee`, `LogoSitecoreXmcloud`, `LogoOptimizely`

### Business & Commerce (15+ icons)

`Briefcase`, `Cart`, `CreditCard`, `Coins`, `Dollar*`, `Invoice`, `Tag`, `Store`, `Buildings`, `V0CreditsV`, `V0Credits0`

### Miscellaneous (30+ icons)

**Location:** `Home`, `Location`, `Route`, `Gps`, `GoldenGate`

**Special:** `Bug`, `Robot`, `Fingerprint`, `Botid`, `QrCode*`, `CanaryBird`, `BeakerFlask`, `Lifebuoy`, `Anchor`, `Hook`, `Trace`, `Prism*`, `Fulcrum`, `Puzzle`, `Layers`, `Spiral`, `Diamond*`, `Asterisk*`, `Hash`, `Percentage`, `Slash*`, `ZeroConfig`, `BlendMode`, `Alpha`, `Cursor*`, `Lens`, `Crosshair`, `Target`, `Circle`, `HalfCircle`, `Paperclip`, `Pin`, `Bookmark`, `Flag*`, `Power`, `Incognito`, `VerifiedCheck*`, `Preview*`, `Inspect`, `Build`, `Undo`, `PaperAirplane`, `Rss`, `Delta`

## Dynamic Icon Loading

### Get Icon by Name

```tsx
import { getIconByName } from '@vercel/geistcn/icons/utils/get-icon-by-name'

const IconComponent = getIconByName('arrow-right')
<IconComponent size={24} />
```

### Name to Icon Converter

```tsx
import { nameToIcon } from '@vercel/geistcn/icons/utils/name-to-icon'

const icon = nameToIcon('check-circle')
```

### Get All Icon Names

```tsx
import { iconNames } from '@vercel/geistcn/icons/icon-names'

console.log(iconNames) // Array of all 550+ icon names
```

## Best Practices

### 1. Import Icons Individually

```tsx
// ✅ Good - Only imports what you need
import { ArrowRight } from '@vercel/geistcn/icons/arrow-right'

// ❌ Avoid - Imports entire library
import * as Icons from '@vercel/geistcn/icons'
```

### 2. Use Semantic Icon Names

```tsx
// ✅ Good - Clear intent
<Check color="green" />
<X color="red" />

// ❌ Unclear
<Circle color="green" />
<Plus color="red" />
```

### 3. Size Appropriately

```tsx
// ✅ Good - Consistent sizing
<ArrowRight size={16} /> // In text
<Settings size={20} />    // In buttons
<Logo size={24} />        // In headers

// ❌ Avoid - Inconsistent sizes
<ArrowRight size={13} />
<Settings size={19} />
```

### 4. Use CurrentColor for Theme Support

```tsx
// ✅ Good - Inherits text color
<Check /> // Uses currentColor by default

// ✅ Also good - Explicit currentColor
<Check color="currentColor" />

// ⚠️ Use carefully - Hard-coded colors
<Check color="#0070f3" />
```

### 5. Add ARIA Labels

```tsx
// ✅ Good - Accessible
<button aria-label="Close">
  <X />
</button>

// ❌ Not accessible
<button>
  <X />
</button>
```

## Common Patterns

```tsx
// Icon with text
<Button>
  <ArrowRight size={16} />
  <span>Continue</span>
</Button>

// Icon button
<button aria-label="Settings">
  <SettingsGear size={20} />
</button>

// Status icon
<div className="status">
  {isSuccess ? <CheckCircle color="green" /> : <Warning color="orange" />}
  <span>{message}</span>
</div>

// Loading icon
<LoaderCircle className="animate-spin" />

// Icon grid
{icons.map((Icon, i) => <Icon key={i} size={24} />)}
```

## Icon Naming Convention

Icons follow these naming patterns:

- **Action verbs**: `Play`, `Pause`, `Stop`, `Upload`, `Download`
- **Objects**: `User`, `File`, `Folder`, `Cloud`, `Shield`
- **Directions**: `ArrowRight`, `ChevronDown`, `CornerUpLeft`
- **States**: `CheckCircleFill`, `EyeOff`, `BellOff`
- **Sizes**: `Small` suffix for smaller variants (`BellSmall`, `LockClosedSmall`)
- **Styles**: `Fill` suffix for filled variants (`HeartFill`, `StarFill`)
- **Brand**: `Logo` prefix for brand icons (`LogoVercel`, `LogoReact`)
- **Acronyms**: `Acronym` prefix (`AcronymApi`, `AcronymJson`)

## Complete Icon List

All 550+ icons are available. Import them from `@vercel/geistcn/icons`:

```tsx
import {} from // ... any icon name from the categories above
'@vercel/geistcn/icons'
```

For the complete programmatic list:

```tsx
import { iconNames } from '@vercel/geistcn/icons/icon-names'
// Returns array of all icon names as strings
```

## TypeScript Support

All icons include full TypeScript definitions:

```tsx
import type { IconProps } from '@vercel/geistcn/icons'

const MyIcon: React.FC<IconProps> = (props) => {
  return <ArrowRight {...props} />
}
```

## Performance Tips

1. **Tree-shaking**: Import icons individually for optimal bundle size
2. **Code splitting**: Load icons dynamically for routes/features
3. **Memoization**: Wrap icon components in `React.memo()` if re-rendered frequently
4. **SVG optimization**: Icons are pre-optimized, no additional processing needed

This icon library provides comprehensive coverage for modern web applications!
[V0_FILE]markdown:file="docs/import-patterns.md"
# Import Patterns

Comprehensive guide to importing components, icons, and utilities from `@vercel/geistcn`.

## Component Imports

### Main Export (Recommended for Multiple Components)

Import multiple components from the main barrel export:

```tsx
import { Button, Input, Card, Badge, Text } from '@vercel/geistcn/components'
```

**Pros:**

- Clean, concise syntax
- Good for importing many components
- Works with Next.js optimizePackageImports

**Cons:**

- Slightly larger initial bundle (mitigated by optimizePackageImports)

### Modularized Imports (Best for Tree-Shaking)

Import from specific component paths:

```tsx
import { Button } from '@vercel/geistcn/components/button'
import { Input } from '@vercel/geistcn/components/input'
import { Card } from '@vercel/geistcn/components/card'
```

**Pros:**

- Maximum tree-shaking
- Smallest possible bundle size
- Fastest build times

**Cons:**

- More verbose
- Longer import statements

### Component Submodules

Some components have subcomponents or related exports:

```tsx
// Table with all subcomponents
import {
  Table,
  TableRoot,
  TableHeader,
  TableBody,
  TableRow,
  TableCell,
} from '@vercel/geistcn/components/table'

// Menu with all parts
import {
  Menu,
  MenuItem,
  MenuDivider,
  MenuButton,
  useMenu,
} from '@vercel/geistcn/components/menu'

// Modal with compound pattern
import { Modal } from '@vercel/geistcn/components/modal'
// Use as: Modal.Title, Modal.Body, Modal.Actions, etc.
```

## Icon Imports

### Individual Icons (Recommended)

Import only the icons you need for optimal bundle size:

```tsx
import { ArrowRight } from '@vercel/geistcn/icons/arrow-right'
import { Check } from '@vercel/geistcn/icons/check'
import { X } from '@vercel/geistcn/icons/x'
```

### Multiple Icons from Barrel Export

For multiple icons at once:

```tsx
import {
  ArrowRight,
  ArrowLeft,
  Check,
  X,
  Plus,
  Minus,
  Search,
  Menu as MenuIcon,
} from '@vercel/geistcn/icons'
```

### Dynamic Icons

For dynamic icon loading:

```tsx
import { getIconByName } from '@vercel/geistcn/icons/utils/get-icon-by-name'
import { nameToIcon } from '@vercel/geistcn/icons/utils/name-to-icon'

// Get icon by name
const Icon = getIconByName('arrow-right')

// Convert name to icon component
const IconComponent = nameToIcon('check')
```

### Icon Names List

Get all available icon names:

```tsx
import { iconNames } from '@vercel/geistcn/icons/icon-names'

console.log(iconNames) // ['arrow-right', 'check', 'x', ...] - 550+ icons
```

**See [Icons Reference](./icons-reference.md) for complete icon catalog organized by category.**

## Logo Imports

### Individual Logos

```tsx
import { VercelLogo } from '@vercel/geistcn/logos/vercel-mark'
import { NextjsLogo } from '@vercel/geistcn/logos/next-mark'
```

### Multiple Logos

```tsx
import {
  VercelLogo,
  VercelWordmark,
  NextjsLogo,
  NextWordmark,
  TurboLogo,
  TurboWordmark,
} from '@vercel/geistcn/logos'
```

### Logo Symbols

For SVG symbols:

```tsx
import VercelSymbol from '@vercel/geistcn/symbols/logos/vercel'
import NextSymbol from '@vercel/geistcn/symbols/logos/next'
```

### Pixel Logos

For pixel-style logos:

```tsx
import { VercelPixel } from '@vercel/geistcn/symbols/pixel/vercel'
import { nameToLogo } from '@vercel/geistcn/symbols/pixel/name-to-logo'
```

## Hooks and Utilities

### Component Hooks

Import hooks from their respective component paths:

```tsx
// Menu hook
import { useMenu } from '@vercel/geistcn/components/menu'

// Toast hooks
import { useToasts } from '@vercel/geistcn/components/toast'

// Radio hook
import { useRadio } from '@vercel/geistcn/components/radio-group'

// Collapse hook
import { useCollapse } from '@vercel/geistcn/components/collapse'

// Command menu hook
import { useCommandMenu } from '@vercel/geistcn/components/command-menu'
```

### Utility Functions

Import utilities from the utils barrel export:

```tsx
import {
  cn, // Class name merger
  useType, // Type hook
  toEm, // Convert to em
  toPixels, // Convert to pixels
  useMediaQuery, // Media query hook
} from '@vercel/geistcn/utils'
```

### Individual Utilities

For specific utilities:

```tsx
import { cn } from '@vercel/geistcn/utils/cn'
import { useMediaQuery } from '@vercel/geistcn/utils/use-media-query'
import { useId } from '@vercel/geistcn/utils/use-id'
import { forwardRef } from '@vercel/geistcn/utils/forward-ref'
```

### Core Utilities

```tsx
import { useDisabledContext } from '@vercel/geistcn/core/use-disabled-context'
```

## Type Imports

### Component Types

```tsx
import type { ButtonProps } from '@vercel/geistcn/components/button'
import type { InputProps } from '@vercel/geistcn/components/input'
import type { CardProps } from '@vercel/geistcn/components/card'
```

### General Types

```tsx
import type { ComponentProps, ColorType, SizeType } from '@vercel/geistcn/types'
```

### Calendar Types

```tsx
import type {
  CalendarProps,
  DateValue,
  Preset,
  Presets,
} from '@vercel/geistcn/components/calendar'
```

### Toast Types

```tsx
import type {
  ToastProps,
  ToastsHook,
  Message,
} from '@vercel/geistcn/components/toast'
```

## Style Imports

### Base Styles (Required)

```tsx
import '@vercel/geistcn/styles.css'
```

### Design System Styles

```tsx
import '@vercel/geistcn/styles/design-system.css'
```

### Syntax Highlighting

```tsx
import '@vercel/geistcn/styles/syntax-theme.module.css'
```

### Tailwind CSS

```tsx
import '@vercel/geistcn/tailwind.css'
```

## Provider Import

```tsx
import { GeistProvider } from '@vercel/geistcn/core/provider'

export default function App({ children }) {
  return <GeistProvider>{children}</GeistProvider>
}
```

## Configuration Imports

### Tailwind CSS v4 Setup

GeistCN uses Tailwind CSS v4 with CSS-first configuration. Import the pre-configured theme:

```tsx
// app/globals.css or app/layout.tsx
import '@vercel/geistcn/tailwind.css'
```

The `tailwind.css` file includes:

- Full Tailwind v4 theme configuration
- All GeistCN design tokens mapped to Tailwind utilities
- OKLCH color space for wide gamut display support
- Custom breakpoints, shadows, and spacing

### PostCSS Config

```js
// postcss.config.mjs
export default require('@vercel/geistcn/config/postcss')
```

Or create your own with `@tailwindcss/postcss`:

```js
// postcss.config.mjs
export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
}
```

## Best Practices

### 1. Use Modularized Imports for Large Apps

```tsx
// ✅ Good - Small bundle size
import { Button } from '@vercel/geistcn/components/button'

// ⚠️ Less optimal without optimizePackageImports
import { Button } from '@vercel/geistcn/components'
```

### 2. Group Related Imports

```tsx
// ✅ Good - Organized and readable
import { Button } from '@vercel/geistcn/components/button'
import { Input } from '@vercel/geistcn/components/input'
import { Card } from '@vercel/geistcn/components/card'
import { ArrowRight } from '@vercel/geistcn/icons/arrow-right'
import { cn } from '@vercel/geistcn/utils/cn'
```

### 3. Use Type Imports When Possible

```tsx
// ✅ Good - Explicitly mark types
import { Button } from '@vercel/geistcn/components/button'
import type { ButtonProps } from '@vercel/geistcn/components/button'
```

### 4. Import Icons Individually

```tsx
// ✅ Good - Only imports what you need
import { ArrowRight } from '@vercel/geistcn/icons/arrow-right'
import { Check } from '@vercel/geistcn/icons/check'

// ❌ Bad - Imports entire icon library
import * as Icons from '@vercel/geistcn/icons'
```

### 5. Use Aliases for Naming Conflicts

```tsx
import { Menu } from '@vercel/geistcn/components/menu'
import { Menu as MenuIcon } from '@vercel/geistcn/icons/menu'
```

## Import Path Reference

| What You Need       | Import Path                                   |
| ------------------- | --------------------------------------------- |
| Components (barrel) | `@vercel/geistcn/components`                  |
| Specific component  | `@vercel/geistcn/components/[component-name]` |
| Icons (barrel)      | `@vercel/geistcn/icons`                       |
| Specific icon       | `@vercel/geistcn/icons/[icon-name]`           |
| Logos               | `@vercel/geistcn/logos`                       |
| Provider            | `@vercel/geistcn/core/provider`               |
| Utilities           | `@vercel/geistcn/utils`                       |
| Types               | `@vercel/geistcn/types`                       |
| Styles              | `@vercel/geistcn/styles.css`                  |
| Tailwind            | `@vercel/geistcn/tailwind.css`                |
| Config              | `@vercel/geistcn/config/[config-type]`        |

## Next.js Optimization

Configure Next.js for optimal imports:

```js
// next.config.js
const nextConfig = {
  transpilePackages: ['@vercel/geistcn'],
  experimental: {
    optimizePackageImports: ['@vercel/geistcn'],
  },
}

module.exports = nextConfig
```

This enables automatic tree-shaking even when using barrel imports from `@vercel/geistcn/components`.
[V0_FILE]markdown:file="docs/quick-reference.md"
# Quick Reference Guide

Fast lookup reference for Geist Design System - most common tasks and components.

## Installation & Setup

```bash
pnpm add @vercel/geistcn
```

```tsx
// app/layout.tsx
import '@vercel/geistcn/styles.css'
import { GeistProvider } from '@vercel/geistcn/core/provider'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <GeistProvider>{children}</GeistProvider>
      </body>
    </html>
  )
}
```

## Most Used Components

### Forms

```tsx
import { Button } from '@vercel/geistcn/components/button'
import { Input } from '@vercel/geistcn/components/input'
import { Select } from '@vercel/geistcn/components/select'
import { Checkbox } from '@vercel/geistcn/components/checkbox'
import { Textarea } from '@vercel/geistcn/components/textarea'

<Input placeholder="Enter text" />
<Select>
  <option>Option 1</option>
</Select>
<Checkbox>I agree</Checkbox>
<Textarea placeholder="Message" />
<Button type="primary">Submit</Button>
```

### Layout

```tsx
import { Container } from '@vercel/geistcn/components/container'
import { Stack } from '@vercel/geistcn/components/stack'
import { Card } from '@vercel/geistcn/components/card'
import { Grid } from '@vercel/geistcn/components/grid'

<Container>
  <Stack gap={4}>
    <Card>Content</Card>
  </Stack>
</Container>

<Grid columns={3} gap={4}>
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Grid>
```

### Navigation

```tsx
import { Link } from '@vercel/geistcn/components/link'
import { Tabs } from '@vercel/geistcn/components/tabs'
import { Menu, MenuItem } from '@vercel/geistcn/components/menu'
import { Breadcrumbs } from '@vercel/geistcn/components/breadcrumbs'

<Link href="/page">Navigate</Link>

<Menu trigger={<Button>Menu</Button>}>
  <MenuItem>Option 1</MenuItem>
  <MenuItem>Option 2</MenuItem>
</Menu>
```

### Feedback

```tsx
import { useToasts } from '@vercel/geistcn/components/toast'
import { Modal } from '@vercel/geistcn/components/modal'
import { Spinner } from '@vercel/geistcn/components/spinner'
import { Progress } from '@vercel/geistcn/components/progress'

// Toasts
const toasts = useToasts()
toasts.success('Success!')
toasts.error('Error!')

// Modal
<Modal open={open} onOpenChange={setOpen}>
  <Modal.Title>Title</Modal.Title>
  <Modal.Body>Content</Modal.Body>
  <Modal.Actions>
    <Modal.Action>Confirm</Modal.Action>
  </Modal.Actions>
</Modal>

// Loading
<Spinner />
<Progress value={50} />
```

### Display

```tsx
import { Text } from '@vercel/geistcn/components/text'
import { Badge } from '@vercel/geistcn/components/badge'
import { Code } from '@vercel/geistcn/components/code'
import { Table } from '@vercel/geistcn/components/table'

<Text size={16} weight="bold">Hello</Text>
<Badge type="success">Active</Badge>
<Code>console.log('hello')</Code>
```

## Common Icons

```tsx
import {
  ArrowRight,
  ArrowLeft,
  Check,
  X,
  Plus,
  Minus,
  Search,
  Menu,
  Settings,
  User,
  Home,
  ChevronDown,
  ChevronUp,
  Edit,
  Trash,
  Copy,
  ExternalLink
} from '@vercel/geistcn/icons'

<ArrowRight size={16} />
<Check color="green" />
<Search size={20} />
```

## Import Patterns

```tsx
// Components (modular - best for tree-shaking)
import { Button } from '@vercel/geistcn/components/button'

// Components (barrel - good with optimizePackageImports)
import { Button, Input, Card } from '@vercel/geistcn/components'

// Icons (individual - recommended)
import { ArrowRight } from '@vercel/geistcn/icons/arrow-right'

// Icons (barrel)
import { ArrowRight, Check } from '@vercel/geistcn/icons'

// Types
import type { ButtonProps } from '@vercel/geistcn/components/button'

// Utilities
import { cn } from '@vercel/geistcn/utils/cn'
```

## TypeScript

```tsx
// Component props
import type { ButtonProps } from '@vercel/geistcn/components/button'

interface CustomButtonProps extends ButtonProps {
  variant: 'special'
}

// With forwardRef
import { forwardRef } from '@vercel/geistcn/utils/forward-ref'

const CustomButton = forwardRef<HTMLButtonElement, CustomButtonProps>(
  ({ variant, ...props }, ref) => {
    return <Button ref={ref} {...props} />
  },
)
```

## Styling

```tsx
// Using className
<Button className="mt-4 px-6">Styled</Button>

// Using cn utility
import { cn } from '@vercel/geistcn/utils/cn'
<Button className={cn('base-class', isActive && 'active')}>Button</Button>

// Component variants
<Button type="primary">Primary</Button>
<Button type="error">Error</Button>
<Button size="small">Small</Button>

// Inline styles
<Button style={{ marginTop: 20 }}>Styled</Button>
```

## Form Example

```tsx
'use client'

import { Button } from '@vercel/geistcn/components/button'
import { Input } from '@vercel/geistcn/components/input'
import { Fieldset } from '@vercel/geistcn/components/fieldset'
import { useToasts } from '@vercel/geistcn/components/toast'

export function ContactForm() {
  const toasts = useToasts()

async function handleSubmit(e: React.FormEvent) {
    e.preventDefault()
    await submitForm()
    toasts.success('Form submitted!')
  }

return (
    <form onSubmit={handleSubmit}>
      <Fieldset>
        <Input name="email" type="email" label="Email" required />
        <Input name="name" label="Name" required />
        <Button type="submit">Submit</Button>
      </Fieldset>
    </form>
  )
}
```

## Modal Example

```tsx
'use client'

import { Modal } from '@vercel/geistcn/components/modal'
import { Button } from '@vercel/geistcn/components/button'
import { useState } from 'react'

export function DeleteButton() {
  const [open, setOpen] = useState(false)

return (
    <>
      <Button onClick={() => setOpen(true)}>Delete</Button>
      <Modal open={open} onOpenChange={setOpen}>
        <Modal.Title>Confirm Deletion</Modal.Title>
        <Modal.Body>Are you sure?</Modal.Body>
        <Modal.Actions>
          <Modal.Action passive onClick={() => setOpen(false)}>
            Cancel
          </Modal.Action>
          <Modal.Action onClick={handleDelete}>Delete</Modal.Action>
        </Modal.Actions>
      </Modal>
    </>
  )
}
```

## Toast Notifications

```tsx
'use client'

import { useToasts } from '@vercel/geistcn/components/toast'
import { Button } from '@vercel/geistcn/components/button'

export function NotifyButton() {
  const toasts = useToasts()

return (
    <>
      <Button onClick={() => toasts.success('Success!')}>Success</Button>
      <Button onClick={() => toasts.error('Error!')}>Error</Button>
      <Button onClick={() => toasts.warning('Warning!')}>Warning</Button>
      <Button onClick={() => toasts.message('Info')}>Info</Button>
    </>
  )
}
```

## Table Example

export function UserTable({ users }) {
  return (
    <TableRoot>
      <Table>
        <TableHeader>
          <TableRow>
            <TableHead>Name</TableHead>
            <TableHead>Status</TableHead>
          </TableRow>
        </TableHeader>
        <TableBody>
          {users.map((user) => (
            <TableRow key={user.id}>
              <TableCell>{user.name}</TableCell>
              <TableCell>
                <Badge type="success">Active</Badge>
              </TableCell>
            </TableRow>
          ))}
        </TableBody>
      </Table>
    </TableRoot>
  )
}
```

## Loading States

```tsx
import { Skeleton } from '@vercel/geistcn/components/skeleton'
import { Spinner } from '@vercel/geistcn/components/spinner'
import { LoadingDots } from '@vercel/geistcn/components/loading-dots'
import { Button } from '@vercel/geistcn/components/button'

// Skeleton
<Skeleton width="100%" height={20} />

// Spinner
<Spinner />

// Loading Dots
<LoadingDots />

// Button loading state
<Button loading>Loading...</Button>
```

## Responsive Utilities

```tsx
import { useMediaQuery } from '@vercel/geistcn/utils/use-media-query'

function MyComponent() {
  const isMobile = useMediaQuery('(max-width: 768px)')

return isMobile ? <MobileView /> : <DesktopView />
}

// Tailwind responsive classes
;<div className="p-4 md:p-6 lg:p-8">Responsive padding</div>
```

## Common Hooks

```tsx
// Toasts
import { useToasts } from '@vercel/geistcn/components/toast'
const toasts = useToasts()

// Menu
import { useMenu } from '@vercel/geistcn/components/menu'
const { visible, setVisible, bindings } = useMenu()

// Collapse
import { useCollapse } from '@vercel/geistcn/components/collapse'
const { visible, bindings } = useCollapse()

// Command Menu
import { useCommandMenu } from '@vercel/geistcn/components/command-menu'
const { isOpen, setIsOpen } = useCommandMenu()

// Media Query
import { useMediaQuery } from '@vercel/geistcn/utils/use-media-query'
const isMobile = useMediaQuery('(max-width: 768px)')

// Disabled Context
import { useDisabledContext } from '@vercel/geistcn/core/use-disabled-context'
const disabled = useDisabledContext()
```

## Component Props Cheat Sheet

### Button

### Input

- `type`: 'text' | 'email' | 'password' | 'number'
- `label`: string
- `placeholder`: string
- `disabled`: boolean
- `error`: boolean

### Badge

### Text

- `size`: number
- `weight`: 'normal' | 'medium' | 'bold'
- `variant`: 'h1' | 'h2' | 'body'

### Icon (all icons)

- `size`: number (default: 16)
- `color`: string
- `strokeWidth`: number

## Next.js Config

```js
// next.config.js
const nextConfig = {
  transpilePackages: ['@vercel/geistcn'],
  experimental: {
    optimizePackageImports: ['@vercel/geistcn'],
  },
}

module.exports = nextConfig
```

## Tailwind Config

```js
// tailwind.config.js
import geistConfig from '@vercel/geistcn/config/tailwindcss'
import geistPlugins from '@vercel/geistcn/config/tailwindcss-plugins'

export default {
  ...geistConfig,
  content: ['./app/**/*.tsx'],
  plugins: [...geistPlugins],
}
```

## Common Pitfalls

❌ **Don't import everything**

```tsx
import * as Geist from '@vercel/geistcn/components' // Too large
```

✅ **Do import specifically**

```tsx
import { Button } from '@vercel/geistcn/components/button'
```

❌ **Don't forget 'use client'**

```tsx
// Missing 'use client' for hooks
function MyComponent() {
  const toasts = useToasts() // Error!
}
```

✅ **Do add 'use client'**

```tsx
'use client'
function MyComponent() {
  const toasts = useToasts() // Works!
}
```

❌ **Don't forget to import styles**

```tsx
// Styles not imported - components won't look right
```

✅ **Do import styles in layout**

```tsx
// app/layout.tsx
import '@vercel/geistcn/styles.css'
```

## Decision Tree

**Need user input?** → Use `Input`, `Select`, `Checkbox`, `Textarea`

**Need an action?** → Use `Button`, `Link`

**Need to show data?** → Use `Table`, `Card`, `Text`, `Badge`

**Need layout?** → Use `Container`, `Stack`, `Grid`

**Need navigation?** → Use `Link`, `Tabs`, `Menu`, `Sidebar`

**Need feedback?** → Use `Toast`, `Modal`, `Progress`, `Spinner`

**Need conditional display?** → Use `Collapse`, `ShowMore`, `Tabs`

## Resources

- **Full Docs:** [README.md](./README.md)
- **Setup:** [Getting Started](./getting-started.md)
- **All Components:** [Available Components](./available-components.md)
- **All Icons:** [Icons Reference](./icons-reference.md) - 550+ icons
- **Examples:** [Common Patterns](./common-patterns.md)
- **Categories:** [Component Categories](./component-categories.md)
- **🎨 Tailwind:** [Tailwind Integration](./tailwind-integration.md) - Color classes, typography
- **Styling:** [Styling Guide](./styling-guide.md) - Colors, tokens, variables
- **TypeScript:** [TypeScript Guide](./typescript-guide.md)
- **⚠️ Mistakes:** [Common Mistakes](./common-mistakes.md) - What to avoid
[V0_FILE]markdown:file="docs/README.md"
# GeistCN Design System Documentation

Complete documentation for the `@vercel/geistcn` design system - Vercel's next-generation UI component library with Tailwind CSS v4.

## Overview

GeistCN is a modern, accessible design system built for React 19 and Next.js 15+. It provides 80+ production-ready components, 550+ icons, and a comprehensive theming system using Tailwind CSS v4 and OKLCH colors for wide gamut display support.

**Key Features:**

- 80+ React components
- 550+ customizable icons
- Built-in dark mode support
- Accessible by default (ARIA compliant)
- Tree-shakeable and optimized
- TypeScript native
- Works with Next.js App Router
- **Tailwind CSS v4** with CSS-first configuration
- **OKLCH color space** for better color accuracy and P3 display support

## Documentation Structure

### Essential Guides

#### [Getting Started](./getting-started.md)

**Read this first!** Complete setup guide covering:

- Installation instructions
- Basic configuration
- Next.js integration
- Provider setup
- First component usage
- Common setup issues

**When to use:** Starting a new project or adding GeistCN to existing project.

#### [Available Components](./available-components.md)

**Complete component reference** listing all 80+ components:

- All available components with descriptions
- Component import paths
- Icons and logos catalog
- Hooks and utilities
- Configuration options
- Package information

**When to use:** Looking up what components exist or checking import paths.

#### [Icons Reference](./icons-reference.md)

**Complete icon library** with 550+ icons:

- All available icons organized by category
- Icon props and customization
- Dynamic icon loading
- Usage patterns and best practices
- Brand logos reference

**When to use:** Finding the right icon or looking up icon names.

#### [Import Patterns](./import-patterns.md)

**Import guide** covering all import methods:

- Component import strategies
- Icon and logo imports
- Hook imports
- Type imports
- Style imports
- Best practices for bundle optimization

**When to use:** Deciding how to import components or optimizing bundle size.

### Practical Guides

#### [Common Patterns](./common-patterns.md)

**Real-world examples** showing how to:

- Build forms with validation
- Create modals and dialogs
- Show toast notifications
- Build navigation menus
- Create data tables
- Handle loading states
- Implement responsive layouts
- Add accessibility features

**When to use:** Implementing common UI patterns or looking for code examples.

#### [Component Categories](./component-categories.md)

**Component selection guide** organized by use case:

- Components grouped by purpose (forms, navigation, feedback, etc.)
- "When to use which component" decision guide
- Component relationships and combinations
- Quick reference tables
- Compound component patterns

**When to use:** Unsure which component to use for your use case.

#### [Tailwind Integration](./tailwind-integration.md)

**Using GeistCN with Tailwind CSS v4:**

- Tailwind color classes mapped to design tokens
- OKLCH color system
- Typography utility classes
- Material utility classes
- Real-world examples
- **Important: Shows how `bg-gray-900` etc. work correctly**

**When to use:** Using Tailwind CSS with GeistCN or wondering about color classes.

#### [Styling Guide](./styling-guide.md)

**Styling methods and customization:**

- Tailwind utility classes in JSX
- Theme system and variables
- Component variants
- Responsive styling
- Custom styling patterns
- Animation and transitions
- **Design tokens reference** (colors, spacing, typography)

**When to use:** Customizing component appearance or integrating with your design system.

#### [Common Mistakes](./common-mistakes.md)

**Anti-patterns and how to avoid them:**

- Wrong import paths (shadcn/ui confusion)
- Using wrong icon libraries (lucide-react)
- Hardcoded colors instead of design tokens
- Wrong component APIs (`variant` vs `type`)
- Missing setup requirements
- **Correct pattern examples**

**When to use:** Debugging issues or ensuring you're following best practices.

#### [TypeScript Guide](./typescript-guide.md)

**TypeScript patterns and best practices:**

- Component prop types
- Hook types
- Generic components
- ForwardRef patterns
- Event handler types
- Type guards
- Advanced type patterns

**When to use:** Working with TypeScript or need type-safe implementations.

## Quick Start

```bash
# Install
pnpm add @vercel/geistcn

# Setup
import '@vercel/geistcn/styles.css'
import { GeistProvider } from '@vercel/geistcn/core/provider'

# Use
import { Button } from '@vercel/geistcn/components/button'
<Button>Click me</Button>
```

See [Getting Started](./getting-started.md) for complete setup instructions.

## Component Overview

### Most Commonly Used Components

**Forms & Input:**

- `Button` - Buttons and actions
- `Input` - Text inputs
- `Select` - Dropdowns
- `Checkbox` - Checkboxes
- `Textarea` - Multi-line input

**Layout:**

- `Grid` - Grid layouts
- `Card` - Content cards
- `Stack` - Spacing utility

**Navigation:**

- `Link` - Links and navigation
- `Tabs` - Tab navigation
- `Menu` - Dropdown menus
- `Breadcrumbs` - Breadcrumb trails

**Feedback:**

- `Toasts` - Notifications
- `Modal` - Dialogs
- `Skeleton` - Loading placeholders

**Display:**

- `Text` - Typography
- `Badge` - Status badges
- `Table` - Data tables
- `Code` - Code display

See [Available Components](./available-components.md) for the complete list.

## Architecture

### Component Import Paths

```
@vercel/geistcn/
├── components/          # React components
│   ├── button/
│   ├── input/
│   └── ...
├── icons/              # Icon library (550+)
├── logos/              # Logo components
├── core/               # Core utilities
│   └── provider/       # GeistProvider
├── utils/              # Utility functions
├── types/              # TypeScript types
├── styles.css          # Base styles
├── tailwind.css        # Tailwind v4 theme config
└── config/             # PostCSS configs
```

### Design Principles

1. **Accessibility First** - WCAG 2.1 AA compliant
2. **Composable** - Build complex UIs from simple components
3. **Performant** - Tree-shakeable, optimized bundles
4. **Type-Safe** - Full TypeScript support
5. **Themeable** - Built-in light/dark mode
6. **Modern Colors** - OKLCH for wide gamut displays

## Key Differences from @vercel/geist

| Feature              | @vercel/geist | @vercel/geistcn            |
| -------------------- | ------------- | -------------------------- |
| **Tailwind Version** | v3            | v4 (CSS-first)             |
| **Color Format**     | HSL           | OKLCH (wide gamut)         |
| **Styling**          | CSS Modules   | Tailwind utilities in JSX  |
| **Bundle Size**      | Larger        | Smaller (Tailwind purging) |

## Common Use Cases

### Building a Form

→ See [Common Patterns - Forms](./common-patterns.md#form-patterns)

### Creating a Modal

→ See [Common Patterns - Modals](./common-patterns.md#modal-patterns)

### Showing Notifications

→ See [Common Patterns - Toasts](./common-patterns.md#toast-notifications)

### Building Navigation

→ See [Common Patterns - Navigation](./common-patterns.md#navigation-patterns)

### Styling Components

→ See [Styling Guide](./styling-guide.md)

### Using with TypeScript

→ See [TypeScript Guide](./typescript-guide.md)

## Best Practices

### Performance

- Use modularized imports for better tree-shaking
- Enable `optimizePackageImports` in Next.js config
- Import icons individually, not from barrel export
- Use code splitting for large component libraries

### Accessibility

- Always provide labels for form inputs
- Use semantic HTML via component `as` props
- Include ARIA attributes when needed
- Test with keyboard navigation
- Use `SkipNavLink` for main content

### Styling

- Use Tailwind utility classes
- Leverage the `cn()` utility for class merging
- Use CSS custom properties for theming
- Keep styles maintainable and reusable

### TypeScript

- Import types separately with `import type`
- Use proper ref types with `forwardRef`
- Define clear prop interfaces
- Leverage type inference where possible
- Use discriminated unions for variants

## Component Categories

Components are organized into these categories:

1. **Input & Forms** (12 components) - User input collection
2. **Buttons & Actions** (6 components) - Triggering actions
3. **Layout & Structure** (5 components) - Page organization
4. **Navigation** (12 components) - Site navigation
5. **Overlays & Dialogs** (8 components) - Focused interactions
6. **Display & Content** (18 components) - Information display
7. **Feedback & Status** (10 components) - System feedback
8. **Media & Assets** (6 components) - Images and media
9. **Interactive** (6 components) - Advanced interactions
10. **Icons & Branding** (550+ icons, logos)

See [Component Categories](./component-categories.md) for details.

## Browser Support

- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)
- Mobile browsers (iOS Safari, Chrome Android)

## Requirements

- **React:** 19.2.0
- **Next.js:** >= 15.4.2-canary.47
- **TypeScript:** >= 5.6.3 (recommended)
- **Node.js:** 22.x
- **Tailwind CSS:** >= 4.1.x

## Package Information

```json
{
  "name": "@vercel/geistcn",
  "version": "0.0.35",
  "type": "module",
  "sideEffects": false
}
```

## Integration Examples

### With Next.js App Router

```tsx
// app/layout.tsx
import '@vercel/geistcn/styles.css'
import { GeistProvider } from '@vercel/geistcn/core/provider'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <GeistProvider>{children}</GeistProvider>
      </body>
    </html>
  )
}
```

### With Tailwind CSS v4

```tsx
// app/globals.css or layout.tsx
import '@vercel/geistcn/tailwind.css'
```

The `tailwind.css` file includes the full Tailwind v4 theme configuration with all GeistCN design tokens mapped to Tailwind color utilities.

### With TypeScript

```tsx
import type { ButtonProps } from '@vercel/geistcn/components/button'
import { Button } from '@vercel/geistcn/components/button'

const MyButton: React.FC<ButtonProps> = (props) => {
  return <Button {...props} />
}
```

## Documentation for LLMs

This documentation is optimized for AI/LLM consumption with:

- **Clear structure** - Hierarchical organization
- **Comprehensive examples** - Real-world code samples
- **Use case guidance** - When to use what
- **Type information** - Full TypeScript coverage
- **Cross-references** - Links between related topics
- **Decision guides** - Component selection help
- **Best practices** - Recommended patterns
- **Common pitfalls** - What to avoid

### For LLMs: How to Use This Documentation

1. **Start with [Getting Started](./getting-started.md)** to understand setup
2. **Reference [Available Components](./available-components.md)** for what exists
3. **Use [Component Categories](./component-categories.md)** to select components
4. **Check [Common Patterns](./common-patterns.md)** for implementation examples
5. **Consult [Import Patterns](./import-patterns.md)** for import strategies
6. **Review [Styling Guide](./styling-guide.md)** for customization
7. **Refer to [TypeScript Guide](./typescript-guide.md)** for type safety

### Key Information for Code Generation

- All components are React Server Components compatible
- Use `'use client'` directive for components with hooks
- Import styles at the root layout level
- Wrap app with `GeistProvider` for full functionality
- Use modularized imports for optimal bundle size
- All components accept standard HTML attributes
- Components use Radix UI primitives where applicable
- **Styling uses Tailwind utility classes directly in JSX**

## Additional Resources

- **Source Code:** `packages/geistcn/src`
- **Component Examples:** Individual component docs in `docs/components/`
- **Vercel Website:** https://vercel.com/geist
- **Next.js Documentation:** https://nextjs.org

## Support

For issues and questions:

1. Check the relevant guide in this documentation
2. Review component-specific docs in `docs/components/`
3. Inspect the source code in `packages/geistcn/src`
4. Refer to Vercel's official documentation
5. Contact: #project-geistcn Slack channel, Team DENG, @severinlandolt, @christopherkindl

---

**Last Updated:** 2025
**Package Version:** 0.0.35
**React Version:** 19.2.0
**Next.js Version:** >= 15.4.2-canary.47
**Tailwind CSS Version:** >= 4.1.x
[V0_FILE]markdown:file="docs/styling-guide.md"
# Styling Guide

Comprehensive guide to styling geistcn components and integrating with your design system.

> **Note:** geistcn uses **Tailwind CSS v4** with **OKLCH colors** for P3 wide gamut support. This is a CSS-first configuration approach, different from Tailwind v3.

## Styling Methods

Geist components support multiple styling approaches:

### 1. CSS Classes (Recommended)

Most components accept `className` prop:

```tsx
import { Button } from '@vercel/geistcn/components/button'
import { Card } from '@vercel/geistcn/components/card'

<Button className="my-custom-button">Click me</Button>
<Card className="custom-card">Content</Card>
```

### 2. Inline Styles

For dynamic or one-off styles:

```tsx
<Button style={{ marginTop: 20, backgroundColor: 'blue' }}>
  Custom Button
</Button>
```

### 3. CSS Modules

Create scoped styles:

```css
/* styles.module.css */
.customButton {
  padding: 12px 24px;
  border-radius: 8px;
}
```

```tsx
import styles from './styles.module.css'

;<Button className={styles.customButton}>Styled Button</Button>
```

### 4. Tailwind CSS

Geist works seamlessly with Tailwind:

```tsx
<Button className="mt-4 px-6 py-3 rounded-lg">
  Tailwind Styled
</Button>

<Card className="p-6 shadow-lg hover:shadow-xl transition-shadow">
  Tailwind Card
</Card>
```

## Using the `cn` Utility

Geist provides a `cn` utility for merging class names (combines `clsx` + `tailwind-merge`):

```tsx
import { cn } from '@vercel/geistcn/utils/cn'

;<Button
  className={cn(
    'base-styles',
    isActive && 'active-styles',
    isDisabled && 'disabled-styles',
  )}
>
  Button
</Button>
```

### Benefits of `cn`

- Merges Tailwind classes intelligently
- Handles conditional classes
- Resolves conflicting Tailwind utilities

```tsx
// Without cn - padding conflict
<div className="p-4 p-6"> // Both apply

// With cn - resolves to p-6
<div className={cn('p-4', 'p-6')}> // Only p-6 applies
```

## Tailwind Integration

### Setup Tailwind with geistcn (Tailwind v4)

geistcn uses Tailwind v4's CSS-first configuration. Instead of a JavaScript config file, you import the config CSS:

```css
/* app/globals.css */
@import 'tailwindcss';
@import '@vercel/geistcn/styles.css';

/* Or with explicit config import */
@import 'tailwindcss';
@import '@vercel/geistcn/config/tailwindcss.css';
```

For projects needing a JavaScript config:

```js
// tailwind.config.js (optional for v4)
import geistConfig from '@vercel/geistcn/config/tailwindcss'
import geistPlugins from '@vercel/geistcn/config/tailwindcss-plugins'

export default {
  ...geistConfig,
  content: [
    './app/**/*.{js,ts,jsx,tsx}',
    './components/**/*.{js,ts,jsx,tsx}',
    './node_modules/@vercel/geistcn/**/*.{js,ts,jsx,tsx}',
  ],
  plugins: [...geistPlugins],
}
```

### Import Tailwind Styles

```tsx
// app/layout.tsx
import '@vercel/geistcn/tailwind.css'
// Or use base styles
import '@vercel/geistcn/styles.css'
```

### geistcn's Tailwind Color System (OKLCH)

geistcn uses **OKLCH colors** for P3 wide gamut support. Colors are defined using the modern OKLCH color space:

```tsx
// Gray scale (automatically theme-aware, OKLCH-based)
<div className="text-gray-900">Secondary text</div>
<div className="text-gray-1000">Primary text</div>
<div className="bg-gray-100">Light background</div>
<div className="bg-gray-200">Subtle background</div>
<div className="border-gray-200">Border</div>

// Background colors
<div className="bg-background-100">Primary background</div>
<div className="bg-background-200">Secondary background</div>

// Semantic colors
<div className="bg-blue-700">Primary blue</div>
<div className="bg-red-700">Error red</div>
<div className="bg-green-700">Success green</div>

// Alpha borders (with transparency)
<div className="border-gray-alpha-200">Subtle border</div>
<div className="border-gray-alpha-400">Medium border</div>

// Aliases (mapped to design tokens)
<div className="bg-black">Maps to gray-1000</div>
<div className="bg-white">Maps to background-100</div>
<div className="text-foreground">Maps to gray-1000</div>
```

**OKLCH Benefits:**

- Wider color gamut (P3 display support)
- Perceptually uniform lightness
- Better color interpolation for gradients
- More vibrant colors on supported displays

### Tailwind Typography Presets

Geist provides typography utility classes:

```tsx
// Headings
<h1 className="text-heading-72">72px heading</h1>
<h2 className="text-heading-64">64px heading</h2>
<h2 className="text-heading-32">32px heading</h2>
<h3 className="text-heading-24">24px heading</h3>

// Body copy
<p className="text-copy-16">16px body text</p>
<p className="text-copy-14">14px body text</p>

// Labels
<label className="text-label-14">14px label</label>
<span className="text-label-12">12px label</span>

// Buttons
<button className="text-button-16">16px button text</button>
```

### Material Utility Classes

Pre-built card/surface styles:

```tsx
<div className="material-small">Small card with shadow</div>
<div className="material-medium">Medium card</div>
<div className="material-large">Large card</div>
<div className="material-menu">Menu surface</div>
<div className="material-modal">Modal surface</div>
```

## Component Variants

Many components have built-in variant props:

### Button Variants

```tsx
// Visual style variants (use 'variant' prop)
<Button variant="primary">Primary</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="tertiary">Tertiary</Button>
<Button variant="success">Success</Button>
<Button variant="warning">Warning</Button>
<Button variant="error">Error</Button>

// Sizes
<Button size="small">Small</Button>
<Button size="medium">Medium</Button>
<Button size="large">Large</Button>

// HTML button type (use 'type' prop)
<Button type="button">Button</Button>
<Button type="submit">Submit</Button>
<Button type="reset">Reset</Button>
```

**Important:** In geistcn, Button uses:

- `variant` prop for **visual style** (primary, secondary, tertiary, success, warning, error)
- `type` prop for **HTML button type** (button, submit, reset)

This is different from @vercel/geist where `type` was used for visual style.

### Badge Variants

```tsx
<Badge type="success">Success</Badge>
<Badge type="error">Error</Badge>
<Badge type="warning">Warning</Badge>
<Badge type="default">Default</Badge>
```

### Text Variants

```tsx
<Text size={12}>Small text</Text>
<Text size={14}>Default text</Text>
<Text size={16}>Large text</Text>

<Text weight="normal">Normal</Text>
<Text weight="medium">Medium</Text>
<Text weight="bold">Bold</Text>
```

**Note:** Text component uses `size` and `weight` props. For semantic HTML, use proper heading tags (`<h1>`, `<h2>`) instead of variant props.

## Theme System

### Using GeistProvider

The `GeistProvider` enables theming:

```tsx
import { GeistProvider } from '@vercel/geistcn/core/provider'

;<GeistProvider
  theme={{
    type: 'dark', // 'light' | 'dark' | 'auto'
  }}
>
  <App />
</GeistProvider>
```

### Theme Switcher

```tsx
import { ThemeSwitcher } from '@vercel/geistcn/components/theme-switcher'

;<ThemeSwitcher />
```

### Custom Theme Variables

Geist uses CSS custom properties that you can override:

```css
/* app/globals.css */
:root {
  --geist-foreground: #000;
  --geist-background: #fff;
  --geist-primary: #0070f3;
  --geist-success: #0070f3;
  --geist-error: #ee0000;
  --geist-warning: #f5a623;
}

[data-theme='dark'] {
  --geist-foreground: #fff;
  --geist-background: #000;
}
```

## Color System

### Geist Colors with Tailwind

When using Geist's Tailwind config, color classes are automatically mapped to design tokens:

```tsx
// Text colors (Tailwind classes → design tokens)
<Text className="text-gray-900">Secondary text</Text>
<Text className="text-gray-1000">Primary text</Text>
<Text className="text-gray-600">Muted text</Text>

// Background colors (Tailwind classes → design tokens)
<div className="bg-background-100">Primary background</div>
<div className="bg-background-200">Secondary background</div>
<div className="bg-gray-100">Subtle background</div>

// Accent colors (Tailwind classes → design tokens)
<div className="bg-blue-700 text-white">Blue background</div>
<div className="bg-green-700">Green background</div>
<div className="bg-red-700">Red background</div>

// Border colors
<div className="border border-gray-200">Default border</div>
<div className="border border-gray-alpha-200">Subtle transparent border</div>
```

**How it works:** geistcn's Tailwind config maps classes like `bg-gray-900` to OKLCH color values via CSS custom properties, so they automatically support dark mode, theming, and P3 wide gamut displays.

### Icon Colors

```tsx
import { Check } from '@vercel/geistcn/icons'

<Check color="success" />
<Check color="error" />
<Check color="warning" />
<Check color="gray-900" />
<Check color="#0070f3" />
```

## Responsive Styling

### Tailwind Breakpoints

```tsx
<div className="p-4 md:p-6 lg:p-8">
  Responsive padding
</div>

<Grid className="grid-cols-1 md:grid-cols-2 lg:grid-cols-3">
  Responsive grid
</Grid>
```

### Theme Variants (geistcn-specific)

geistcn provides custom Tailwind variants for theme-specific styling:

```tsx
// Apply styles only in dark theme
<div className="dark-theme:bg-gray-900 dark-theme:text-white">
  Dark mode only
</div>

// Apply styles only in light theme
<div className="light-theme:bg-white light-theme:text-gray-900">
  Light mode only
</div>

// Combined example
<Card className="bg-white light-theme:shadow-md dark-theme:bg-gray-900 dark-theme:border-gray-800">
  Theme-aware card
</Card>
```

### useMediaQuery Hook

```tsx
import { useMediaQuery } from '@vercel/geistcn/utils/use-media-query'

function ResponsiveComponent() {
  const isMobile = useMediaQuery('(max-width: 768px)')
  const isDesktop = useMediaQuery('(min-width: 1024px)')

return isMobile ? <MobileView /> : <DesktopView />
}
```

### Responsive Props

Some components support responsive props:

```tsx
<Text size={{ xs: 12, md: 14, lg: 16 }}>
  Responsive text
</Text>

<Stack gap={{ xs: 2, md: 4, lg: 6 }}>
  Responsive gap
</Stack>
```

## Custom Component Styling

### Wrapping Components

Create custom styled wrappers:

```tsx
// components/CustomButton.tsx
import { Button } from '@vercel/geistcn/components/button'
import { cn } from '@vercel/geistcn/utils/cn'

export function CustomButton({ className, ...props }) {
  return (
    <Button
      className={cn(
        'bg-gradient-to-r from-blue-500 to-purple-500',
        'hover:from-blue-600 hover:to-purple-600',
        'text-white font-semibold',
        className,
      )}
      {...props}
    />
  )
}
```

### Using forwardRef

For proper ref handling:

```tsx
import { forwardRef } from '@vercel/geistcn/utils/forward-ref'
import { Button } from '@vercel/geistcn/components/button'

export const CustomButton = forwardRef<
  HTMLButtonElement,
  React.ComponentProps<typeof Button>
>(({ className, ...props }, ref) => {
  return (
    <Button ref={ref} className={cn('custom-styles', className)} {...props} />
  )
})
```

## Design Tokens & CSS Variables

Geist provides a comprehensive set of CSS custom properties (variables) for colors, spacing, typography, and more.

### Color System

#### Design System Colors (Recommended)

The modern design system colors with both light and dark mode support:

```css
/* Gray Scale (100-1000) */
--ds-gray-100   /* Lightest gray */
--ds-gray-200
--ds-gray-300
--ds-gray-400
--ds-gray-500
--ds-gray-600
--ds-gray-700
--ds-gray-800
--ds-gray-900
--ds-gray-1000  /* Darkest gray / near black */

/* Blue */
--ds-blue-100   /* Lightest blue */
--ds-blue-200
--ds-blue-300
--ds-blue-400
--ds-blue-500
--ds-blue-600
--ds-blue-700   /* Primary blue */
--ds-blue-800
--ds-blue-900
--ds-blue-1000  /* Darkest blue */

/* Red */
--ds-red-100    /* Lightest red */
--ds-red-200
--ds-red-300
--ds-red-400
--ds-red-500
--ds-red-600
--ds-red-700    /* Error red */
--ds-red-800
--ds-red-900
--ds-red-1000   /* Darkest red */

/* Green */
--ds-green-100  /* Lightest green */
--ds-green-200
--ds-green-300
--ds-green-400
--ds-green-500
--ds-green-600
--ds-green-700  /* Success green */
--ds-green-800
--ds-green-900
--ds-green-1000 /* Darkest green */

/* Gray Alpha (with transparency) */
--ds-gray-alpha-100  /* rgba(0, 0, 0, 0.05) in light mode */
--ds-gray-alpha-200
--ds-gray-alpha-300
--ds-gray-alpha-400
--ds-gray-alpha-500
--ds-gray-alpha-600
--ds-gray-alpha-700
--ds-gray-alpha-800
--ds-gray-alpha-900
--ds-gray-alpha-1000 /* rgba(0, 0, 0, 0.91) in light mode */

/* Background */
--ds-background-100  /* Primary background (white in light, dark in dark) */
--ds-background-200  /* Secondary background */
```

#### Legacy Color System

```css
/* Accents (8-scale) */
--accents-1  /* #fafafa in light, #111111 in dark */
--accents-2  /* #eaeaea in light, #333333 in dark */
--accents-3  /* #999999 */
--accents-4  /* #888888 */
--accents-5  /* #666666 */
--accents-6  /* #444444 */
--accents-7  /* #333333 in light, #eaeaea in dark */
--accents-8  /* #111111 in light, #fafafa in dark */

/* Semantic Colors */
--geist-foreground  /* #000 in light, #fff in dark */
--geist-background  /* #fff in light, #000 in dark */
--geist-foreground-rgb  /* RGB values without 'rgb()' */
--geist-background-rgb  /* RGB values without 'rgb()' */

/* Success (Blue) */
--geist-success-lighter  /* #d3e5ff */
--geist-success-light    /* #3291ff */
--geist-success          /* #0070f3 */
--geist-success-dark     /* #0761d1 */

/* Error (Red) */
--geist-error-lighter  /* #f7d4d6 */
--geist-error-light    /* #ff1a1a */
--geist-error          /* #ee0000 */
--geist-error-dark     /* #c50000 */

/* Warning (Orange/Yellow) */
--geist-warning-lighter  /* #ffefcf */
--geist-warning-light    /* #f7b955 */
--geist-warning          /* #f5a623 */
--geist-warning-dark     /* #ab570a */

/* Violet (Purple) */
--geist-violet-lighter  /* #d8ccf1 */
--geist-violet-light    /* #8a63d2 */
--geist-violet          /* #7928ca */
--geist-violet-dark     /* #4c2889 */

/* Cyan */
--geist-cyan-lighter  /* #aaffec */
--geist-cyan-light    /* #79ffe1 */
--geist-cyan          /* #50e3c2 */
--geist-cyan-dark     /* #29bc9b */

/* Secondary (Gray aliases) */
--geist-secondary-lighter
--geist-secondary-light
--geist-secondary
--geist-secondary-dark

/* Special */
--geist-link-color     /* Link color (blue) */
--geist-selection      /* Text selection background */
--geist-selection-text-color
--geist-code           /* Code text color */
```

### Spacing System

```css
/* Base Spacing (4px scale) */
--geist-space: 4px --geist-space-2x: 8px --geist-space-3x: 12px
  --geist-space-4x: 16px --geist-space-6x: 24px --geist-space-8x: 32px
  --geist-space-10x: 40px --geist-space-16x: 64px --geist-space-24x: 96px
  --geist-space-32x: 128px --geist-space-48x: 192px --geist-space-64x: 256px
  /* Named Spacing */ --geist-space-small: 32px --geist-space-medium: 40px
  --geist-space-large: 48px /* Gap Spacing (for layouts) */
  --geist-gap-quarter: 8px --geist-gap-half: 12px --geist-gap: 24px
  --geist-gap-double: 48px --geist-gap-section: 32px
  /* Negative Spacing (for overlaps) */ --geist-space-negative: -4px
  --geist-space-2x-negative: -8px --geist-space-4x-negative: -16px
  /* ... all spacing values have negative counterparts */;
```

### Border Radius

```css
--geist-radius: 6px /* Default radius */ --geist-marketing-radius: 8px
  /* Marketing pages radius */;
```

### Typography

```css
/* Font Families */
--font-sans:
  'Geist Sans', var(--font-sans-fallback) --font-mono: 'Geist Mono',
  var(--font-mono-fallback) --font-sans-fallback: 'Inter', -apple-system,
  BlinkMacSystemFont, ... --font-mono-fallback: 'Roboto Mono', Menlo, Monaco,
  ... --font-space-grotesk: 'Space Grotesk',
  var(--font-sans) /* Form Typography */ --geist-form-font: 0.875rem /* 14px */
    --geist-form-line-height: 1.25rem /* 20px */ --geist-form-height: 40px
    --geist-form-large-font: 1rem /* 16px */
    --geist-form-large-line-height: 1.5rem --geist-form-large-height: 48px
    --geist-form-small-font: 0.875rem --geist-form-small-line-height: 0.875rem
    --geist-form-small-height: 32px;
```

### Shadows

```css
/* Legacy Shadows */
--shadow-smallest:
  0px 2px 4px rgba(0, 0, 0, 0.1) --shadow-extra-small: 0px 4px 8px
    rgba(0, 0, 0, 0.12) --shadow-small: 0 5px 10px rgba(0, 0, 0, 0.12)
    --shadow-medium: 0 8px 30px rgba(0, 0, 0, 0.12) --shadow-large: 0 30px 60px
    rgba(0, 0, 0, 0.12) --shadow-hover: 0 30px 60px rgba(0, 0, 0, 0.12)
    --shadow-sticky: 0 12px 10px -10px rgba(0, 0, 0, 0.12)
    /* Design System Shadows */ --ds-shadow-border: Border only shadow
    --ds-shadow-border-inset: Inset border shadow --ds-shadow-small: Subtle
    elevation --ds-shadow-border-small: Border + small shadow
    --ds-shadow-medium: Medium elevation --ds-shadow-border-medium: Border +
    medium shadow --ds-shadow-large: Large elevation
    --ds-shadow-border-large: Border + large shadow --ds-shadow-tooltip: Tooltip
    shadow --ds-shadow-menu: Menu/dropdown shadow --ds-shadow-modal: Modal
    dialog shadow --ds-shadow-fullscreen: Fullscreen overlay shadow
    /* Focus Ring */ --ds-focus-ring: 0 0 0 2px var(--ds-background-100),
  0 0 0 4px var(--ds-focus-color) --ds-focus-ring-outline: 2px solid
    var(--ds-focus-color) --ds-focus-color: var(--ds-blue-700) in light,
  var(--ds-blue-900) in dark;
```

### Layout

```css
/* Page Layout */
--geist-page-width: 1200px --geist-page-width-with-margin: calc(1200px + 48px)
  --geist-page-margin: 24px --ds-page-width: 1400px
  --ds-page-width-with-margin: calc(1400px + 48px) /* Header */
  --header-height: 64px --header-zindex: 75 --header-border-bottom: 0 1px 0 0
  rgba(0, 0, 0, 0.1) --header-sub-menu-height: 46px /* Footer */
  --footer-height: 0px /* Default, can be overridden */ /* Banner */
  --banner-height: 0px /* 40px when banner is shown */;
```

### Motion & Animation

```css
/* Motion Timing */
--ds-motion-timing-swift: cubic-bezier(0.175, 0.885, 0.32, 1.1)
  /* Overlay Motion */ --ds-motion-overlay-scale: 0.96
  --ds-motion-overlay-timing: var(--ds-motion-timing-swift)
  --ds-motion-overlay-duration: 300ms /* Popover Motion */
  --ds-motion-popover-timing: var(--ds-motion-timing-swift)
  --ds-motion-popover-duration: 200ms;
```

### Overlay

```css
--ds-overlay-backdrop-color: var(--ds-background-200)
  --ds-overlay-backdrop-opacity: 0.8;
```

### Gradients

```css
--geist-text-gradient: linear-gradient(
    180deg,
    rgba(0, 0, 0, 0.8) 0%,
    #000000 100%
  )
  /* Changes in dark mode to: linear-gradient(180deg, #ffffff 0%, rgba(255, 255, 255, 0.75) 100%) */
  /* Home Page Gradients (Light Mode) */ --develop-start-gradient: #007cf0
  --develop-end-gradient: #00dfd8 --develop-line-end: #019ae9
  --develop-text: #0a72ef --preview-start-gradient: #7928ca
  --preview-end-gradient: #ff0080 --preview-line-end: #9a1fb8
  --preview-text: #de1d8d --ship-start-gradient: #ff4d4d
  --ship-end-gradient: #f9cb28 --ship-line-end: #f9cb28 --ship-text: #ff5b4f;
```

### Console Colors

```css
--geist-console-header:
  #efe7ed in light, #0f0310 in dark --geist-console-purple: #7928ca in light,
  #8a63d2 in dark --geist-console-text-color-default: var(--geist-foreground)
    --geist-console-text-color-blue: #0070f3 in light,
  #3291ff in dark --geist-console-text-color-pink: #eb367f
    --geist-console-text-color-purple: #7928ca;
```

### Highlight Colors

```css
--geist-highlight-purple: #f81ce5 --geist-highlight-magenta: #eb367f
  --geist-highlight-pink: #ff0080 --geist-highlight-yellow: #fff500;
```

### Web Vitals Colors

```css
--wv-green: #0cce6b /* Good */ --wv-orange: #ffa400 /* Needs Improvement */
  --wv-red: #ff4e42 /* Poor */;
```

### Using Design Tokens

**In CSS:**

```css
.my-component {
  color: var(--ds-gray-900);
  background: var(--ds-background-100);
  border: 1px solid var(--ds-gray-alpha-200);
  padding: var(--geist-space-4x);
  gap: var(--geist-gap);
  border-radius: var(--geist-radius);
  box-shadow: var(--ds-shadow-small);
  font-family: var(--font-sans);
}
```

**In Tailwind:**

```tsx
<div className="text-[var(--ds-gray-900)] bg-[var(--ds-background-100)]" />
<div style={{ color: 'var(--ds-blue-700)' }} />
```

**Overriding Tokens:**

```css
:root {
  --geist-gap: 20px;
  --geist-radius: 8px;
  --geist-success: #00ff00;
}

.dark-theme {
  --geist-success: #00cc00;
}
```

### Quick Token Reference

**Text:** `--geist-foreground`, `--ds-gray-700` (secondary), `--ds-gray-600` (muted)

**Backgrounds:** `--ds-background-100` (primary), `--ds-background-200` (secondary), `--ds-gray-100` (subtle)

**Borders:** `--ds-gray-alpha-200` (default), `--ds-gray-alpha-100` (subtle)

**Semantic:** `--geist-success`, `--geist-error`, `--geist-warning`

## Animation & Transitions

### Built-in Animations

```tsx
// Loading states
<Button loading>Loading</Button>

// Skeleton animations
<Skeleton animate />

// Spinner
<Spinner />
```

### Custom Transitions

```tsx
<div className="transition-all duration-200 hover:scale-105">
  Animated element
</div>

<Button className="transform transition-transform hover:translate-y-[-2px]">
  Hover lift
</Button>
```

## Best Practices

### 1. Use Component Variants First

```tsx
// ✅ Good - Use built-in variant prop
<Button variant="error">Delete</Button>

// ❌ Avoid - Custom styling for standard variants
<Button className="bg-red-500">Delete</Button>
```

### 2. Leverage the `cn` Utility

```tsx
// ✅ Good - Handles conflicts properly
<Button className={cn('p-4', 'p-6')}>Button</Button>

// ❌ Avoid - Class conflicts
<Button className="p-4 p-6">Button</Button>
```

### 3. Keep Styles Maintainable

```tsx
// ✅ Good - Reusable, composed styles
const cardStyles = cn(
  'p-4 rounded-lg',
  'bg-background-100 border border-gray-200',
  'hover:border-gray-300 transition-colors'
)

<div className={cardStyles}>Content</div>

// ❌ Avoid - Overly long className strings
<div className="p-4 rounded-lg bg-background-100 border border-gray-200 hover:border-gray-300 transition-colors shadow-sm hover:shadow-md">
  Content
</div>
```

### 4. Use CSS Modules for Complex Styles

```css
/* Button.module.css */
.gradientButton {
  @apply bg-gradient-to-r from-blue-500 to-purple-500;
  @apply hover:from-blue-600 hover:to-purple-600;
  @apply text-white font-semibold;
}
```

```tsx
import styles from './Button.module.css'

;<Button className={styles.gradientButton}>Gradient Button</Button>
```

### 5. Respect Accessibility

```tsx
// ✅ Good - Maintains focus styles
<Button className="focus:ring-2 focus:ring-blue-500">
  Accessible
</Button>

// ❌ Avoid - Removes focus indicators
<Button className="focus:outline-none">
  Not accessible
</Button>
```

## Debugging Styles

### Use Browser DevTools

1. Inspect the element
2. Check computed styles
3. Look for CSS custom properties
4. Check Tailwind classes are applied

### Common Issues

```tsx
// Issue: Tailwind classes not applying
// Solution: Ensure component path is in Tailwind config content array

// Issue: Custom styles overridden
// Solution: Use cn() to properly merge classes

// Issue: Dark mode not working
// Solution: Ensure GeistProvider with theme prop is wrapping your app
```

This guide covers all major styling approaches with Geist components.
[V0_FILE]markdown:file="docs/tailwind-integration.md"
# Tailwind CSS v4 Integration

Complete guide to using GeistCN Design System with Tailwind CSS v4.

## Overview

GeistCN uses **Tailwind CSS v4** with CSS-first configuration and **OKLCH colors** for wide gamut display support. The Tailwind config automatically maps all color classes to design tokens, ensuring:

- Automatic dark mode support
- Theme consistency
- Design system compliance
- Clean, readable code
- **P3 wide gamut color support** via OKLCH

## Setup

### 1. Install Dependencies

```bash
pnpm add -D tailwindcss@^4.1 @tailwindcss/postcss
```

### 2. Import GeistCN's Tailwind Theme

GeistCN provides a pre-configured `tailwind.css` with all theme tokens:

```tsx
// app/layout.tsx or app/globals.css
import '@vercel/geistcn/tailwind.css'
import '@vercel/geistcn/styles.css'
import { GeistProvider } from '@vercel/geistcn/core/provider'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <GeistProvider>{children}</GeistProvider>
      </body>
    </html>
  )
}
```

### 3. PostCSS Config

```js
// postcss.config.mjs
export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
}
```

Or use GeistCN's preconfigured PostCSS:

```js
// postcss.config.mjs
export default require('@vercel/geistcn/config/postcss')
```

## OKLCH Color System

GeistCN uses **OKLCH** (Oklab Lightness Chroma Hue) colors for better perceptual uniformity and P3 wide gamut display support.

### Why OKLCH?

| HSL (traditional)         | OKLCH (GeistCN)           |
| ------------------------- | ------------------------- |
| Perceptually inconsistent | Perceptually uniform      |
| sRGB only                 | P3 wide gamut support     |
| Less accurate gradients   | Smooth, natural gradients |

### Color Format

```css
/* GeistCN uses OKLCH values */
--ds-gray-100: oklch(0.961 0 0);
--ds-blue-700: oklch(57.61% 0.2508 258.23);
--ds-red-700: oklch(62.56% 0.2524 23.03);
```

## Color Classes

### Gray Scale (100-1000)

All gray classes are mapped to design tokens and support dark mode:

```tsx
// Text colors
<p className="text-gray-100">Lightest gray text</p>
<p className="text-gray-600">Muted text</p>
<p className="text-gray-900">Secondary text</p>
<p className="text-gray-1000">Primary text (darkest)</p>

// Background colors
<div className="bg-gray-100">Light gray background</div>
<div className="bg-gray-200">Subtle background</div>
<div className="bg-gray-300">Medium background</div>

// Border colors
<div className="border-gray-200">Light border</div>
<div className="border-gray-400">Medium border</div>
<div className="border-gray-600">Dark border</div>

// Gray alpha (transparent)
<div className="border-gray-alpha-200">Subtle transparent border</div>
<div className="bg-gray-alpha-100">Subtle transparent background</div>
```

**Mapped to:** `var(--ds-gray-XXX)` (OKLCH values)

### Background Colors

```tsx
<div className="bg-background-100">Primary background (white in light, dark in dark)</div>
<div className="bg-background-200">Secondary background</div>
```

**Mapped to:** `var(--ds-background-XXX)`

### Semantic Colors

#### Blue

```tsx
<div className="bg-blue-100">Lightest blue</div>
<div className="bg-blue-700">Primary blue</div>
<div className="bg-blue-900">Bright blue (dark mode)</div>
<div className="text-blue-700">Blue text</div>
<div className="border-blue-700">Blue border</div>
```

#### Red (Error)

```tsx
<div className="bg-red-100">Lightest red</div>
<div className="bg-red-700">Error red</div>
<div className="text-red-700">Error text</div>
<Badge className="bg-red-100 text-red-900">Error badge</Badge>
```

#### Green (Success)

```tsx
<div className="bg-green-100">Lightest green</div>
<div className="bg-green-700">Success green</div>
<div className="text-green-700">Success text</div>
<Badge className="bg-green-100 text-green-900">Success badge</Badge>
```

#### Other Colors

- **Amber:** `bg-amber-{100-1000}`, `text-amber-{100-1000}`
- **Purple:** `bg-purple-{100-1000}`, `text-purple-{100-1000}`
- **Pink:** `bg-pink-{100-1000}`, `text-pink-{100-1000}`
- **Teal:** `bg-teal-{100-1000}`, `text-teal-{100-1000}`

### Special Color Aliases

```tsx
<div className="bg-black">Maps to --ds-black (oklch(0 0 0))</div>
<div className="bg-white">Maps to --ds-white (oklch(1 0 0))</div>
```

## Custom Variants

GeistCN provides custom Tailwind variants for theme-specific styling:

```tsx
// Style only in dark theme
<div className="dark-theme:bg-gray-200">Dark theme only background</div>

// Style only in light theme
<div className="light-theme:border-gray-300">Light theme only border</div>
```

These are defined in the tailwind.css:

```css
@custom-variant dark-theme (&:where(.dark-theme, .dark-theme *));
@custom-variant light-theme (&:where(.light-theme, .light-theme *));
```

## Box Shadows

All shadows are mapped to design system tokens:

```tsx
<div className="shadow-2xs">Extra extra small shadow</div>
<div className="shadow-xs">Extra small shadow</div>
<div className="shadow-sm">Small shadow</div>
<div className="shadow-md">Medium shadow</div>
<div className="shadow-lg">Large shadow</div>
<div className="shadow-xl">Extra large shadow</div>
<div className="shadow-2xl">2XL shadow</div>
<div className="shadow-border">Border shadow</div>
```

**Mapped to:** Design system shadow tokens (`--ds-shadow-*`)

## Border Radius

```tsx
<div className="rounded-xs">2px radius</div>
<div className="rounded-sm">4px radius</div>
<div className="rounded-md">6px radius (default)</div>
<div className="rounded-lg">8px radius</div>
<div className="rounded-xl">12px radius</div>
<div className="rounded-2xl">16px radius</div>
<div className="rounded-full">Full radius (pills)</div>
```

## Breakpoints

GeistCN uses custom breakpoints:

```tsx
<div className="sm:flex">/* 401px+ */</div>
<div className="md:flex">/* 601px+ */</div>
<div className="lg:flex">/* 961px+ */</div>
<div className="xl:flex">/* 1200px+ */</div>
<div className="2xl:flex">/* 1400px+ */</div>
```

## Spacing

GeistCN uses Tailwind's default spacing scale (4px based) via `--spacing`:

```tsx
<div className="p-4">16px padding</div>
<div className="m-6">24px margin</div>
<div className="gap-4">16px gap</div>
<div className="space-y-2">8px vertical spacing</div>
```

## Real-World Examples

### Card with Hover Effect

```tsx
<div className="bg-background-100 border border-gray-200 rounded-lg p-4 hover:border-gray-300 transition-colors">
  <h3 className="text-xl font-semibold text-gray-1000 mb-2">Card Title</h3>
  <p className="text-sm text-gray-700">Card description</p>
</div>
```

### Form Input Group

```tsx
import { Input } from '@vercel/geistcn/components/input'
import { Button } from '@vercel/geistcn/components/button'

;<div className="space-y-4">
  <div>
    <label className="text-sm font-medium text-gray-900 mb-1 block">
      Email
    </label>
    <Input type="email" className="w-full" />
  </div>
  <div>
    <label className="text-sm font-medium text-gray-900 mb-1 block">
      Password
    </label>
    <Input type="password" className="w-full" />
  </div>
  <Button variant="primary" className="w-full">
    Sign In
  </Button>
</div>
```

### Status Badge

```tsx
import { Badge } from '@vercel/geistcn/components/badge'

;<div className="flex items-center gap-2">
  <span className="text-sm text-gray-900">Status:</span>
  <Badge variant="success" className="bg-green-100 text-green-900">
    Active
  </Badge>
</div>
```

### Data Table Row

```tsx
<div className="bg-background-100 border-b border-gray-alpha-200 px-4 py-3 hover:bg-gray-100">
  <div className="flex items-center justify-between">
    <span className="text-sm text-gray-1000">{item.name}</span>
    <Badge variant="default" className="text-gray-700">
      {item.status}
    </Badge>
  </div>
</div>
```

## Available Tailwind Colors

All these classes are available and mapped to OKLCH design tokens:

```tsx
// Complete color scale (all support dark mode)
gray-{100, 200, 300, 400, 500, 600, 700, 800, 900, 1000}
blue-{100, 200, 300, 400, 500, 600, 700, 800, 900, 1000}
red-{100, 200, 300, 400, 500, 600, 700, 800, 900, 1000}
green-{100, 200, 300, 400, 500, 600, 700, 800, 900, 1000}
amber-{100, 200, 300, 400, 500, 600, 700, 800, 900, 1000}
purple-{100, 200, 300, 400, 500, 600, 700, 800, 900, 1000}
pink-{100, 200, 300, 400, 500, 600, 700, 800, 900, 1000}
teal-{100, 200, 300, 400, 500, 600, 700, 800, 900, 1000}

// Alpha variants (transparent)
gray-alpha-{100, 200, 300, 400, 500, 600, 700, 800, 900, 1000}

// Background
background-{100, 200}

// Special
black, white
```

## Color Usage Guidelines

### Text Colors

```tsx
text - gray - 1000 // Primary text
text - gray - 900 // Secondary text
text - gray - 700 // Tertiary text
text - gray - 600 // Muted text
text - gray - 500 // Disabled text
```

### Background Colors

```tsx
bg - background - 100 // Primary background (page)
bg - background - 200 // Secondary background (cards)
bg - gray - 100 // Subtle background (hover states)
bg - gray - 200 // Medium background
```

### Border Colors

```tsx
border - gray - 200 // Default border
border - gray - alpha - 200 // Subtle transparent border (recommended for dark mode)
border - gray - alpha - 400 // Medium transparent border
border - gray - 300 // Medium solid border
```

## Best Practices

### Use Tailwind Classes for GeistCN Tokens

```tsx
// CORRECT - Clean and theme-aware
<div className="bg-background-100 text-gray-900 border-gray-200">

// AVOID - Verbose and harder to read
<div className="bg-[var(--ds-background-100)] text-[var(--ds-gray-900)] border-[var(--ds-gray-200)]">
```

### Use Component Variants First

```tsx
// BEST - Use component API
<Button variant="error">Delete</Button>

// OK - Tailwind for custom styling
<Button className="bg-gradient-to-r from-blue-700 to-purple-700">
  Custom
</Button>

// AVOID - Recreating standard variants
<Button className="bg-red-700 text-white">Delete</Button>
```

### Prefer Alpha Borders for Dark Mode

```tsx
// BETTER - Works better in dark mode
<div className="border border-gray-alpha-200">

// OK - Solid border
<div className="border border-gray-200">
```

## Dark Mode

All Tailwind classes automatically support dark mode through GeistCN's design tokens:

```tsx
// Single className - works in both light and dark
<div className="bg-background-100 text-gray-900 border-gray-200">
  Automatically adapts to dark mode
</div>

// No need for dark: prefix
// NOT NEEDED
<div className="bg-white dark:bg-black">

// AUTOMATIC via design tokens
<div className="bg-background-100">
```

## Complete Example

```tsx
'use client'

import { useState } from 'react'
import { Button } from '@vercel/geistcn/components/button'
import { Input } from '@vercel/geistcn/components/input'
import { Badge } from '@vercel/geistcn/components/badge'
import { Icon } from '@vercel/geistcn/icon'

export function Dashboard() {
  const [search, setSearch] = useState('')

return (
    <div className="min-h-screen bg-background-100">
      {/* Header */}
      <header className="border-b border-gray-alpha-200 bg-background-100">
        <div className="max-w-7xl mx-auto px-6 py-4">
          <h1 className="text-2xl font-semibold text-gray-1000">Dashboard</h1>
          <p className="text-sm text-gray-700">
            Manage your projects and deployments
          </p>
        </div>
      </header>

{/* Main */}
      <main className="max-w-7xl mx-auto px-6 py-8">
        {/* Search */}
        <div className="flex items-center gap-4 mb-6">
          <div className="relative flex-1 max-w-md">
            <Icon
              name="magnifying-glass"
              className="absolute left-3 top-1/2 -translate-y-1/2 text-gray-600"
            />
            <Input
              placeholder="Search..."
              value={search}
              onChange={(e) => setSearch(e.target.value)}
              className="pl-10 w-full"
            />
          </div>
          <Button variant="secondary" prefix={<Icon name="filter" />}>
            Filters
          </Button>
        </div>

{/* Content Grid */}
        <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
          {items.map((item) => (
            <div
              key={item.id}
              className="bg-background-100 border border-gray-200 rounded-lg p-4 hover:border-gray-300 transition-colors"
            >
              <div className="flex items-start justify-between mb-3">
                <h3 className="font-medium text-gray-1000">{item.name}</h3>
                <Badge
                  variant={item.status === 'active' ? 'success' : 'default'}
                >
                  {item.status}
                </Badge>
              </div>
              <p className="text-sm text-gray-700 mb-4">{item.description}</p>
              <div className="flex items-center gap-2">
                <Button variant="primary" size="small">
                  View
                </Button>
                <Button variant="secondary" size="small">
                  Edit
                </Button>
              </div>
            </div>
          ))}
        </div>
      </main>
    </div>
  )
}
```

## Summary

**DO:**

- Use Tailwind classes: `bg-gray-200`, `text-gray-900`, `border-gray-200`
- Let GeistCN's Tailwind config handle dark mode automatically
- Use OKLCH colors for gradients and custom colors

**DON'T:**

- Use arbitrary values: `bg-[var(--ds-gray-200)]` (verbose)
- Use hardcoded hex colors: `bg-[#eaeaea]` (not theme-aware)
- Use `dark:` prefix (GeistCN handles this automatically)
- Recreate component variants with custom classes

The key insight: **GeistCN's Tailwind v4 config makes OKLCH design tokens available as clean, readable Tailwind classes with automatic dark mode support.**
[V0_FILE]markdown:file="docs/typescript-guide.md"
# TypeScript Guide

Complete guide to using Geist with TypeScript, including types, patterns, and best practices.

## Type Safety

Geist is written in TypeScript and exports full type definitions. No additional `@types` packages needed.

## Component Props

### Importing Component Types

// Use in your components
const MyButton: React.FC<ButtonProps> = (props) => {
  return <Button {...props} />
}
```

### Extending Component Props

```tsx
import type { ButtonProps } from '@vercel/geistcn/components/button'
import { Button } from '@vercel/geistcn/components/button'

interface CustomButtonProps extends ButtonProps {
  customProp: string
  onCustomClick?: () => void
}

export function CustomButton({
  customProp,
  onCustomClick,
  ...buttonProps
}: CustomButtonProps) {
  return (
    <Button onClick={onCustomClick} {...buttonProps}>
      {customProp}
    </Button>
  )
}
```

### Generic Component Props

```tsx
import { Button } from '@vercel/geistcn/components/button'

// Get props type from component
type ButtonProps = React.ComponentProps<typeof Button>

// Or using ComponentPropsWithoutRef
type ButtonPropsNoRef = React.ComponentPropsWithoutRef<typeof Button>

// With ref
type ButtonPropsWithRef = React.ComponentPropsWithRef<typeof Button>
```

## Hook Types

### Toast Hook Types

```tsx
import type { ToastsHook, Message } from '@vercel/geistcn/components/toast'
import { useToasts } from '@vercel/geistcn/components/toast'

function MyComponent() {
  const toasts: ToastsHook = useToasts()

const showToast = (message: Message) => {
    toasts.message(message)
  }

// Type-safe message object
  const message: Message = {
    text: 'Success!',
    type: 'success',
    delay: 3000,
  }
}
```

### Menu Hook Types

```tsx
import { useMenu } from '@vercel/geistcn/components/menu'

function MyMenu() {
  const { visible, setVisible, bindings } = useMenu()

// All typed automatically
}
```

### Custom Hook with Geist Types

```tsx
import type { ButtonProps } from '@vercel/geistcn/components/button'
import { useState } from 'react'

function useButtonState(initialType: ButtonProps['type'] = 'primary') {
  const [type, setType] = useState<ButtonProps['type']>(initialType)
  const [loading, setLoading] = useState(false)

return { type, setType, loading, setLoading }
}
```

## Icon Types

### Icon Component Types

```tsx
import type { IconProps } from '@vercel/geistcn/icons'
import { ArrowRight } from '@vercel/geistcn/icons/arrow-right'

// Extend icon props
interface CustomIconProps extends IconProps {
  isActive?: boolean
}

function CustomIcon({ isActive, ...iconProps }: CustomIconProps) {
  return <ArrowRight {...iconProps} color={isActive ? 'blue' : 'gray'} />
}
```

### Dynamic Icon Loading

```tsx
import type { FC } from 'react'
import type { IconProps } from '@vercel/geistcn/icons'

type IconComponent = FC<IconProps>

async function loadIcon(name: string): Promise<IconComponent> {
  const icon = await import(`@vercel/geistcn/icons/${name}`)
  return icon.default
}
```

## Utility Types

### Using General Types

```tsx
import type { ComponentProps, ColorType, SizeType } from '@vercel/geistcn/types'

interface MyComponentProps {
  color?: ColorType
  size?: SizeType
}
```

### Calendar Types

```tsx
import type {
  CalendarProps,
  DateValue,
  Preset,
} from '@vercel/geistcn/components/calendar'

const presets: Preset[] = [
  {
    label: 'Today',
    value: new Date(),
  },
  {
    label: 'Tomorrow',
    value: new Date(Date.now() + 86400000),
  },
]

function MyCalendar(props: CalendarProps) {
  const handleChange = (date: DateValue) => {
    console.log(date)
  }

return <Calendar {...props} onChange={handleChange} />
}
```

### Table Types

```tsx
import type {
  TableProps,
  TableRowProps,
  TableCellProps,
} from '@vercel/geistcn/components/table'

interface User {
  id: string
  name: string
  email: string
}

function UserTable({ users }: { users: User[] }) {
  return (
    <Table>
      {users.map((user) => (
        <TableRow key={user.id}>
          <TableCell>{user.name}</TableCell>
          <TableCell>{user.email}</TableCell>
        </TableRow>
      ))}
    </Table>
  )
}
```

## Polymorphic Components

### Creating Polymorphic Components

```tsx
import type { ElementType, ComponentPropsWithoutRef } from 'react'

type PolymorphicProps<E extends ElementType> = {
  as?: E
} & ComponentPropsWithoutRef<E>

function PolymorphicButton<E extends ElementType = 'button'>({
  as,
  ...props
}: PolymorphicProps<E>) {
  const Component = as || 'button'
  return <Component {...props} />
}

// Usage
<PolymorphicButton as="a" href="/link">Link Button</PolymorphicButton>
<PolymorphicButton as="button" type="submit">Form Button</PolymorphicButton>
```

## ForwardRef with Types

### Typed ForwardRef Component

```tsx
import { forwardRef } from '@vercel/geistcn/utils/forward-ref'
import type { ButtonProps } from '@vercel/geistcn/components/button'
import { Button } from '@vercel/geistcn/components/button'

interface CustomButtonProps extends ButtonProps {
  variant?: 'default' | 'custom'
}

export const CustomButton = forwardRef<
  HTMLButtonElement,
  CustomButtonProps
>(({ variant = 'default', ...props }, ref) => {
  return <Button ref={ref} {...props} />
})

// Usage with ref
const buttonRef = useRef<HTMLButtonElement>(null)
<CustomButton ref={buttonRef} variant="custom" />
```

## Generic Components

### Generic List Component

```tsx
import { Card } from '@vercel/geistcn/components/card'

interface ListProps<T> {
  items: T[]
  renderItem: (item: T) => React.ReactNode
  keyExtractor: (item: T) => string
}

function List<T>({ items, renderItem, keyExtractor }: ListProps<T>) {
  return (
    <>
      {items.map((item) => (
        <Card key={keyExtractor(item)}>{renderItem(item)}</Card>
      ))}
    </>
  )
}

// Usage
interface User {
  id: string
  name: string
}

;<List<User>
  items={users}
  renderItem={(user) => <div>{user.name}</div>}
  keyExtractor={(user) => user.id}
/>
```

## Form Types

### Typed Form Component

```tsx
import type { FormEvent } from 'react'
import { Input } from '@vercel/geistcn/components/input'
import { Button } from '@vercel/geistcn/components/button'
import { Fieldset } from '@vercel/geistcn/components/fieldset'

interface FormData {
  name: string
  email: string
  message: string
}

interface ContactFormProps {
  onSubmit: (data: FormData) => void | Promise<void>
}

export function ContactForm({ onSubmit }: ContactFormProps) {
  const handleSubmit = async (e: FormEvent<HTMLFormElement>) => {
    e.preventDefault()
    const formData = new FormData(e.currentTarget)

const data: FormData = {
      name: formData.get('name') as string,
      email: formData.get('email') as string,
      message: formData.get('message') as string,
    }

await onSubmit(data)
  }

return (
    <form onSubmit={handleSubmit}>
      <Fieldset>
        <Input name="name" label="Name" required />
        <Input name="email" type="email" label="Email" required />
        <Textarea name="message" label="Message" required />
        <Button type="submit">Send</Button>
      </Fieldset>
    </form>
  )
}
```

## Event Handler Types

### Typed Event Handlers

```tsx
import type { MouseEvent, ChangeEvent } from 'react'
import { Button } from '@vercel/geistcn/components/button'
import { Input } from '@vercel/geistcn/components/input'

function MyComponent() {
  const handleClick = (e: MouseEvent<HTMLButtonElement>) => {
    console.log('Button clicked', e.currentTarget)
  }

const handleChange = (e: ChangeEvent<HTMLInputElement>) => {
    console.log('Value changed', e.target.value)
  }

return (
    <>
      <Button onClick={handleClick}>Click me</Button>
      <Input onChange={handleChange} />
    </>
  )
}
```

## Discriminated Unions

### Typed Component Variants

```tsx
import { Badge } from '@vercel/geistcn/components/badge'

type StatusBadgeProps =
  | { status: 'success'; message: string }
  | { status: 'error'; error: Error }
  | { status: 'loading' }

function StatusBadge(props: StatusBadgeProps) {
  switch (props.status) {
    case 'success':
      return <Badge type="success">{props.message}</Badge>
    case 'error':
      return <Badge type="error">{props.error.message}</Badge>
    case 'loading':
      return <Badge>Loading...</Badge>
  }
}
```

## Async Component Types

### Typed Server Components

```tsx
import { Card } from '@vercel/geistcn/components/card'

interface User {
  id: string
  name: string
}

async function UserList(): Promise<JSX.Element> {
  const users: User[] = await fetchUsers()

return (
    <>
      {users.map((user) => (
        <Card key={user.id}>{user.name}</Card>
      ))}
    </>
  )
}
```

## Utility Function Types

### Using Geist Utilities with Types

```tsx
import { cn } from '@vercel/geistcn/utils/cn'
import type { ClassValue } from 'clsx'

function getButtonClasses(...inputs: ClassValue[]): string {
  return cn('base-button-class', ...inputs)
}

// Usage
const classes = getButtonClasses('custom-class', { active: isActive })
```

## Type Guards

### Creating Type Guards for Geist

```tsx
import type { ButtonProps } from '@vercel/geistcn/components/button'

function isErrorButton(
  props: ButtonProps,
): props is ButtonProps & { type: 'error' } {
  return props.type === 'error'
}

function handleButton(props: ButtonProps) {
  if (isErrorButton(props)) {
    // TypeScript knows type is 'error' here
    console.log('Error button')
  }
}
```

## Module Augmentation

### Extending Geist Types

```tsx
// types/geist.d.ts
import '@vercel/geistcn/components/button'

declare module '@vercel/geistcn/components/button' {
  interface ButtonProps {
    customProp?: string
  }
}

// Now you can use customProp on Button
;<Button customProp="value">Click</Button>
```

## Best Practices

### 1. Always Import Types

```tsx
// ✅ Good
import type { ButtonProps } from '@vercel/geistcn/components/button'
import { Button } from '@vercel/geistcn/components/button'

// ❌ Avoid
import { Button, ButtonProps } from '@vercel/geistcn/components/button'
```

### 2. Use Type Inference

```tsx
// ✅ Good - Let TypeScript infer
const [value, setValue] = useState('')

// ❌ Unnecessary - Type is already inferred
const [value, setValue] = useState<string>('')
```

### 3. Define Interfaces for Props

```tsx
// ✅ Good - Clear and reusable
interface UserCardProps {
  user: User
  onEdit: (user: User) => void
}

// ❌ Avoid - Inline types are harder to reuse
function UserCard({
  user,
  onEdit,
}: {
  user: User
  onEdit: (user: User) => void
}) {}
```

### 4. Use Proper Ref Types

```tsx
// ✅ Good
const inputRef = useRef<HTMLInputElement>(null)

// ❌ Avoid
const inputRef = useRef<any>(null)
```

### 5. Type Component Children

```tsx
// ✅ Good
interface WrapperProps {
  children: React.ReactNode
}

// ❌ Too restrictive
interface WrapperProps {
  children: JSX.Element
}
```

## Common Patterns

### Conditional Props

```tsx
type ButtonWithLink = {
  href: string
  onClick?: never
}

type ButtonWithClick = {
  href?: never
  onClick: () => void
}

type ConditionalButtonProps = ButtonWithLink | ButtonWithClick

// Usage ensures href XOR onClick
<Button href="/link">Link</Button>
<Button onClick={() => {}}>Click</Button>
// Error: Can't have both
<Button href="/link" onClick={() => {}}>Invalid</Button>
```

### Render Props

```tsx
interface RenderProps<T> {
  data: T[]
  render: (item: T, index: number) => React.ReactNode
}

function DataList<T>({ data, render }: RenderProps<T>) {
  return <>{data.map((item, i) => render(item, i))}</>
}
```

This guide covers comprehensive TypeScript patterns for Geist components.
[V0_FILE]typescriptreact:file="app/page.tsx" isDeleted="true"
import { Input } from '@vercel/geistcn/components/input'
import { Button } from '@vercel/geistcn/components/button'

export default function Page() {
  return (
    <div className="flex min-h-screen items-center justify-center">
      <form className="w-full max-w-sm space-y-4">
        <h1 className="text-2xl font-semibold">Sign Up</h1>

<Button variant="default" size="medium" typeName="submit">
          Sign Up
        </Button>
      </form>
    </div>
  )
}e5:["$","$Lf3",null,{"chatId":"dgNKbdNtQsP","children":["$","$Lf4",null,{"data":{"@\"active-block\",\"dgNKbdNtQsP\",":{"id":"b_h31eeH5hWoU","messageId":"o2kicoFhG5FtEChB08D8MJ0FHGQZVsvq","source":"$f5","language":"typescriptreact","type":"code-project","closed":true,"meta":{"id":"Code","type":"code-project","project":"Code"},"hasSourceBeenEdited":false,"forkedFromBlockId":"$undefined"},"@\"chat:vm-mode\",\"dgNKbdNtQsP\",":true,"/chat/api/snapshots/proxy?blockId=b_h31eeH5hWoU&v=v2":null},"children":"$Lf6"}]}]
</article></body></html>

About

Tags

Share

About

Tags

Share

More from sahaj-jj

More Templates Like This

More from sahaj-jj

More Templates Like This