# Faz 4 — Poyraz UI v3 foundation

Tarih: 2026-07-16

Bu faz, freelancer ve portal sayfalarının dikey dönüşümünden önce ortak UI sözleşmesini kurar. Sayfa bazlı bilgi mimarisi ve görsel revizyonlar Faz 5–6'da kullanıcı yönlendirmesiyle yapılacaktır.

## Uygulanan temel

- `poyraz-ui` `3.0.2` sürümüne yükseltildi; hem pnpm hem npm lockfile'ları eşitlendi.
- Tailwind v4 girişine `poyraz-ui/preset.css` eklendi.
- Atom, molecule ve organism importları yalnızca ilgili package subpath'inden yapılıyor.
- Freelancer ve portal shell'i aynı Poyraz Sidebar organism bileşimini kullanıyor.
- Masaüstü daraltma, mobil overlay ve mobil aç/kapat state'i `SidebarProvider` tarafından yönetiliyor.
- Hesap menüsü custom event yönetimi yerine Poyraz `DropdownMenu`; icon-only shell aksiyonları Poyraz `Tooltip` kullanıyor.
- Root feedback katmanı Poyraz `Toaster`; auth bildirimleri Poyraz `Alert` ve `toast` kullanıyor.
- Auth alanları ve loading ekranları local kopyalar yerine Poyraz atomlarını kullanıyor.
- Instance adı ve açık/koyu logo shell ile auth yüzeylerine taşındı.

## Import ve ownership kuralı

```ts
import { Button, Input, Typography } from "poyraz-ui/atoms";
import { Alert, Dialog, Form, Select, toast } from "poyraz-ui/molecules";
import { DataTable, Sidebar } from "poyraz-ui/organisms";
```

`poyraz-ui` package root importu kullanılmaz. Genel amaçlı UI primitive'i `components/ui` altında yeniden yazılmaz. Neta'ya özgü durum veya davranış, Poyraz bileşenlerinden `components/system` altında compose edilir.

İzin verilen local davranış yardımcıları:

- `OfflineIndicator`: browser bağlantı durumu davranışı.
- `PendingLink`: Next.js navigasyon pending davranışı.
- `PendingSubmitButton`: server action pending davranışı; görsel primitive olarak Poyraz `Button` kullanır.

Bu sınır `pnpm phase4:ui-boundary` ile otomatik doğrulanır.

## Typography ve page header

Poyraz `Typography` bütün yeni sayfalarda metin semantiğinin kaynağıdır:

| Rol | Poyraz variant | HTML semantiği |
| --- | --- | --- |
| Sayfa başlığı | `h1` | `h1` |
| Bölüm başlığı | `h2` / `h3` | sıradaki doğru heading seviyesi |
| Kart başlığı | `h4` / `large` | bağlama göre `h2`–`h3` |
| Gövde | `body` / `p` | `p` |
| Yardımcı açıklama | `muted` | `p` |
| Metadata | `caption` / `small` | `span` veya `p` |

Yeni liste ve detay sayfaları `components/system/page-header.tsx` bileşimini kullanır. Header sırası: isteğe bağlı eyebrow, tek `h1`, kısa açıklama, secondary aksiyonlar ve en sağda bir primary aksiyon. Bir görünümde birincil aksiyon sayısı bir olmalıdır. Secondary aksiyonlar `secondary`, `outline` veya `ghost`; riskli aksiyonlar yalnızca `destructive` variant kullanır.

## Form standardı

İki form yolu vardır:

1. Basit Server Action formları native `<form>` ile; görünür Poyraz `Label`, Poyraz `Input`/`Textarea`/`Select`, alan yanında açıklama ve inline hata kullanır.
2. Client-side etkileşimli veya çok alanlı formlar `react-hook-form` ile Poyraz `Form`, `FormField`, `FormItem`, `FormLabel`, `FormControl`, `FormDescription` ve `FormMessage` bileşimini kullanır. Zod doğrulaması gerektiğinde mevcut resolver katmanı kullanılır.

Kurallar:

- Placeholder label yerine geçmez.
- Server ve client aynı Zod/domain sözleşmesine göre doğrular; client doğrulaması güvenlik sınırı değildir.
- Alan hatası `FormMessage` veya alanın hemen altındaki inline metinle gösterilir. Toast tek başına form hatası değildir.
- Submit durumu Poyraz `Button` üzerindeki `loading`, `disabled` ve `aria-busy` proplarıyla gösterilir.
- Başarılı, formun dışında etkisi olan işlem toast ile; kullanıcının karar vermesi gereken veya kalıcı bilgi inline `Alert` ile gösterilir.

## Status-to-Badge standardı

Merkezi eşleme `components/system/status-badge.tsx` içindedir.

| Anlam | Örnek status'ler | Badge variant |
| --- | --- | --- |
| Başarılı/çalışır | `active`, `accepted`, `completed`, `done`, `paid` | `success` |
| Süreçte/bilgi | `in_progress`, `sent` | `info` |
| Bekliyor/dikkat | `pending`, `paused` | `warning` |
| Plan/taslak | `planning`, `planned`, `todo`, `draft` | `secondary` |
| Hata/risk | `overdue`, `rejected`, `revoked`, `expired` | `destructive` |
| Pasif terminal | `cancelled`, `archived` | `outline` |

Renk tek başına anlam taşımaz; badge her zaman Türkçe durum metni içerir.

## Feedback state standardı

`components/system/feedback-state.tsx` yeni sayfaların ortak state bileşimidir.

- Loading: layout'a yakın Poyraz `Skeleton`; kapsayıcıda `aria-busy` ve screen-reader label.
- Empty: nötr Poyraz `Card`, kısa neden ve mümkünse bir sonraki primary aksiyon.
- Error: Poyraz destructive `Alert`, kullanıcıya uygun açıklama ve retry aksiyonu.
- Forbidden: Poyraz warning `Alert`; var olmayan kaynağı açığa çıkarmayacak metin ve güvenli geri dönüş.
- Toast: kısa ömürlü, sayfalar arası kalıcı olmayan işlem sonucu.
- Inline Alert: kullanıcının okumadan devam etmemesi gereken, forma veya sayfaya bağlı durum.

## Overlay, confirmation, table ve KPI

- Geri döndürülemez işlem `components/system/destructive-confirmation.tsx` üzerinden açık `DialogTitle`, `DialogDescription`, vazgeç ve destructive onay aksiyonu ile kurulur.
- Kısa desktop formu `Dialog`, bağlamsal yan panel `Sheet`; küçük ekranda uzun/çok adımlı akış `Drawer` olur. Ekranı kaplayan özel div overlay yazılmaz.
- Veri listeleri seçim, arama, pagination, loading veya error gerektiriyorsa Poyraz organism `DataTable` kullanır. Basit iki sütunlu statik bilgiler native semantic table kalabilir.
- Dashboard metrikleri Poyraz `StatsCard` ile kurulur: kısa label, formatlanmış value, isteğe bağlı trend ve tek anlamlı icon. Renk yalnızca trend/durum bilgisini destekler.

## Branding token bridge

Branding servisi eski `--primary` benzeri uygulama tokenları yerine Poyraz v3 sözleşmesini server-side üretir:

- `--poyraz-primary` ve foreground/hover/active/scale rolleri
- `--poyraz-ring` ve `--poyraz-focus-ring`
- `--poyraz-radius-xs` … `--poyraz-radius-xl`

Değerler root `<html style>` içine SSR edilir; bu nedenle ilk render'da varsayılan renkten instance rengine geçiş parlaması oluşmaz. `system` renk modu ilk paint öncesi media query ile `.dark` sınıfına çevrilir ve işletim sistemi değişikliği dinlenir. `--poyraz-accent`, secondary, surface, status, elevation, density ve motion gibi semantik etkileşim rolleri inline branding katmanında ezilmez; light/dark karşılıklarının tek kaynağı Poyraz presetidir. Branding API'sindeki türetilmiş `accentColor` alanı mobil ve harici istemciler için korunur, web tema köprüsüne enjekte edilmez.

Recharts içindeki eski `hsl(var(--...))` ifadeleri geçerli Poyraz CSS renk tokenlarına taşındı.

## Local primitive ve dependency sonucu

Kaldırılan local generic primitive'ler: Button, Card, Checkbox, Dialog, DropdownMenu, Field/Form, Input/Label, Select, Separator, Skeleton, Textarea ve Toast/Toaster. Kullanılmayan eski toast hook'u ve `next-themes` provider'ı da kaldırıldı.

Poyraz'ın kendi dependency ağacında yönettiği `@base-ui/react`, doğrudan Radix paketleri, `radix-ui`, `class-variance-authority`, `shadcn`, ayrıca kullanılmayan `@iconify/react` ve `next-themes` doğrudan Neta dependency listesinden çıkarıldı. Poyraz molecule entrypoint'i dinamik Mermaid importunu build sırasında çözdüğü için package'ın optional peer'i `mermaid` açık dependency olarak eklendi. Sonuçta doğrudan dependency sayısı net 14, pnpm kurulum ağacı yaklaşık 112 paket azaldı.

## Erişilebilirlik foundation kuralları

- Heading hiyerarşisi semantik component proplarıyla korunur.
- Icon-only aksiyonlar görünür label yoksa `aria-label`; bağlam açıklaması gerekiyorsa Tooltip kullanır.
- Dialog/Sheet/Drawer title ve description olmadan yayınlanmaz.
- Focus ring utility ile kapatılmaz; Poyraz focus tokenı branding primary rengine bağlıdır.
- Loading ve disabled görsel class taklidiyle değil component proplarıyla kurulur.
- Global reduced-motion kuralı ve component seviyesinde `motion-reduce` korunur.
- Durumlar renk yanında metin ve gerektiğinde icon ile anlatılır.

Bu faz foundation sözleşmesini doğrular. Legacy feature sayfalarının tamamına uygulanması ilgili Faz 5–6 dikey dilimlerinin kalite kapısıdır.

## Doğrulama

```bash
pnpm phase4:ui-boundary
pnpm typecheck
./node_modules/.bin/eslint app/layout.tsx components/layout components/system components/auth components/error-toaster.tsx components/ui/offline-indicator.tsx components/ui/pending-link.tsx components/ui/pending-submit-button.tsx app/login/page.tsx app/register/page.tsx 'app/invite/[token]/page.tsx' server/branding/service.ts scripts/phase4-ui-boundary.mjs
pnpm phase3:storage-smoke
pnpm phase1:auth-smoke
pnpm build
git diff --check
```

Boundary testi v3 major sürümünü, preset importunu, Sidebar bileşimini, package subpath importlarını, izin verilen local UI dosyalarını ve kaldırılan duplicate UI bağımlılıklarını doğrular.

Foundation hedefli ESLint kontrolü temizdir. Repo genelindeki `pnpm lint`, henüz Faz 5–7'de taşınacak legacy feature/API dosyalarındaki mevcut `no-explicit-any`, `set-state-in-effect` ve benzeri borçlar nedeniyle bu fazda global kalite kapısı olarak kapatılmadı; master plandaki genel lint maddesi bu nedenle işaretlenmedi.