# Poyraz Portfolio — poyraz-ui v3 Migration Plan Bu planın amacı `poyraz-portfolio` projesini `poyraz-ui@2.x` kullanımından `poyraz-ui@3.0.0` kullanımına, mevcut sayfa düzenini ve portfolio kimliğini bozmadan geçirmek. Öncelik sırası: 1. Önce paket geçişi ve build/type güvenliği. 2. Sonra mevcut layout davranışını koruma. 3. En son görsel polish ve yeni v3 tasarım yeteneklerini kontrollü ekleme. > Not: Bu dokümandaki tasarım iyileştirmeleri v3 geçişinden sonra ayrı küçük fazlara bölünebilir. İlk migration hedefi “çalışan ve görsel olarak kırılmamış portfolio”dur. --- ## Mevcut Durum Özeti - Proje Next.js `16.1.6`, React `19.2.3`, Tailwind CSS v4 kullanıyor. - `poyraz-ui` şu anda npm paketi olarak `^2.0.1` kullanılıyor. - `app/globals.css` içinde `@import "poyraz-ui/preset.css";` zaten mevcut. - Componentler local registry copy olarak değil, doğrudan paket exportları üzerinden kullanılıyor. - Aktif poyraz-ui importları şu alanlarda: - `poyraz-ui/atoms` - `poyraz-ui/molecules` - `poyraz-ui/organisms` - `poyraz-ui/themes` Migration için avantajlı nokta: v3 tarafında kullanılan temel exportların çoğu korunmuş görünüyor. Bu nedenle geçişin büyük kısmı dependency bump + görsel/behavior doğrulama şeklinde ilerleyebilir. --- ## Risk Haritası ### Yüksek Öncelikli Riskler - [ ] `poyraz-ui@3.0.0` Node `>=22` istediği için local/Vercel Node versiyonu doğrulanmalı. - [ ] `pnpm-lock.yaml` v3 dependency graph ile temiz güncellenmeli. - [ ] `poyraz-ui/preset.css` v3 tokenları mevcut layout renklerini beklenmedik şekilde değiştirebilir. - [ ] Card template componentleri (`NewsCard`, `ImageCard`, `ArticleCard`, `TestimonialCard`) v3’te daha modern/glassy defaultlara sahip olduğu için mevcut compact tasarımda kayma oluşturabilir. - [ ] `CommandPalette`, `Sheet`, `Modal`, `Select`, `DropdownMenu` gibi Radix tabanlı componentlerde overlay, focus ve portal davranışı görsel olarak kontrol edilmeli. ### Orta Öncelikli Riskler - [ ] `Typography` variant ölçüleri v3 tokenlarıyla farklılaşabilir. - [ ] `Badge`, `Card`, `Button`, `Input` default radius/spacing değerleri mevcut `rounded-sm` class override’larıyla büyük ölçüde korunacak ama sayfa bazlı kontrol edilmeli. - [ ] `AnnouncementBar` v3 animasyon ve spacing’i `AppShell` içinde ekstra yükseklik/boşluk yaratabilir. - [ ] Mobile navbar sheet davranışı v3 overlay/close butonu nedeniyle farklı görünebilir. ### Düşük Öncelikli Riskler - [ ] `src/lib/themes.ts` aktif kullanılmıyor; v3 theme exportlarıyla uyumlu kalması yeterli. - [ ] `reactive-switcher` şu an kullanılmıyor; dark mode geçişi v3 migration kapsamına alınmamalı. - [ ] Portfolio tasarım polish istekleri migration sonrasına bırakılmalı. --- ## Faz 0 — Hazırlık ve Baseline Amaç: Değişiklik yapmadan önce projenin mevcut sağlığını ve migration başlangıç noktasını netleştirmek. ### Görevler - [ ] `git status --short` ile mevcut dirty dosyaları not al. - [ ] Mevcut kullanıcı değişikliklerine dokunma. - [ ] `pnpm-workspace.yaml` içinde önceden yapılmış `allowBuilds` değişikliğini kullanıcı değişikliği olarak koru. - [ ] Paket yöneticisi versiyonunu doğrula. - [ ] Node versiyonunu doğrula. - [ ] `pnpm lint` çalıştır. - [ ] `pnpm build` çalıştır. - [ ] Varsa mevcut lint/build uyarılarını migration öncesi baseline olarak not al. ### Kabul Kriterleri - [ ] Migration öncesi proje durumu belgelenmiş olmalı. - [ ] Mevcut build hatası varsa v3 geçişinden bağımsız olduğu anlaşılmalı. - [ ] Kullanıcı değişiklikleri ezilmemeli. --- ## Faz 1 — Dependency Geçişi Amaç: `poyraz-ui` paketini v3’e almak ve lockfile’ı temiz güncellemek. ### Görevler - [ ] `package.json` içindeki `poyraz-ui` sürümünü `^3.0.0` yap. - [ ] `pnpm install` ile `pnpm-lock.yaml` güncelle. - [ ] `pnpm-lock.yaml` içinde `poyraz-ui@3.0.0` çözümlendiğini doğrula. - [ ] `package.json` içine gerekirse Node engine eklemeyi değerlendir: - `node >=22` - Bu değişiklik Vercel deploy ile uyumlu olmalı. - [ ] Vercel tarafında Node 22 kullanılacağından emin olmak için proje ayarı/notu ekle. ### Kabul Kriterleri - [ ] `package.json` v3 dependency kullanıyor. - [ ] Lockfile v3’e güncellendi. - [ ] Paket kurulumu temiz tamamlandı. - [ ] Kullanılmayan geçici paket/alias eklenmedi. --- ## Faz 2 — Import ve API Uyumluluk Kontrolü Amaç: v3 sonrası TypeScript/Next build seviyesinde kırılan import veya prop kullanımlarını düzeltmek. ### Kontrol Edilecek Import Grupları - [ ] `poyraz-ui/atoms` - `Avatar` - `Badge` - `Button` - `Card` - `Input` - `Separator` - `Skeleton` - `Typography` - [ ] `poyraz-ui/molecules` - `ArticleCard` - `CommandPalette` - `DropdownMenu` - `ImageCard` - `Modal` - `NewsCard` - `Pagination` - `Select` - `Sheet` - `TestimonialCard` - [ ] `poyraz-ui/organisms` - `AnnouncementBar` - [ ] `poyraz-ui/themes` - `poyrazLightTheme` - `poyrazDarkTheme` - `poyrazThemes` ### Görevler - [ ] `rg "poyraz-ui"` ile tüm kullanım noktalarını tekrar listele. - [ ] `pnpm lint` çalıştır. - [ ] `pnpm build` çalıştır. - [ ] Kırılan import varsa en küçük değişiklikle düzelt. - [ ] Kırılan prop varsa component davranışını koruyarak v3 API’ya uyarla. - [ ] Gereksiz refactor yapma. ### Kabul Kriterleri - [ ] Tüm importlar v3 exportlarıyla uyumlu. - [ ] Type/build hatası kalmadı. - [ ] Sayfa düzenini etkileyecek gereksiz class değişikliği yapılmadı. --- ## Faz 3 — Global CSS ve Token Uyumluluğu Amaç: v3 preset tokenlarının portfolio genel görünümünü bozmadığını doğrulamak. ### Görevler - [ ] `app/globals.css` içindeki import sırasını koru: - `@import "tailwindcss";` - `@import "poyraz-ui/preset.css";` - [ ] Custom utility’leri kontrol et: - `animate-marquee` - `pause-on-hover` - [ ] `bg-background`, `text-foreground`, `border-border`, `muted-foreground` gibi semantic tokenların v3 karşılığını görsel olarak kontrol et. - [ ] Light mode temel kontrastı kontrol et. - [ ] Dark mode aktif değilse migration kapsamında dark mode ekleme. ### Kabul Kriterleri - [ ] Global CSS minimal kaldı. - [ ] Tailwind v4 compile sorunu yok. - [ ] Semantic tokenlar sayfa genelinde okunabilir. --- ## Faz 4 — Layout ve Shell Doğrulaması Amaç: Site iskeletini korumak. ### Kontrol Edilecek Dosyalar - [ ] `app/[locale]/layout.tsx` - [ ] `components/app-shell.tsx` - [ ] `components/site-navbar.tsx` - [ ] `components/search-command.tsx` - [ ] `components/language-switcher.tsx` ### Görevler - [ ] Locale layout render zincirini kontrol et. - [ ] `AppShell` max width ve spacing değerlerinin değişmediğini doğrula. - [ ] `AnnouncementBar` yüksekliği ve border davranışını kontrol et. - [ ] Desktop navbar hizasını kontrol et. - [ ] Mobile navbar sheet aç/kapat davranışını kontrol et. - [ ] Search command palette aç/kapat davranışını kontrol et. - [ ] Cmd/Ctrl + K shortcut davranışını doğrula. ### Kabul Kriterleri - [ ] Navbar layout bozulmadı. - [ ] Mobile menü çalışıyor. - [ ] Search command çalışıyor. - [ ] Announcement bar sayfa içeriğini itip bozmadı. --- ## Faz 5 — Sayfa Bazlı Görsel Regression Kontrolü Amaç: Mevcut portfolio düzenini v3 sonrası sayfa sayfa korumak. ### Ana Sayfa - [ ] `HomeHero` kart yerleşimi korunuyor. - [ ] `NewsCard` yükseklikleri düzgün. - [ ] Hero görsel alanı taşmıyor. - [ ] References marquee çalışıyor. - [ ] Sponsor kartları hizalı. ### About - [ ] Eğitim ve deneyim kartları compact kalıyor. - [ ] Sertifika sheet açılıyor. - [ ] Bookmark sheet açılıyor. - [ ] Referans ve gönüllülük link kartları hizalı. ### Blog - [ ] Kategori badge’leri doğru görünüyor. - [ ] Search input focus state rahatsız etmiyor. - [ ] `ArticleCard` grid yüksekliği dengeli. - [ ] Pagination active state düzgün. - [ ] Empty state bozulmadı. ### Blog Detail - [ ] Markdown typography okunabilir. - [ ] Code block görünümü korunuyor. - [ ] Mermaid block loading/error kartları düzgün. - [ ] TOC paneli taşmıyor. - [ ] Progress bar çalışıyor. ### Projects - [ ] `ImageCard` square grid düzenini bozmuyor. - [ ] NPM/GitHub kartları aynı yükseklik mantığında kalıyor. - [ ] Badge ve icon spacingleri düzgün. ### Content - [ ] YouTube cardları düzgün. - [ ] PDF preview kartları düzgün. - [ ] PDF modal açılıyor. - [ ] Prev/Next buttonları çalışıyor. ### Links - [ ] Profile card rounded/glass görünüm korunuyor. - [ ] `Select` ve `Input` aynı satırda düzgün. - [ ] Link kartları hover’da layout shift yapmıyor. - [ ] Mobile layout taşmıyor. ### Contact / Gallery / Volunteer / References - [ ] Kartlar compact düzeni koruyor. - [ ] Linkler çalışıyor. - [ ] Galeri modal/preview davranışı korunuyor. ### Kabul Kriterleri - [ ] Kritik sayfalarda layout kırığı yok. - [ ] Horizontal overflow yok. - [ ] Component default değişimleri mevcut tasarımı bozmadı. --- ## Faz 6 — Davranış ve Etkileşim Testleri Amaç: Sadece build almakla kalmayıp interaktif alanları doğrulamak. ### Manuel Test Listesi - [ ] Navbar linkleri locale-aware route ediyor. - [ ] Language switcher route’u bozmadan locale değiştiriyor. - [ ] Social dropdown açılıyor/kapanıyor. - [ ] Mobile sheet açılıyor/kapanıyor. - [ ] Search palette: - [ ] Click ile açılıyor. - [ ] Cmd/Ctrl + K ile açılıyor. - [ ] Arama filtreliyor. - [ ] Internal linke gidiyor. - [ ] External link yeni sekme açıyor. - [ ] About sheetleri açılıyor/kapanıyor. - [ ] Atatürk widget modal açılıyor. - [ ] PDF modal açılıyor. - [ ] PDF modal içinde prev/next çalışıyor. - [ ] Blog pagination linkleri doğru query üretir. ### Kabul Kriterleri - [ ] Temel kullanıcı akışlarında regression yok. - [ ] Focus trap/overlay kilitlenmesi yok. - [ ] Body scroll lock sorun çıkarmıyor. --- ## Faz 7 — Build, Lint ve Release Readiness Amaç: Deploy edilebilir temiz durum elde etmek. ### Görevler - [ ] `pnpm lint` - [ ] `pnpm build` - [ ] `git diff --check` - [ ] `git status --short` - [ ] Build sırasında Next warningleri not al. - [ ] Vercel Node 22 gereksinimi için deploy notu çıkar. ### Kabul Kriterleri - [ ] Build başarılı. - [ ] Lint başarılı ya da mevcut baseline dışı yeni hata yok. - [ ] Diff sadece migration kapsamındaki dosyalardan oluşuyor. --- ## Faz 8 — Commit ve Handoff Amaç: Migration değişikliklerini okunabilir şekilde teslim etmek. ### Önerilen Commit Gruplaması 1. `docs: plan poyraz-ui v3 migration` - Sadece bu plan dosyası. 2. `chore: migrate portfolio to poyraz-ui v3` - `package.json` - `pnpm-lock.yaml` - Gerekirse `pnpm-workspace.yaml` - Gerekirse küçük API uyumluluk düzeltmeleri. 3. Eğer görsel uyumluluk düzeltmesi gerekiyorsa: - `fix: preserve portfolio layout with poyraz-ui v3` ### Kabul Kriterleri - [ ] Commitler anlamlı ve review edilebilir. - [ ] Kullanıcı değişiklikleri commit kapsamına yanlışlıkla alınmadı. - [ ] Final notta test sonuçları açıkça yazıldı. --- ## Migration Sonrasına Bırakılacak Tasarım İşleri Bu işler v3 geçişinden sonra ayrıca ele alınmalı: - [ ] Portfolio genelini daha glassy/soft v3 tarzına yaklaştırma. - [ ] Button hover animasyonlarını portfolio CTA’larına uygulama. - [ ] Typography text effectlerini hero/blog başlıklarında kullanma. - [ ] Card variantlarını sayfa bazlı standardize etme. - [ ] Dark mode/theme switcher ekleme. - [ ] Links sayfasını daha modern micro-landing görünümüne taşıma. - [ ] Navbar ve command palette görsel polish. - [ ] Blog kartlarında daha zengin image/metadata layout. --- ## İlk Uygulama Sırası Migration’a başlarken uygulanacak pratik sıra: 1. Faz 0 baseline. 2. Faz 1 dependency geçişi. 3. Faz 2 import/API kontrolü. 4. Faz 7 build/lint doğrulaması. 5. Faz 4 ve Faz 5 hızlı görsel kontrol. 6. Gerekiyorsa küçük düzeltmeler. 7. Commit. Bu sıra major geçişi hızlı tamamlamaya, tasarım detaylarını ise yayın sonrası küçük ve güvenli iterasyonlara bırakmaya uygundur.