poyraz-portfolio/docs/poyraz-ui-v3-migration-plan.md

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.

Faz 0 Notları

• Node: v24.16.0
• pnpm: 11.5.1
• Baseline pnpm lint: başarılı, mevcut 4 warning var.
• Baseline pnpm build: başarılı.
• Next baseline warning: middleware file convention deprecated, proxy öneriliyor.

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.

Faz 1 Notları

• poyraz-ui: ^2.0.1 → ^3.0.0
• package.json içine engines.node: >=22 eklendi.
• pnpm install sonrası lockfile poyraz-ui@3.0.0 olarak çözümlendi.
• pnpm, güvenlik politikası nedeniyle pnpm-workspace.yaml içine minimumReleaseAgeExclude: poyraz-ui@3.0.0 ekledi.

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.

Faz 2 Notları

• V3 sonrası import/API kırığı çıkmadı.
• pnpm lint: başarılı, baseline ile aynı 4 warning devam ediyor.
• pnpm build: başarılı.
• Bu fazda component kullanımını veya layout classlarını değiştirmeye gerek kalmadı.

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";
• poyraz-ui dist utility classlarının tüketici build/dev tarafında tarandığını garantiye al.
  • @source "../node_modules/poyraz-ui/dist";
• 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 3 Ara Notları

• ArticleCard ve TestimonialCard içindeki avatar görselleri npm paketinin template classlarına (size-6, size-9) bağlı.
• Avatar boyutlarının bozulması component kullanımından değil, Tailwind source scan/dev cache tarafında poyraz-ui/dist classlarının kaçırılmasından kaynaklanabilir.
• Componentlere hardcoded avatar classı eklemek yerine app/globals.css içinde paket dist source’u açıkça tanımlandı.
• Bu değişiklik sonrası pnpm lint ve pnpm build başarılı.
• Build CSS çıktısında .bg-background, .text-foreground, .border-border, .text-muted-foreground, .animate-marquee, .pause-on-hover:hover, .size-6 ve .size-9 classları doğrulandı.
• Dark mode/theme switcher bu migration fazında eklenmedi; mevcut light mode korunuyor.

---

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 4 Notları

• Locale layout NextIntlClientProvider + AppShell zinciriyle korunuyor.
• AppShell container yapısı max-w-4xl, px-4 sm:px-6, py-4 olarak değişmedi.
• SiteNavbar desktop link/search/social dropdown hattı v3 componentleriyle build ve runtime smoke testinden geçti.
• SearchCommand click ile açılıyor, query yazınca sonuç üretiyor ve dialog render oluyor.
• Mobile viewport smoke testinde Menü sheet dialogu açıldı.
• Runtime smoke sonucu:
  • navLogo: başarılı
  • announcement: başarılı
  • commandOpen: başarılı
  • commandItems: 2 sonuç
  • mobileSheet: başarılı

---

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 5 Notları

• Production runtime smoke testte şu sayfalar desktop viewportta kontrol edildi:
  • /tr
  • /tr/about
  • /tr/blog
  • /tr/projects
  • /tr/content
  • /tr/links
  • /tr/contact
  • /tr/gallery
  • /tr/about/references
  • /tr/about/volunteer-community
• Tüm bu sayfalarda horizontal overflow 0 ölçüldü.
• Oversized rounded avatar/image regression bulunmadı.
• Blog empty state /tr/blog?search=unlikelymigrationquery ile doğrulandı.
• Blog detail sayfasında progress bar ve TOC render doğrulandı.
• Gallery preview/modal akışı 15 galeri itemı üzerinden doğrulandı.

---

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 6 Notları

• Navbar /tr → /tr/about locale-aware route akışı geçti.
• Language switcher /tr → /en akışı geçti.
• Social dropdown açılışı doğrulandı.
• Search palette:
  • Click ile açıldı.
  • Ctrl+K ile açıldı.
  • blog araması sonuç döndürdü.
  • Internal item route etti.
  • GitHub external item yeni sayfa hedefi olarak https://github.com/poyrazavsever açtı.
• About certificate ve bookmark sheetleri açıldı.
• Atatürk widget modalı açıldı.
• Content PDF modalı 27 PDF card button üzerinden doğrulandı; prev/next kontrolleri modalda göründü.
• Blog pagination linkleri /blog?page=2 ve /blog?page=3 queryleriyle doğrulandı.
• Mobile sheet açıldığında body scroll lock aktifti.

---

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 7 Notları

• pnpm lint: başarılı. Baseline dışı yeni hata yok; mevcut 4 warning devam ediyor:
  • components/blog-detail-content.tsx: @next/next/no-img-element
  • components/links-content.tsx: @next/next/no-img-element
  • scripts/fetch-medium-all.mjs: kullanılmayan mkdirSync
  • scripts/test-medium-scraper.mjs: kullanılmayan response
• pnpm build: başarılı.
• Next build warning: middleware file convention deprecated, proxy öneriliyor.
• git diff --check: temiz.
• git status --short: yalnızca migration kapsamındaki 5 dosya değişti:
  • package.json
  • pnpm-lock.yaml
  • pnpm-workspace.yaml
  • app/globals.css
  • docs/poyraz-ui-v3-migration-plan.md
• Deploy notu: poyraz-ui@3.0.0 Node >=22 istediği için Vercel project Node.js runtime ayarı Node 22+ olmalı. package.json içinde engines.node: >=22 eklendi.

---

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ı.

Faz 8 Notları

• Commitler migration kapsamını okunabilir tutacak şekilde şu mantıkla ayrıldı:
  1. Plan/checklist dokümantasyonu.
  2. poyraz-ui@3.0.0 dependency ve lockfile geçişi.
  3. Tailwind v4 consumer source scan düzeltmesi.
• Commit kapsamı yalnızca migration için değişen dosyalarla sınırlandı.

---

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.