Files

T

poyrazavsever cce7265fb1 docs: define self-hosted v3 migration baseline

2026-07-16 16:21:20 +03:00

49 KiB

Raw Blame History

Poyraz UI — AI Consumer Guide

Bu doküman, poyraz-ui paketini başka bir React/Next.js projesinde kullanmak isteyen bir geliştiricinin veya bir AI kod asistanının doğrudan okuyup doğru kararlar verebilmesi için hazırlanmıştır.

Amaç: Bir projede UI geliştirirken AI’a bu dosyayı verip “poyraz-ui kullanarak bu ekranı oluştur” dediğinizde, AI’ın doğru import path’lerini, doğru componentleri, doğru variantları, doğru tema yaklaşımını ve doğru tasarım dilini uygulaması.

Referans paket: poyraz-ui@3.0.2

1. AI için kısa talimat

Eğer bu dokümanı bir AI’a vereceksen, aşağıdaki bölümü prompt’un başına koyabilirsin:

Bu projede UI için poyraz-ui kullan.

Kurallar:
- React componentleri için `poyraz-ui/atoms`, `poyraz-ui/molecules`, `poyraz-ui/organisms` import path’lerini kullan.
- Global CSS’e `@import "poyraz-ui/preset.css";` eklenmiş kabul et; ekli değilse ekle.
- Gereksiz custom CSS yazma. Önce component variantlarını, radius/size/surface/appearance/effect prop’larını ve Tailwind utility classlarını kullan.
- Tasarım dili: minimal, soft, hafif rounded, clean border, mümkün olduğunda gölgesiz, dark-mode uyumlu, semantic token bazlı.
- Buttonlarda varsayılan hover motion için mümkünse `effect="swap"` kullan. Shine/fill/border-draw efektlerini yalnızca bilinçli vurgu için kullan.
- Form, overlay, dropdown, dialog, sheet, tabs, tooltip gibi davranışlı componentlerde poyraz-ui molecule componentlerini kullan; kendi headless implementation’ını yazma.
- Layout seviyesinde Navbar, Sidebar, Footer, AnnouncementBar ve DataTable gerekiyorsa `poyraz-ui/organisms` kullan.
- Componentleri erişilebilir şekilde kur: label/input ilişkisi, keyboard navigation, focus ring, aria-label, dialog title gibi gereklilikleri koru.

2. Poyraz UI nedir?

Poyraz UI; React, Tailwind CSS v4 ve Radix UI temelli, minimal ve soft-glass tasarım diline sahip bir component sistemidir.

Temel karakter:

Compact ve minimal görünüm
Clean border ağırlıklı yüzeyler
Gölge kullanımını minimumda tutan sade tasarım
Hafif rounded köşeler
Glass, soft, solid yüzey seçenekleri
Semantic token sistemi
Dark mode uyumu
Radix tabanlı erişilebilir primitives
Shadcn mantığına yakın source registry desteği
Npm paketi olarak merkezi kullanım
Atomic Design yapısı:
- Atoms
- Molecules
- Organisms
- Blocks/templates

3. Dağıtım modeli

Poyraz UI iki farklı kullanım modelini destekler.

3.1. Npm package kullanımı

Merkezi versiyon yönetimi, hızlı kurulum ve paket importları için kullanılır.

pnpm add poyraz-ui@3

import { Button, Card, Input } from "poyraz-ui/atoms";
import { Dialog, Tabs } from "poyraz-ui/molecules";
import { Navbar } from "poyraz-ui/organisms";

Bu modelde component kaynak kodu projenize kopyalanmaz. Paket güncellendikçe componentler merkezi olarak güncellenir.

3.2. Source registry kullanımı

Shadcn tarzı “component’i projeye kopyala, sahiplen ve özelleştir” modeli için kullanılır.

components.json içine registry namespace eklenir:

{
  "registries": {
    "@poyraz": "https://ui.poyrazavsever.com/r/{name}.json"
  }
}

Örnek component ekleme:

pnpm dlx shadcn@latest add @poyraz/button

Bu yaklaşımda component, projenizin configured aliases.ui klasörüne kopyalanır. Çok derin özelleştirme gerekiyorsa bu model tercih edilir.

AI’a tavsiye:

Proje hızlıca UI geliştirecekse npm package kullan.
Componentin kodu projede değiştirilecekse registry/source copy kullan.
Kullanıcı “shadcn gibi kopyalansın” derse source registry modelini öner.

4. Kurulum

4.1. Paket kurulumu

pnpm add poyraz-ui@3

Alternatifler:

npm install poyraz-ui@3
yarn add poyraz-ui@3

4.2. Peer dependencies

Zorunlu:

{
  "react": ">=18",
  "react-dom": ">=18",
  "tailwindcss": ">=4"
}

Opsiyonel:

react-hook-form — Form molecule için
@hookform/resolvers — schema resolver için
zod — form validation için
reactive-switcher — hazır theme objectleriyle dinamik tema için
mermaid — Mermaid molecule için

4.3. CSS kurulumu

Root global CSS dosyasına ekle:

@import "tailwindcss";
@import "poyraz-ui/preset.css";

Next.js App Router örneği:

// app/layout.tsx
import "./globals.css";

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

poyraz-ui/preset.css şunları sağlar:

Semantic color token bridge
Typography tokenları
Radius/token mapping
Motion keyframe ve animation utility’leri
Dark mode uyumlu CSS variable altyapısı
Componentlerin beklediği base CSS layer

Bu import yoksa componentler görsel olarak eksik, renksiz veya animasyonsuz görünebilir.

5. Import stratejisi

Önerilen import path’leri:

import { Button, Card, Input } from "poyraz-ui/atoms";
import { Dialog, DropdownMenu, Tabs } from "poyraz-ui/molecules";
import { Navbar, Sidebar, Footer } from "poyraz-ui/organisms";

Ana barrel de kullanılabilir:

import { Button, Dialog, Navbar } from "poyraz-ui";

Fakat AI için öneri:

Atom seviyesindeki componentleri poyraz-ui/atoms üzerinden import et.
Molecule seviyesindeki componentleri poyraz-ui/molecules üzerinden import et.
Layout ve büyük section componentlerini poyraz-ui/organisms üzerinden import et.
Theme objectleri gerekiyorsa poyraz-ui/themes kullan.

Theme import:

import { poyrazLightTheme, poyrazDarkTheme, poyrazThemes } from "poyraz-ui/themes";

Utility:

import { cn } from "poyraz-ui";

6. Tasarım dili

Poyraz UI’ın ana tasarım dili:

Minimal
Soft
Hafif rounded
Clean border
Glassy ama abartısız
Gölgesiz veya çok düşük gölgeli
Semantic token bazlı
Form elemanlarında net focus ring
Overlaylerde kontrollü blur/surface
Dark mode’da kontrastı koruyan yüzeyler

AI tasarım kararları:

Büyük gölgelerden kaçın.
Gereksiz custom border override yazma.
Kartlarda öncelikle variant="default", variant="glass", variant="soft" veya variant="outline" kullan.
Buttonlarda vurgu CTA için variant="default"; ikincil CTA için variant="secondary", variant="outline" veya variant="glass" kullan.
Radius için genellikle radius="sm" veya radius="md" tercih et.
Çok pill/rounded istenmedikçe radius="full" kullanma.
Interactive hover için önce componentin kendi variant/effect prop’larını kullan.

7. Tema ve token sistemi

Poyraz UI componentleri semantic Tailwind utility’leri ve CSS variable’ları üzerinden çalışır.

Sık kullanılan semantic utility’ler:

bg-background
bg-card
bg-muted
bg-primary
text-foreground
text-muted-foreground
text-primary
border-border
ring-ring

Custom tema yapılacaksa genellikle global CSS’te --poyraz-* variable’ları override edilir.

Örnek:

:root {
  --poyraz-primary: #dc2626;
  --poyraz-radius-md: 0.625rem;
}

.dark {
  --poyraz-background: #09090b;
  --poyraz-foreground: #fafafa;
}

AI için kural:

Hard-coded renkleri minimumda tut.
#dc2626 gibi brand renkleri yalnızca gerçekten brand vurgusu gerekiyorsa kullan.
Önce primary, muted, border, foreground, card tokenlarını kullan.

8. Motion sistemi

Poyraz UI motion sistemi CSS-only yaklaşımı tercih eder.

Button effect’leri:

<Button effect="none">Default</Button>
<Button effect="shine">Shine</Button>
<Button effect="fill" fillDirection="up">Fill</Button>
<Button effect="swap" swapTarget="both">Swap</Button>
<Button effect="border-draw">Border Draw</Button>

Button effect prop değerleri:

type ButtonEffect = "none" | "shine" | "fill" | "swap" | "border-draw";
type ButtonFillDirection = "right" | "left" | "up" | "down";
type ButtonSwapTarget = "icon" | "label" | "both";

AI için motion kuralı:

Standart CTA için effect="swap" kullan.
Shine efektini premium/brand vurgu için kullan.
Fill efektini güçlü hover dolum istenirse kullan.
Border-draw efektini outline butonlarda dekoratif vurgu için kullan.
Hareketleri erişilebilir tut; animasyonla bilgi verme.

Swap anatomy için önerilen yapı:

import { Button, ButtonIcon, ButtonLabel } from "poyraz-ui/atoms";

<Button effect="swap" swapTarget="both">
  <ButtonLabel>Devam et</ButtonLabel>
  <ButtonIcon>
    <ArrowRightIcon />
  </ButtonIcon>
</Button>

Not:

asChild kullanımı bazı durumlarda özel children yapılarıyla effect anatomy’sini bozabilir.
Swap effect’in net çalışması için ButtonLabel ve ButtonIcon doğrudan Button içinde kullanılmalıdır.

9. Atoms

Atoms, en küçük ve temel UI yapı taşlarıdır.

9.1. Button

Import:

import { Button, ButtonIcon, ButtonLabel } from "poyraz-ui/atoms";

Kullanım:

<Button>Kaydet</Button>

<Button variant="secondary" size="sm" radius="sm">
  İptal
</Button>

<Button effect="swap" swapTarget="both">
  <ButtonLabel>Detayları gör</ButtonLabel>
  <ButtonIcon>→</ButtonIcon>
</Button>

Variantlar:

default
secondary
outline
glass
destructive
soft
ghost
link

Size:

xs
sm
default
lg
icon-sm
icon
icon-lg

Radius:

none
xs
sm
md
lg
xl
2xl
full

Effect:

none
shine
fill
swap
border-draw

AI önerisi:

Primary CTA: variant="default" effect="swap"
Secondary CTA: variant="secondary" effect="swap"
Icon-only: size="icon" ve mutlaka aria-label
Loading durumunda loading prop kullan.

9.2. Badge

Import:

import { Badge } from "poyraz-ui/atoms";

Kullanım:

<Badge>Yeni</Badge>
<Badge variant="outline">Beta</Badge>
<Badge variant="success">Aktif</Badge>

Variantlar:

default
secondary
outline
glass
info
success
warning
destructive

Size:

sm
default
lg

Radius:

sm
md
full

AI önerisi:

Durum göstergelerinde success, warning, destructive, info
Kategori etiketlerinde outline veya secondary
Premium/soft yüzeylerde glass

9.3. Avatar

Import:

import { Avatar, AvatarImage, AvatarFallback } from "poyraz-ui/atoms";

Kullanım:

<Avatar size="lg" radius="full">
  <AvatarImage src="/avatar.png" alt="Poyraz Avsever" />
  <AvatarFallback>PA</AvatarFallback>
</Avatar>

Size:

xs
sm
default
lg
xl

Radius:

sm
md
lg
full

AI önerisi:

Kullanıcı profilinde radius="full"
Kurumsal logo/avatar gridlerinde radius="md" veya radius="lg"

9.4. Card

Import:

import {
  Card,
  CardHeader,
  CardTitle,
  CardDescription,
  CardContent,
  CardFooter,
  CardAction,
  CardImage,
} from "poyraz-ui/atoms";

Kullanım:

<Card variant="default" radius="md">
  <CardHeader>
    <CardTitle>Başlık</CardTitle>
    <CardDescription>Açıklama metni</CardDescription>
  </CardHeader>
  <CardContent>
    İçerik
  </CardContent>
  <CardFooter>
    Footer
  </CardFooter>
</Card>

Variantlar:

default
outline
glass
soft
ghost
elevated
interactive
bordered
highlight

Radius:

none
md
lg
xl
2xl

AI önerisi:

Genel layout kartı: variant="default"
Cam efektli dashboard: variant="glass"
Subtle info yüzeyi: variant="soft"
Clickable kart: variant="interactive"
Gölge istenmiyorsa elevated kullanma.

9.5. Card variants

Import:

import {
  BasicContentCard,
  ImageContentCard,
  HorizontalCard,
  ProfileCard,
  StatisticCard,
  PricingPlanCard,
  FeatureCard,
  GlassCard,
  InteractiveCard,
  ExpandableCard,
} from "poyraz-ui/atoms";

Kullanım amaçları:

BasicContentCard: başlık, açıklama, aksiyon butonu
ImageContentCard: üstte görsel, altta içerik
HorizontalCard: solda görsel, sağda içerik
ProfileCard: avatar, isim, rol, bio, sosyal aksiyonlar
StatisticCard: KPI/metrik kartı
PricingPlanCard: fiyat planı
FeatureCard: ikon + özellik başlığı + açıklama
GlassCard: glass yüzey kartı
InteractiveCard: hover/interaction odaklı kart
ExpandableCard: açılır/kapanır içerik kartı

AI önerisi:

Landing page feature grid için FeatureCard
Dashboard KPI için StatisticCard
Pricing ekranı için PricingPlanCard
Portfolio kişi kartı için ProfileCard

9.6. Input

Import:

import { Input, InputGroup, InputGroupAddon } from "poyraz-ui/atoms";

Kullanım:

<Input placeholder="E-posta" />

<InputGroup variant="glass" radius="md">
  <InputGroupAddon position="start">@</InputGroupAddon>
  <Input placeholder="kullanici" />
</InputGroup>

Field variantları:

default
glass
soft

Radius:

none
sm
md
lg
xl
full

AI önerisi:

Normal form alanı: variant="default"
Cam yüzeylerde: variant="glass"
Hafif arka planlı alanlarda: variant="soft"
Icon prefix/suffix için InputGroup + InputGroupAddon

9.7. Form Fields

Import:

import {
  NumberInput,
  MaskedInput,
  SearchInput,
  PhoneInput,
  PasswordInput,
  UrlInput,
  applyInputMask,
} from "poyraz-ui/atoms";

Kullanım:

<SearchInput placeholder="Ara..." onSearch={(value) => console.log(value)} />

<PhoneInput
  countryCode="+90"
  mask="### ### ## ##"
  onValueChange={(formatted, raw) => console.log(formatted, raw)}
/>

<UrlInput
  protocol="https://"
  onValueChange={(value, absoluteUrl) => console.log(absoluteUrl)}
/>

<PasswordInput placeholder="Şifre" />

<MaskedInput
  mask="##/##/####"
  placeholder="gg/aa/yyyy"
  onValueChange={(formatted, raw) => console.log(formatted, raw)}
/>

AI önerisi:

Search box için custom input yazma; SearchInput
Telefon için PhoneInput
URL için UrlInput
Şifre için PasswordInput
Basit maskeler için MaskedInput

9.8. Textarea

Import:

import { Textarea } from "poyraz-ui/atoms";

Kullanım:

<Textarea variant="soft" radius="md" placeholder="Mesajınız" />

Variantlar Input ile aynıdır:

default
glass
soft

9.9. Checkbox

Import:

import { Checkbox } from "poyraz-ui/atoms";

Kullanım:

<div className="flex items-center gap-2">
  <Checkbox id="terms" />
  <Label htmlFor="terms">Şartları kabul ediyorum</Label>
</div>

Radix tabanlıdır. Controlled veya uncontrolled kullanılabilir.

9.10. Radio Group

Import:

import { RadioGroup, RadioGroupItem } from "poyraz-ui/atoms";

Kullanım:

<RadioGroup defaultValue="monthly">
  <div className="flex items-center gap-2">
    <RadioGroupItem id="monthly" value="monthly" />
    <Label htmlFor="monthly">Aylık</Label>
  </div>
  <div className="flex items-center gap-2">
    <RadioGroupItem id="yearly" value="yearly" />
    <Label htmlFor="yearly">Yıllık</Label>
  </div>
</RadioGroup>

9.11. Switch

Import:

import { Switch } from "poyraz-ui/atoms";

Kullanım:

<Switch checked={enabled} onCheckedChange={setEnabled} />

AI önerisi:

Aç/kapat ayarlarında kullan.
Checkbox yerine boolean ayar toggle’larında tercih et.

9.12. Label

Import:

import { Label } from "poyraz-ui/atoms";

Kullanım:

<Label htmlFor="email">E-posta</Label>
<Input id="email" type="email" />

AI kuralı:

Form alanlarına her zaman label ekle.
Placeholder label’ın yerine geçmez.

9.13. Separator

Import:

import { Separator } from "poyraz-ui/atoms";

Kullanım:

<Separator />
<Separator orientation="vertical" />

9.14. Skeleton

Import:

import { Skeleton } from "poyraz-ui/atoms";

Kullanım:

<Skeleton className="h-8 w-48" />
<Skeleton className="h-32 rounded-md" />

AI önerisi:

Veri yüklenirken layout shift azaltmak için kullan.

9.15. Scroll Area

Import:

import { ScrollArea } from "poyraz-ui/atoms";

Kullanım:

<ScrollArea maxHeight={320} orientation="vertical">
  Uzun içerik
</ScrollArea>

Props:

maxHeight?: string | number
orientation?: "vertical" | "horizontal" | "both"
scrollbarSize?: "sm" | "md" | "lg"

9.16. Logo

Import:

import { Logo } from "poyraz-ui/atoms";

Kullanım:

<Logo src="/logo.png" alt="Brand" href="/" effect="shine-loop" radius="sm" />

Effect:

none
shine
shine-loop

AI önerisi:

Navbar’da avatar yerine logo gerekiyorsa Logo kullan.
Premium/brand hissi için effect="shine-loop" kullanılabilir.

9.17. Typography ve TextEffect

Import:

import { Typography, TextEffect } from "poyraz-ui/atoms";

Kullanım:

<Typography variant="h1" component="h1">
  Modern <TextEffect effect="shimmer" tone="primary">UI sistemi</TextEffect>
</Typography>

<Typography variant="p" className="text-muted-foreground">
  Açıklama metni
</Typography>

Typography variantları:

display
h1
h2
h3
h4
large
lead
p
body
small
caption
muted
blockquote
list

Font:

primary
secondary
inherit

TextEffect variantları:

none
marker
strike
outline
hand-drawn
contrast
shimmer
gradient
glow
boxed

Tone:

primary
neutral
warning

AI önerisi:

Heading’lerde Typography kullan.
Vurgulu kelimelerde custom span/CSS yerine TextEffect kullan.
Shiny gradient text için effect="shimmer" veya effect="gradient".
Elle çizilmiş underline hissi için effect="hand-drawn".
Marker vurgusu için effect="marker".
Hollow text için effect="outline".

9.18. Background Patterns

Import:

import {
  PatternDots,
  PatternGrid,
  PatternLines,
  PatternDiagonal,
  PatternCross,
  PatternCheckerboard,
  PatternDiamond,
  PatternZigzag,
  PatternDashedGrid,
  PatternRadial,
} from "poyraz-ui/atoms";

Kullanım:

<div className="relative overflow-hidden">
  <PatternDots overlay opacity={0.12} size={24} />
  <div className="relative z-10">İçerik</div>
</div>

Pattern props:

color?: string
opacity?: number
size?: number
overlay?: boolean

PatternRadial props:

from?: string
to?: string
opacity?: number
overlay?: boolean

AI önerisi:

Hero background veya empty state için kullan.
Pattern overlay ise parent relative overflow-hidden olmalı.

10. Molecules

Molecules, birkaç atomun birlikte oluşturduğu daha davranışlı UI parçalarıdır.

10.1. Accordion

Import:

import {
  Accordion,
  AccordionItem,
  AccordionTrigger,
  AccordionContent,
} from "poyraz-ui/molecules";

Kullanım:

<Accordion type="single" collapsible>
  <AccordionItem value="item-1" separated surface="soft" radius="md">
    <AccordionTrigger>Başlık</AccordionTrigger>
    <AccordionContent>İçerik</AccordionContent>
  </AccordionItem>
</Accordion>

AI önerisi:

FAQ, settings, detay aç/kapa için kullan.
Custom collapse state yazma; Radix props kullan.

10.2. Alert

Import:

import { Alert, AlertTitle, AlertDescription } from "poyraz-ui/molecules";

Kullanım:

<Alert variant="success" appearance="soft" radius="md" motion="slide">
  <AlertTitle>Başarılı</AlertTitle>
  <AlertDescription>Kayıt tamamlandı.</AlertDescription>
</Alert>

Variant:

default
info
success
warning
destructive

Appearance:

inline
outline
glass
soft
filled

Motion:

none
scale
fade
slide

Ek props:

icon?: ReactNode
dismissible?: boolean
onDismiss?: () => void
dismissLabel?: string

AI önerisi:

Inline bilgilendirme: appearance="inline"
Form/global feedback: appearance="soft" veya appearance="outline"
Kritik hata: variant="destructive"

Import:

import {
  Tooltip,
  TooltipTrigger,
  TooltipContent,
  TooltipProvider,
} from "poyraz-ui/molecules";

Kullanım:

<TooltipProvider>
  <Tooltip>
    <TooltipTrigger asChild>
      <Button size="icon" aria-label="Ayarlar">⚙</Button>
    </TooltipTrigger>
    <TooltipContent side="bottom" surface="soft" radius="sm">
      Ayarlar
    </TooltipContent>
  </Tooltip>
</TooltipProvider>

Surface:

solid
soft
glass

Radius:

none
sm
md
lg
xl

AI önerisi:

Icon-only butonlarda tooltip kullan.
Tooltip içeriğini kısa tut.

Import:

import { Popover, PopoverTrigger, PopoverContent } from "poyraz-ui/molecules";

Kullanım:

<Popover>
  <PopoverTrigger asChild>
    <Button>Filtre</Button>
  </PopoverTrigger>
  <PopoverContent surface="soft" radius="md" align="end">
    Filtre içeriği
  </PopoverContent>
</Popover>

AI önerisi:

Küçük floating panel için Popover.
Büyük panel gerekiyorsa Sheet veya Dialog.

Import:

import { HoverCard, HoverCardTrigger, HoverCardContent } from "poyraz-ui/molecules";

Kullanım:

<HoverCard>
  <HoverCardTrigger asChild>
    <a href="/profile">Poyraz</a>
  </HoverCardTrigger>
  <HoverCardContent surface="glass" radius="md">
    Profil özeti
  </HoverCardContent>
</HoverCard>

AI önerisi:

Profil preview, link preview, mini context kartları için kullan.

Import:

import {
  DropdownMenu,
  DropdownMenuTrigger,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuLabel,
  DropdownMenuSeparator,
  DropdownMenuCheckboxItem,
  DropdownMenuRadioGroup,
  DropdownMenuRadioItem,
  DropdownMenuShortcut,
} from "poyraz-ui/molecules";

Kullanım:

<DropdownMenu>
  <DropdownMenuTrigger asChild>
    <Button variant="outline">Menü</Button>
  </DropdownMenuTrigger>
  <DropdownMenuContent align="end" surface="solid" radius="md">
    <DropdownMenuLabel>Hesap</DropdownMenuLabel>
    <DropdownMenuItem interactiveMotion="shift">Profil</DropdownMenuItem>
    <DropdownMenuItem>Ayarlar</DropdownMenuItem>
    <DropdownMenuSeparator />
    <DropdownMenuItem>Çıkış</DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>

AI önerisi:

Click menu için DropdownMenu.
Hover-only mega menu gerekiyorsa Navbar organism altındaki menu parçalarını düşün.
Social dropdown gibi sade menülerde surface="solid" kullan.

10.7. Select

Import:

import {
  Select,
  SelectTrigger,
  SelectValue,
  SelectContent,
  SelectGroup,
  SelectLabel,
  SelectItem,
  SelectSeparator,
} from "poyraz-ui/molecules";

Kullanım:

<Select defaultValue="tr">
  <SelectTrigger>
    <SelectValue placeholder="Dil seç" />
  </SelectTrigger>
  <SelectContent surface="soft" radius="md">
    <SelectGroup>
      <SelectLabel>Diller</SelectLabel>
      <SelectItem value="tr">Türkçe</SelectItem>
      <SelectItem value="en">English</SelectItem>
    </SelectGroup>
  </SelectContent>
</Select>

AI önerisi:

Native select yerine bu componenti kullan.
Form içinde FormField ile birlikte kullanılabilir.

10.8. Dialog

Import:

import {
  Dialog,
  DialogTrigger,
  DialogContent,
  DialogHeader,
  DialogTitle,
  DialogDescription,
  DialogFooter,
  DialogClose,
} from "poyraz-ui/molecules";

Kullanım:

<Dialog>
  <DialogTrigger asChild>
    <Button>Dialog aç</Button>
  </DialogTrigger>
  <DialogContent surface="solid" radius="lg">
    <DialogHeader>
      <DialogTitle>Başlık</DialogTitle>
      <DialogDescription>Açıklama</DialogDescription>
    </DialogHeader>
    İçerik
    <DialogFooter>
      <DialogClose asChild>
        <Button variant="secondary">Kapat</Button>
      </DialogClose>
    </DialogFooter>
  </DialogContent>
</Dialog>

AI önerisi:

Kritik confirmation veya küçük modal akışlarında Dialog.
Her Dialog içinde görünür veya sr-only title bulundur.

Import:

import {
  Modal,
  ModalTrigger,
  ModalContent,
  ModalHeader,
  ModalTitle,
  ModalDescription,
  ModalFooter,
  ModalClose,
} from "poyraz-ui/molecules";

Modal, Dialog’a benzer fakat Poyraz UI’ın daha opinionated modal surface/size yaklaşımını sunar.

AI önerisi:

Uygulama içi custom modal tasarımları için Modal.
Radix-like standart kullanım için Dialog.

10.10. Sheet

Import:

import {
  Sheet,
  SheetTrigger,
  SheetContent,
  SheetHeader,
  SheetTitle,
  SheetDescription,
  SheetFooter,
  SheetClose,
} from "poyraz-ui/molecules";

Kullanım:

<Sheet>
  <SheetTrigger asChild>
    <Button>Detaylar</Button>
  </SheetTrigger>
  <SheetContent side="right" surface="solid" radius="md">
    <SheetHeader>
      <SheetTitle>Detaylar</SheetTitle>
      <SheetDescription>Ek bilgiler</SheetDescription>
    </SheetHeader>
  </SheetContent>
</Sheet>

AI önerisi:

Sağdan açılan ayar, filtre, detay paneli için Sheet.
Mobilde full-screen hissi gereken yan paneller için uygun.

10.11. Drawer

Import:

import {
  Drawer,
  DrawerTrigger,
  DrawerContent,
  DrawerHeader,
  DrawerTitle,
  DrawerDescription,
  DrawerFooter,
  DrawerClose,
} from "poyraz-ui/molecules";

Drawer vaul tabanlıdır.

AI önerisi:

Mobil bottom sheet davranışı için Drawer.
Desktop side panel için Sheet tercih et.

10.12. Command Palette

Import:

import {
  CommandPalette,
  CommandPaletteTrigger,
  CommandPaletteContent,
  CommandPaletteInput,
  CommandPaletteList,
  CommandPaletteGroup,
  CommandPaletteItem,
  CommandPaletteEmpty,
  CommandPaletteSeparator,
  CommandPaletteFooter,
  useCommandPalette,
} from "poyraz-ui/molecules";

Kullanım:

<CommandPalette>
  <CommandPaletteTrigger asChild>
    <Button variant="outline">Ara</Button>
  </CommandPaletteTrigger>
  <CommandPaletteContent>
    <CommandPaletteInput placeholder="Komut ara..." />
    <CommandPaletteList>
      <CommandPaletteEmpty>Sonuç yok.</CommandPaletteEmpty>
      <CommandPaletteGroup heading="Sayfalar">
        <CommandPaletteItem value="dashboard">Dashboard</CommandPaletteItem>
        <CommandPaletteItem value="settings">Ayarlar</CommandPaletteItem>
      </CommandPaletteGroup>
    </CommandPaletteList>
    <CommandPaletteFooter>⌘K ile aç</CommandPaletteFooter>
  </CommandPaletteContent>
</CommandPalette>

AI önerisi:

Global search/command menu için kullan.
Navbar search butonuna bağlanabilir.

10.13. Tabs

Import:

import { Tabs, TabsList, TabsTrigger, TabsContent } from "poyraz-ui/molecules";

Kullanım:

<Tabs defaultValue="overview">
  <TabsList>
    <TabsTrigger value="overview">Genel</TabsTrigger>
    <TabsTrigger value="settings">Ayarlar</TabsTrigger>
  </TabsList>
  <TabsContent value="overview">Genel içerik</TabsContent>
  <TabsContent value="settings">Ayarlar içeriği</TabsContent>
</Tabs>

AI önerisi:

Nav link görünümü için de Tabs yapısı kullanılabilir.
Sayfa içi section switching için uygundur.

Import:

import {
  Breadcrumb,
  BreadcrumbList,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbPage,
  BreadcrumbSeparator,
  BreadcrumbEllipsis,
} from "poyraz-ui/molecules";

Kullanım:

<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink href="/">Ana sayfa</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbPage>Projeler</BreadcrumbPage>
    </BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>

10.15. Pagination

Import:

import {
  Pagination,
  PaginationContent,
  PaginationItem,
  PaginationLink,
  PaginationPrevious,
  PaginationNext,
  PaginationEllipsis,
} from "poyraz-ui/molecules";

Kullanım:

<Pagination>
  <PaginationContent>
    <PaginationItem>
      <PaginationPrevious href="?page=1" />
    </PaginationItem>
    <PaginationItem>
      <PaginationLink href="?page=2" isActive>2</PaginationLink>
    </PaginationItem>
    <PaginationItem>
      <PaginationEllipsis />
    </PaginationItem>
    <PaginationItem>
      <PaginationNext href="?page=3" />
    </PaginationItem>
  </PaginationContent>
</Pagination>

10.16. Sonner / Toaster

Import:

import { Toaster, toast } from "poyraz-ui/molecules";

Root layout:

<body>
  {children}
  <Toaster />
</body>

Toast:

toast.success("Kaydedildi");
toast.error("Bir hata oluştu");
toast.promise(save(), {
  loading: "Kaydediliyor...",
  success: "Kaydedildi",
  error: "Kaydedilemedi",
});

AI önerisi:

Form submit sonrası global feedback için toast kullan.
Inline hata için Alert/FormMessage kullan.

10.17. Form

Import:

import {
  Form,
  FormField,
  FormItem,
  FormLabel,
  FormControl,
  FormDescription,
  FormMessage,
} from "poyraz-ui/molecules";

react-hook-form ile kullanılır.

Kullanım:

<Form {...form}>
  <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-4">
    <FormField
      control={form.control}
      name="email"
      render={({ field }) => (
        <FormItem>
          <FormLabel>E-posta</FormLabel>
          <FormControl>
            <Input type="email" placeholder="poyraz@example.com" {...field} />
          </FormControl>
          <FormDescription>İş e-postanı kullan.</FormDescription>
          <FormMessage />
        </FormItem>
      )}
    />
    <Button type="submit">Gönder</Button>
  </form>
</Form>

AI önerisi:

Validasyonlu formlarda bu yapı dışına çıkma.
FormMessage kullanarak hata mesajlarını erişilebilir yap.

10.18. Calendar

Import:

import { Calendar } from "poyraz-ui/molecules";

Kullanım:

<Calendar mode="single" selected={date} onSelect={setDate} />

Mode:

single
range

AI önerisi:

Inline takvim için Calendar.
Input ile açılan tarih seçimi için DatePicker.

10.19. Date Picker

Import:

import { DatePicker } from "poyraz-ui/molecules";

Kullanım:

<DatePicker value={date} onChange={setDate} placeholder="Tarih seç" />

AI önerisi:

Form tarih alanı için DatePicker kullan.

10.20. Autocomplete

Import:

import { Autocomplete } from "poyraz-ui/molecules";

Kullanım:

<Autocomplete
  options={[
    { value: "react", label: "React" },
    { value: "next", label: "Next.js", description: "React framework" },
  ]}
  placeholder="Teknoloji ara..."
/>

AI önerisi:

Select gibi ama arama/filter gerekiyorsa Autocomplete.

10.21. Mermaid

Import:

import { Mermaid } from "poyraz-ui/molecules";

Kullanım:

<Mermaid
  chart={`graph TD
    A[Start] --> B[Build]
    B --> C[Ship]
  `}
/>

Not:

mermaid peer dependency gerektirir.

10.22. Card Templates

Import:

import {
  ArticleCard,
  ImageCard,
  NewsCard,
  StatsCard,
  TestimonialCard,
  PricingCard,
  ProductCard,
  StarRating,
} from "poyraz-ui/molecules";

ArticleCard

Blog/article kartları için:

<ArticleCard
  title="Building with Poyraz UI"
  description="Soft glass component sistemi."
  image="/cover.png"
  category="Design"
  href="/blog/poyraz-ui"
/>

ImageCard

Görsel ağırlıklı proje/portfolio kartları için:

<ImageCard
  image="/project.png"
  title="Project Name"
  description="Kısa açıklama"
  badge="Web App"
  href="/projects/project-name"
/>

NewsCard

Yatay haber/post listeleri için:

<NewsCard
  image="/post.png"
  title="Yeni yazı"
  category="Blog"
  date="2026-07-16"
  href="/blog/new-post"
/>

StatsCard

Dashboard metrikleri için:

<StatsCard
  label="Aktif kullanıcı"
  value="24.6K"
  trend="up"
  trendValue="+12%"
/>

TestimonialCard

Referans/yorum kartı:

<TestimonialCard
  quote="Harika çalıştı."
  author="Ada Raimova"
  role="Founder"
  avatar="/ada.png"
  rating={5}
/>

PricingCard

Fiyatlandırma:

<PricingCard
  title="Pro"
  price="$19"
  period="/mo"
  features={["10 Projects", "Priority Support"]}
  action={<Button>Choose Plan</Button>}
/>

ProductCard

E-commerce ürün kartı:

<ProductCard
  title="Headphones"
  price="$99"
  image="/headphone.png"
  rating={4.8}
/>

StarRating

Yıldız rating:

<StarRating rating={4.5} />

AI önerisi:

Blog için ArticleCard veya NewsCard
Projeler için ImageCard
Dashboard KPI için StatsCard
Referanslar için TestimonialCard
Pricing sayfası için PricingCard
Ürün gridleri için ProductCard

11. Organisms

Organisms, kompleks layout ve app shell parçalarıdır.

Import:

import {
  Navbar,
  NavbarTopBar,
  NavbarTopBarSection,
  NavbarMain,
  NavbarBrand,
  NavbarLinks,
  NavbarLink,
  NavbarDropdown,
  NavbarDropdownTrigger,
  NavbarMegaMenu,
  NavbarMegaMenuLinks,
  NavbarMegaMenuFeatured,
  NavbarMegaMenuItem,
  NavbarPopoverDropdown,
  NavbarPopoverDropdownItem,
  NavbarPanelDropdown,
  NavbarPanelDropdownItem,
  NavbarActions,
  NavbarMobileToggle,
  NavbarMobileMenu,
  NavbarMobileLink,
  NavbarMobileGroup,
  NavbarMobileActions,
  NavbarMobileDropdown,
  NavbarMobileDrillMenu,
  NavbarMobileDrillTrigger,
  NavbarMobileDrillPanel,
  NavbarSearch,
  NavbarDivider,
} from "poyraz-ui/organisms";

Basit kullanım:

<Navbar variant="default">
  <NavbarMain>
    <NavbarBrand href="/" logo={<img src="/logo.png" alt="" />}>
      App
    </NavbarBrand>
    <NavbarLinks>
      <NavbarLink href="/docs">Docs</NavbarLink>
      <NavbarLink href="/components">Components</NavbarLink>
    </NavbarLinks>
    <NavbarActions>
      <NavbarSearch placeholder="Ara..." />
      <Button>Başla</Button>
    </NavbarActions>
  </NavbarMain>
</Navbar>

AI önerisi:

Ana site navbarı için Navbar organism kullan.
Logo için mümkünse Logo atom veya NavbarBrand kullan.
Linkler solda, actionlar sağda olacaksa NavbarMain içinde NavbarBrand + NavbarLinks + NavbarActions.
Mobil menü gerekiyorsa NavbarMobileToggle + NavbarMobileMenu.
Global search gerekiyorsa NavbarSearch veya CommandPalette ile birlikte kullan.

11.2. Sidebar

Import:

import {
  Sidebar,
  SidebarProvider,
  SidebarPanel,
  SidebarHeader,
  SidebarBranding,
  SidebarContent,
  SidebarGroup,
  SidebarGroupLabel,
  SidebarSection,
  SidebarMenu,
  SidebarMenuItem,
  SidebarMenuAction,
  SidebarSeparator,
  SidebarBadge,
  SidebarFooter,
  SidebarTrigger,
  SidebarRail,
  SidebarSearch,
  SidebarSubMenu,
  SidebarSubMenuItem,
  SidebarUserProfile,
} from "poyraz-ui/organisms";

Kullanım:

<SidebarProvider variant="collapsible">
  <Sidebar variant="collapsible">
    <SidebarPanel>
      <SidebarHeader>
        <SidebarBranding title="Dashboard" subtitle="Admin" />
      </SidebarHeader>
      <SidebarContent>
        <SidebarMenu>
          <SidebarMenuItem active href="/dashboard" icon={<HomeIcon />}>
            Dashboard
          </SidebarMenuItem>
          <SidebarMenuItem href="/settings" icon={<SettingsIcon />}>
            Settings
          </SidebarMenuItem>
        </SidebarMenu>
      </SidebarContent>
      <SidebarFooter>
        <SidebarUserProfile name="Poyraz" role="Developer" initials="PA" />
      </SidebarFooter>
    </SidebarPanel>
  </Sidebar>
</SidebarProvider>

Sidebar variantları:

default
collapsible
floating
mini
dark
bordered
inset

AI önerisi:

Dashboard layoutlarında SidebarProvider kullan.
Collapsible sidebar için variant="collapsible".
Compact icon sidebar için variant="mini".
Mobile drawer ihtiyacı için Sidebar mobile state veya Sheet ile kombinasyon.

11.3. Footer

Import:

import {
  Footer,
  FooterGrid,
  FooterSection,
  FooterHeading,
  FooterLink,
  FooterBrand,
  FooterSocials,
  FooterSocialLink,
  FooterDivider,
  FooterBottom,
  FooterBottomLinks,
  FooterDescription,
  FooterBadge,
  FooterLinkGroup,
  FooterCTA,
  FooterApp,
  FooterAppLink,
  FooterNewsletter,
} from "poyraz-ui/organisms";

Kullanım:

<Footer variant="minimal">
  <FooterGrid>
    <FooterBrand>
      <FooterHeading>Poyraz UI</FooterHeading>
      <FooterDescription>Soft glass component system.</FooterDescription>
    </FooterBrand>
    <FooterSection>
      <FooterHeading>Links</FooterHeading>
      <FooterLink href="/docs">Docs</FooterLink>
      <FooterLink href="/components">Components</FooterLink>
    </FooterSection>
  </FooterGrid>
  <FooterDivider />
  <FooterBottom>
    <span>© 2026</span>
    <FooterBottomLinks>
      <FooterLink href="/privacy">Privacy</FooterLink>
    </FooterBottomLinks>
  </FooterBottom>
</Footer>

Footer variantları:

minimal
compact
full
branded
centered
dark

AI önerisi:

Landing page footer: variant="minimal" veya variant="branded"
App footer: variant="compact"
Koyu section footer: variant="dark"

11.4. Announcement Bar

Import:

import { AnnouncementBar } from "poyraz-ui/organisms";

Kullanım:

<AnnouncementBar
  variant="branded"
  dismissible
  icon={<SparklesIcon />}
  action={<Button size="sm">İncele</Button>}
>
  Yeni sürüm yayında!
</AnnouncementBar>

Variantlar:

default
info
success
warning
branded
danger

AI önerisi:

Site-wide duyuru için kullan.
Dismiss state gerekiyorsa caller state yönetmeli veya kendi persistence hook’unu kullanmalı.

11.5. Data Table

Import:

import { DataTable, DataTableCore, type DataTableColumnDef } from "poyraz-ui/organisms";

Kullanım:

type User = {
  id: string;
  name: string;
  email: string;
  role: string;
};

const columns: DataTableColumnDef<User>[] = [
  { id: "name", header: "Name", accessorKey: "name", sortable: true },
  { id: "email", header: "Email", accessorKey: "email" },
  { id: "role", header: "Role", accessorKey: "role", filterable: true },
];

<DataTable
  columns={columns}
  data={users}
  getRowId={(row) => row.id}
  searchable
  selectable
  columnToggle
  pageSize={10}
  surface="solid"
  radius="md"
/>

DataTable props özeti:

columns
data
getRowId
pageSize
pagination
searchable
searchPlaceholder
selectable
onSelectionChange
columnToggle
className
caption
emptyMessage
loading
error
stickyHeader
tableMaxHeight
density
surface
radius
toolbar

Density:

compact
default
spacious

Surface:

solid
soft
glass

AI önerisi:

Basit tablo için DataTable.
Kendi pagination/search/sort yazma.
Daha kontrollü state gerekiyorsa DataTableCore kullan.

12. Blocks ve hazır template mantığı

Registry içinde ayrıca block/template yapıları bulunur. Bunlar npm export’larından ziyade source registry üzerinden projeye kopyalanması hedeflenen daha büyük UI parçalarıdır.

Blocks:

article-card
image-card
news-card
stats-card
testimonial-card
pricing-card
product-card
navigation-block
mobile-navigation-block
mega-menu-block
mobile-sidebar-block
footer-blocks
dashboard-shell-block
glass-app-shell-block
auth-card-block
pricing-block
brand-hero-block
smart-dashboard-block

AI önerisi:

Kullanıcı “tam section tasarla” derse block mantığını öner.
Kullanıcı npm package ile ilerliyorsa molecule/organism componentleriyle aynı section’ı elle oluştur.
Kullanıcı “source-owned olsun” derse shadcn registry komutuyla block eklemeyi öner.

Örnek:

pnpm dlx shadcn@latest add @poyraz/brand-hero-block
pnpm dlx shadcn@latest add @poyraz/dashboard-shell-block

13. Sık kullanılan layout reçeteleri

13.1. Landing hero

import { Button, ButtonIcon, ButtonLabel, Card, TextEffect, Typography } from "poyraz-ui/atoms";

export function Hero() {
  return (
    <section className="mx-auto grid max-w-6xl gap-8 px-6 py-16 lg:grid-cols-[1fr_420px]">
      <div className="flex flex-col justify-center gap-5">
        <Typography variant="display" component="h1">
          Modern <TextEffect effect="shimmer">soft UI</TextEffect> sistemi
        </Typography>
        <Typography variant="lead" className="text-muted-foreground">
          React projeleri için minimal, token bazlı ve erişilebilir componentler.
        </Typography>
        <div className="flex gap-3">
          <Button effect="swap" swapTarget="both">
            <ButtonLabel>Başla</ButtonLabel>
            <ButtonIcon>→</ButtonIcon>
          </Button>
          <Button variant="secondary" effect="swap" swapTarget="both">
            <ButtonLabel>Docs</ButtonLabel>
            <ButtonIcon>↗</ButtonIcon>
          </Button>
        </div>
      </div>

      <Card variant="glass" radius="xl" className="p-6">
        Preview
      </Card>
    </section>
  );
}

13.2. Dashboard card grid

import { StatsCard } from "poyraz-ui/molecules";

<div className="grid gap-4 md:grid-cols-2 xl:grid-cols-4">
  <StatsCard label="Revenue" value="$56,000" trend="up" trendValue="+12.5%" />
  <StatsCard label="Users" value="24,680" trend="up" trendValue="+8.2%" />
  <StatsCard label="Errors" value="12" trend="down" trendValue="-2.1%" />
  <StatsCard label="Conversion" value="3.46%" trend="neutral" />
</div>

13.3. Settings form

import { Button, Input, Switch, Label } from "poyraz-ui/atoms";
import { Card, CardContent, CardHeader, CardTitle } from "poyraz-ui/atoms";

<Card>
  <CardHeader>
    <CardTitle>Profil</CardTitle>
  </CardHeader>
  <CardContent className="space-y-4">
    <div className="space-y-2">
      <Label htmlFor="name">Ad</Label>
      <Input id="name" placeholder="Adınız" />
    </div>
    <div className="flex items-center justify-between">
      <Label htmlFor="notifications">Bildirimler</Label>
      <Switch id="notifications" />
    </div>
    <Button effect="swap">Kaydet</Button>
  </CardContent>
</Card>

13.4. Global search with Command Palette

import {
  CommandPalette,
  CommandPaletteTrigger,
  CommandPaletteContent,
  CommandPaletteInput,
  CommandPaletteList,
  CommandPaletteGroup,
  CommandPaletteItem,
  CommandPaletteEmpty,
} from "poyraz-ui/molecules";
import { Button } from "poyraz-ui/atoms";

<CommandPalette>
  <CommandPaletteTrigger asChild>
    <Button variant="outline">Search</Button>
  </CommandPaletteTrigger>
  <CommandPaletteContent>
    <CommandPaletteInput placeholder="Search docs..." />
    <CommandPaletteList>
      <CommandPaletteEmpty>No results.</CommandPaletteEmpty>
      <CommandPaletteGroup heading="Pages">
        <CommandPaletteItem value="docs">Docs</CommandPaletteItem>
        <CommandPaletteItem value="components">Components</CommandPaletteItem>
      </CommandPaletteGroup>
    </CommandPaletteList>
  </CommandPaletteContent>
</CommandPalette>

14. Erişilebilirlik kuralları

AI şu kurallara uymalı:

Icon-only buttonlarda aria-label ekle.
Dialog/Sheet/Modal içinde mutlaka Title kullan.
Form inputlarında Label kullan.
Placeholder’ı label yerine kullanma.
Toast ile kritik bilgiyi tek başına verme; gerekiyorsa inline feedback de göster.
Focus ring’i custom classlarla silme.
Dropdown/Select/Tabs gibi davranışlı elementlerde Radix tabanlı poyraz-ui componentlerini kullan.
Keyboard navigation’ı bozacak wrapper yapıları kurma.
Disabled/loading state’leri prop üzerinden ver.

15. AI için component seçme rehberi

Kullanıcı şunu isterse:

İstek	Kullanılacak component
Birincil aksiyon	`Button variant="default"`
İkincil aksiyon	`Button variant="secondary"` veya `outline`
Icon button	`Button size="icon"`
Sayfa başlığı	`Typography variant="h1"` veya `h2`
Vurgulu kelime	`TextEffect`
Form input	`Input`, `Textarea`, `Form`
Telefon/URL/şifre	`PhoneInput`, `UrlInput`, `PasswordInput`
Küçük durum etiketi	`Badge`
İçerik yüzeyi	`Card`
Glass panel	`Card variant="glass"` veya `GlassCard`
Dropdown aksiyon menüsü	`DropdownMenu`
Küçük floating panel	`Popover`
Tooltip açıklama	`Tooltip`
Büyük overlay/modal	`Dialog` veya `Modal`
Yan panel	`Sheet`
Mobil bottom drawer	`Drawer`
Global search	`CommandPalette`
Segmented nav	`Tabs`
Dashboard tablo	`DataTable`
App navbar	`Navbar`
Dashboard sidebar	`Sidebar`
Site footer	`Footer`
Duyuru barı	`AnnouncementBar`
Blog kartı	`ArticleCard` veya `NewsCard`
Proje kartı	`ImageCard`
Metrik kartı	`StatsCard`
Referans kartı	`TestimonialCard`
Fiyatlandırma	`PricingCard` veya `PricingPlanCard`

16. Kaçınılması gerekenler

AI şunları yapmamalı:

Poyraz UI componenti varken sıfırdan custom Dropdown/Dialog/Tabs yazmamalı.
div ile button gibi davranan element yapmamalı.
Focus outline/ring’i silmemeli.
Hard-coded dark/light renkleri çoğaltmamalı.
Çok fazla shadow eklememeli.
Buttonlarda swap/fill gibi effectler için custom CSS yazmamalı; prop kullanmalı.
Form validation mesajlarını sadece toast ile vermemeli.
asChild kullanırken Button effect anatomy’sini bozacak nested yapılar kurmamalı.
Component variantlarını bilmeden uydurmamalı; bu dokümandaki variant değerlerine bağlı kalmalı.

17. Başka projede kullanım için örnek AI prompt

Aşağıdaki prompt’u başka bir projede AI’a verebilirsin:

Bu projede poyraz-ui kullanarak UI geliştir.

Kurulum:
- Eğer yoksa `poyraz-ui@3` kur.
- Global CSS içinde `@import "poyraz-ui/preset.css";` olduğundan emin ol.

Import:
- Atoms: `poyraz-ui/atoms`
- Molecules: `poyraz-ui/molecules`
- Organisms: `poyraz-ui/organisms`

Tasarım dili:
- Minimal, soft, hafif rounded, clean border, gölgesiz veya çok düşük gölgeli.
- Semantic token kullan: `bg-background`, `text-foreground`, `text-muted-foreground`, `border-border`, `bg-card`, `text-primary`.
- Gereksiz custom CSS yazma.

Button:
- CTA butonlarında `effect="swap"` kullan.
- `ButtonLabel` ve `ButtonIcon` kullan.
- Icon-only buttonlarda aria-label ekle.

Form:
- Input için `Input`, `Textarea`, `PhoneInput`, `UrlInput`, `PasswordInput`, `SearchInput` kullan.
- Form validation varsa `Form`, `FormField`, `FormItem`, `FormLabel`, `FormControl`, `FormMessage` kullan.

Overlay:
- Dropdown için `DropdownMenu`
- Dialog/modal için `Dialog` veya `Modal`
- Yan panel için `Sheet`
- Mobil drawer için `Drawer`
- Global search için `CommandPalette`

Layout:
- Navbar için `Navbar`
- Sidebar için `Sidebar`
- Footer için `Footer`
- Duyuru için `AnnouncementBar`
- Tablo için `DataTable`

Her componenti erişilebilir ve responsive kur.

18. Minimal starter örneği

import "poyraz-ui/preset.css";

import { Button, ButtonIcon, ButtonLabel, Card, CardContent, Typography } from "poyraz-ui/atoms";
import { Tabs, TabsContent, TabsList, TabsTrigger } from "poyraz-ui/molecules";

export default function Page() {
  return (
    <main className="min-h-screen bg-background text-foreground">
      <section className="mx-auto max-w-5xl space-y-8 px-6 py-12">
        <div className="space-y-3">
          <Typography variant="h1" component="h1">
            Poyraz UI Starter
          </Typography>
          <Typography variant="lead" className="text-muted-foreground">
            Minimal, soft ve token bazlı React arayüzü.
          </Typography>
          <Button effect="swap" swapTarget="both">
            <ButtonLabel>Başla</ButtonLabel>
            <ButtonIcon>→</ButtonIcon>
          </Button>
        </div>

        <Card>
          <CardContent className="p-4">
            <Tabs defaultValue="one">
              <TabsList>
                <TabsTrigger value="one">Overview</TabsTrigger>
                <TabsTrigger value="two">Settings</TabsTrigger>
              </TabsList>
              <TabsContent value="one">Overview content</TabsContent>
              <TabsContent value="two">Settings content</TabsContent>
            </Tabs>
          </CardContent>
        </Card>
      </section>
    </main>
  );
}

19. Registry component adları

Source registry üzerinden eklenebilen component/block adları:

Atoms

avatar
badge
bg-pattern
button
card
checkbox
form-fields
input
label
logo
radio-group
scroll-area
separator
skeleton
switch
textarea
typography

Molecules

accordion
alert
autocomplete
breadcrumb
calendar
command-palette
date-picker
dialog
drawer
dropdown-menu
form
hover-card
mermaid
modal
pagination
popover
select
sheet
sonner
star-rating
tabs
tooltip

Organisms

announcement-bar
data-table
footer
navbar
sidebar

Blocks

article-card
auth-card-block
brand-hero-block
dashboard-shell-block
footer-blocks
glass-app-shell-block
image-card
mega-menu-block
mobile-navigation-block
mobile-sidebar-block
navigation-block
news-card
pricing-block
pricing-card
product-card
smart-dashboard-block
stats-card
testimonial-card

Registry install örneği:

pnpm dlx shadcn@latest add @poyraz/button
pnpm dlx shadcn@latest add @poyraz/dropdown-menu
pnpm dlx shadcn@latest add @poyraz/brand-hero-block

20. Son kontrol listesi

Başka projede poyraz-ui kullanırken AI şu checklist’i uygulamalı:

poyraz-ui@3 kurulu mu?
@import "poyraz-ui/preset.css"; global CSS’te var mı?
Componentler doğru entry point’ten import ediliyor mu?
Tasarım semantic tokenlarla mı kurulmuş?
Button effectleri prop ile mi verilmiş?
Form alanlarında label ve error state var mı?
Overlay componentlerinde Title/Description kullanılmış mı?
Icon-only buttonlarda aria-label var mı?
Dark mode’da hard-coded renk problemi yok mu?
Gereksiz custom CSS yazılmadı mı?
Responsive grid/stack davranışı tanımlı mı?
Keyboard/focus erişilebilirliği korunuyor mu?

49 KiB Raw Blame History Unescape Escape

Poyraz UI — AI Consumer Guide

1. AI için kısa talimat

2. Poyraz UI nedir?

3. Dağıtım modeli

3.1. Npm package kullanımı

3.2. Source registry kullanımı

4. Kurulum

4.1. Paket kurulumu

4.2. Peer dependencies

4.3. CSS kurulumu

5. Import stratejisi

6. Tasarım dili

7. Tema ve token sistemi

8. Motion sistemi

9. Atoms

9.1. Button

9.2. Badge

9.3. Avatar

9.4. Card

9.5. Card variants

9.6. Input

9.7. Form Fields

9.8. Textarea

9.9. Checkbox

9.10. Radio Group

9.11. Switch

9.12. Label

9.13. Separator

9.14. Skeleton

9.15. Scroll Area

9.16. Logo

9.17. Typography ve TextEffect

9.18. Background Patterns

10. Molecules

10.1. Accordion

10.2. Alert

10.3. Tooltip

10.4. Popover

10.5. Hover Card

10.6. Dropdown Menu

10.7. Select

10.8. Dialog

10.9. Modal

10.10. Sheet

10.11. Drawer

10.12. Command Palette

10.13. Tabs

10.14. Breadcrumb

10.15. Pagination

10.16. Sonner / Toaster

10.17. Form

10.18. Calendar

10.19. Date Picker

10.20. Autocomplete

10.21. Mermaid

10.22. Card Templates

ArticleCard

ImageCard

NewsCard

StatsCard

TestimonialCard

PricingCard

ProductCard

StarRating

11. Organisms

11.1. Navbar

11.2. Sidebar

11.3. Footer

11.4. Announcement Bar

11.5. Data Table

12. Blocks ve hazır template mantığı

13. Sık kullanılan layout reçeteleri

13.1. Landing hero

13.2. Dashboard card grid

13.3. Settings form

13.4. Global search with Command Palette

14. Erişilebilirlik kuralları

15. AI için component seçme rehberi

16. Kaçınılması gerekenler

49 KiB

Raw Blame History