ui copilot-instructions.md

Copilot Instructions for Farsi UI

Project Overview

Farsi UI is a Persian/RTL-first component library inspired by shadcn/ui. It is not a packaged library but a copy-paste foundation for building RTL-aware React UIs. Key difference from shadcn/ui: everything is RTL-native from the start, not an afterthought.

• Stack: Next.js, React 18+, TypeScript, Tailwind CSS, Radix UI
• Distribution: Copy components into your project and customize them
• Philosophy: Full ownership, no lock-in, no hidden registry

Architecture & Project Structure

Core Directories

• components/ui/ – Reusable, primitive UI components (50+ components)
• components/docs/ – Documentation layout components (ComponentPreview, Header, Nav)
• components/theme-provider.tsx – Next-themes wrapper for dark mode
• app/docs/ – Next.js App Router documentation site
• hooks/ – Custom hooks (use-mobile, use-toast)
• lib/utils.ts – Central utility: cn() function (clsx + tailwind-merge)
• app/globals.css – Design tokens + Tailwind config (Moon Design System color naming)

Design Token System

Colors use Moon Design System naming (e.g., --piccolo, --hales, --bulma) mapped to semantic colors via CSS variables:

• --primary, --secondary, --destructive, --accent, etc.
• Variables use oklch() color space for better perceptual uniformity
• Dark mode variants prefixed with dark:

Critical Patterns

1. Component Structure

All UI components follow this pattern:

// 1. Use CVA (class-variance-authority) for variants
const componentVariants = cva("base-styles", {
  variants: {
    variant: { ... },
    size: { ... },
  },
  defaultVariants: { ... },
})

// 2. Accept component props + variant props + className
function Component({
  className,
  variant,
  size,
  asChild = false,
  ...props
}: React.ComponentProps<'element'> & VariantProps<typeof componentVariants> & { asChild?: boolean })

// 3. Use Slot if asChild=true (from @radix-ui/react-slot)
const Comp = asChild ? Slot : 'element'
return <Comp className={cn(componentVariants({ variant, size, className }))} {...props} />