Tasarım sistemi ve uygulama kabuğu

Kapsam

Bu katman ana sayfa, katalog, gezinme ve okuma görünümünü birleştirir. Annotation, lügat, atıf ağı, hesap, tam metin araması veya yeni bir veri release’i eklemez. DB ve Content API sözleşmesi değişmez.

Quran.com’un ana sayfa, ortak gezinme girişi, sekmeli panel ve okuma ayarları yerleşimleri referans alınmıştır. Ürün bileşenleri Münderecat için yazılmıştır; referans projenin durum yönetimi veya metin motoru taşınmamıştır.

Ortak Değerler

packages/theme/index.js renk, boşluk, kontrol, radius, yerleşim ve tipografi değerlerinin tek kaynağıdır. @munderecat/theme hem web hem native tüketiciyi besler; tokens.css ve TypeScript bildirimleri bu kaynaktan üretilir.

corepack pnpm --filter @munderecat/theme generate
corepack pnpm --filter @munderecat/theme test

Açık, koyu ve sepya paletleri vardır. Native PALETTES aynı paketten gelir. Native ana ekran, uygulama menüsü, arama ve okuyucu araçları da bu temeli kullanır. Platformlar DOM bileşenlerini değil, tema, mesaj, arama ve okuyucu sözleşmelerini paylaşır.

apps/mobile/src/components/shell/ uygulama genelindeki native header ve panellerdir. screens/catalog-screen.tsx kitap/bölüm listesini, mevcut screens/reader-screen.tsx okuyucuyu yönetir. Dil ve tercihler ortak MobileUiProvider içindedir. Arayüz dili değişimi corpus isteğini yenilemez. Dokunmatik kontroller en az 44 mantıksal piksel; uzun etiketler sarılır. 430px altındaki native header tek satırda marka, Ara, Tema ve Menü gösterir; Giriş Yap ve Arayüz dili menüden erişilir. Büyük sistem yazısı tercihinde de bu kompakt düzen kullanılır. Komutların dokunma alanı küçültülmez.

Native katalogda Kitaplar/Bölümler seçimi; okuyucuda içindekiler ve okuma ayarları vardır. Web’deki başlık/sayfa gezinme panelinin birebir native kopyası, web fontlarının native dosyaları bu pakette yoktur. Native kütüphane tüm eserleri Türkçe katalog etiketleriyle gösterir; metin hedefleri yalnız okuyucudadır. Son okunan bölüm kütüphanede Okumaya devam et olarak gösterilir; geçmiş yoksa başlangıç bölümü sunulur. Bölüm içi okuma konumu kaydı korunur. Özellik eşliği bütün ekranların piksel piksel aynı olduğu veya native uygulamanın mağazada yayımlandığı anlamına gelmez.

Bileşenler ve Akış

apps/web/src/components/shell/ ortak arayüzü içerir:

Bileşen	Sorumluluk
SiteHeader	Marka; Giriş Yap, Dil, Ara, Tema ve uygulama menüsü
SiteMenu	Sağdan açılan uygulama menüsü; içerik gezinmesinden ayrıdır
LanguagePanel	Corpus dilinden bağımsız arayüz dili seçimi
ThemePicker	Üç temalı native popover menüsü; klavye seçimi ve mevcut tercih kaydı
DialogPanel	Native modal dialog; inert arka plan, Escape, odak geri dönüşü ve sayfa kaydırma kilidi
NavigationPanel	Kitaplar, Bölümler, Başlıklar, Sayfalar; seçili bağlam, arama, kalıcı bağlantılar
LibraryHome	Gerçek katalogla ana sayfa ve tam katalog görünümü
HomeSearch	Masaüstü combobox, mobil arama çekmecesi ve isteğe bağlı son seçimler
appearance	Ana sayfa ve okuyucunun ortak cihaz tercihi

• /: Kitap/bölüm araması, okumaya başlama/devam etme ve bütün kitaplar.
• /reader: 298 bölümlük mevcut tam katalog yüzeyi.
• /tr/... ve /en/...: Mevcut kalıcı okuyucu adresleri.
• /design-system: Çalışan tema/kontrol örnekleri ve açıkça işaretlenmiş gelecek modül şablonları. Etkin olmayan modüller veri veya ilerleme uydurmaz.

Ana sayfa ve menüdeki gezinme aynı paneldir. Kitap seçimi Bölümler sekmesini açar; bölüm seçimi mevcut canonical adrese gider ve panel kapanır. Okuyucuda panel açıldığında etkin kitap/bölüm görünür tutulur. Başlık verisi sadece Başlıklar sekmesi istendiğinde yüklenir. Sayfalar sekmesi şimdilik boş durum gösterir; tarayıcı yüksekliğinden basılı sayfa numarası üretilmez.

Ana sayfa, katalog, Latin/Osmanlıca/İngilizce okuyucu ve tasarım önizlemesi aynı SiteHeader kullanır. Tema ve değişiklik callback’i zorunludur; header’a sayfaya özel araç enjekte edilmez. Okuyucuda içindekiler ve okuma ayarları, bölüm dolaşımıyla birlikte ikinci sabit satırdadır. İçindekiler düğmesi bu satırın başında, bölüm seçimi ortada, ayarlar sonundadır; eski Külliyat bağlantısı kaldırılmıştır. Dar web ekranında da içindekiler gizlenmez. Native okuyucuda içindekiler/ayarlar karşılıklı uçlarda, metin hedefleri ayrı satırdadır. Tema seçici doğrudan okuyucunun mevcut updatePreferences akışını kullanır; ayrı bir tema state’i oluşturmaz, dil/düzen/yazı tercihlerini sıfırlamaz. Tasarım önizlemesinin menüsü de gerçek katalogla aynı NavigationPanel bileşenini açar.

Header 56px’tir; ikinci satır onun altına sabitlenir. Ana kontrollerin sırası, konumu ve ölçüleri 320/390/768/1440px ekranlarda sayfalar arasında test edilir. Uzun bölüm adı gerektiğinde kısaltılır; tam adı düğmenin title alanındadır. Önceki /chapters/... ayrıntılı annotation ekranı ile hata durumlarının eski header’ları bu görsel birleştirmenin kapsamı dışındadır.

Sağ üstteki Menü artık uygulama menüsüdür; içerik paneline bu menüdeki Külliyatta gezin komutuyla veya okuyucunun bölüm/içindekiler araçlarıyla ulaşılır. Header’daki katalog/dokümantasyon linkleri kaldırılmıştır. Arama ana sayfa aramasıyla aynı motoru paylaşır. Dil seçimi, 19 dildeki arayüz mesajlarını değiştirir; metin diliyle ayrımı ve güncelleme sözleşmesi ayrı belgelenmiştir. Giriş Yap bu aşamada kullanılabilir bir oturum akışı değildir.

Katalog etiketleri API’nin Türkçe bookLabel ve chapterLabel alanlarıdır. Arama Türkçe büyük/küçük harf ve aksansız girişleri tolere eder. Bu katlama yalnız katalog keşfi içindir; kaynak metne veya lexical eşleşmelere uygulanmaz.

Ana sayfa araması, referans deponun SearchInput, ExpandedSearchInputSection, CommandsList ve SearchDrawer akışlarına göre uyarlanmıştır. Masaüstünde 750px’e kadar kapsül alanın altında sonuç paneli açılır; ana sayfa içeriği filtrelenmez veya aşağı itilmez. 768px altında ayrı native modal arama açılır. Mobil giriş otomatik odaklanır; kapanırken odak ve sayfa kaydırması geri gelir. Arama kutusu ve açılır sonuçlar bütün temalarda surface, arkasındaki ana sayfa bandı subtle kullanır; koyu temada da kapalı arama alanı zeminle birleşmez.

catalog-quick-search.ts, mevcut kataloğu kitap ve bölüm seçeneklerine çevirir. Tam başlık, başlık başlangıcı, başlık içeriği ve kitap bağlamı sırasıyla aranır; eşitlikte katalog sırası korunur. Sonuçlar kesilmez, panel içinde kaydırılır. Ok tuşları seçenekleri gezer, Enter seçimi açar, Escape kapatır; masaüstünde dışarı tıklama ve odak çıkışı da kapatır. Bölüm linkleri canonical adresleri korur ve toplu prefetch yapmaz. Kitap seçimi ortak gezinmede Bölümler’i açar.

Arama mevcut kitap/bölüm adlarıyla sınırlıdır. Tam metin ve sesli arama kontrolü yoktur; bu akış yeni API/DB sorgusu, telemetri veya bağımlılık eklemez.

Metin Güvencesi

DocumentBlocks ve TargetDocument değiştirilmemiştir. Arayüz, paragraf ve cümle metnine boşluk/noktalama eklemez veya çıkarmaz. followingText, sıra, anchor kimlikleri ve source/target doğrulaması mevcut reader-core akışındadır.

Ortak ReaderPreferences.textAlignment alanı justify | start kabul eder; eksik/eski tercihler justify ile açılır. Web CSS ve native Text.textAlign yalnız sunumu değiştirir. Başlangıç hizası arayüz diline değil metnin yönüne bağlıdır. Yeni seçenekler 19 ortak sözlükte bulunur.

Native konum ölçümü readingFrame + ReaderDocument + paragraf koordinatlarını toplar. Hedef değişimi ilk route anchor’ını değil güncel kaynak paragraf ID’sini taşır. Yeni belgenin boyutu oluşmadan kaydırma uygulanmaz. Paragraf değişimleri cihazda sıralı yazılır; son bölüm ve konum okunurken bekleyen yazılar tamamlanır. Kütüphane odağı geri aldığında son bölüm yenilenir. English standalone_text için tahmini paragraf hizası üretilmez; çeviri baştan gösterilir, kaynak anchor Latin/Osmanlıcaya dönüş için korunur. Anchor varlığı parallel modunu açmaz. İngilizce bloğun içindeki kesin konum ayrı bir hizalama tüketici işi olarak kalır.

Web ve native okuyucuda Latin / Osmanlıca / Çeviri modları, okuma ayarının yanındaki simgelerle seçilir; ayrı sekme satırı yoktur. Latin ve Osmanlıca doğrudan geçiş yapar, Çeviri simgesi dil seçicisini açar: webde sağ dialog, native’de alt seçim paneli. Etkin simge vurgu rengiyle belirtilir; web tooltip ve erişilebilir adlar, native’de uzun basma açıklaması bulunur. readerTranslationTargets ortak hedef kaydını kaynak diliyle karşılaştırır; Osmanlıca farklı yazım olduğundan çeviri listesine girmez. Hedef kullanılabilirliği ve canonical dil adresi birlikte aranır. Şu an tek çeviri English’tir; yeni bir çeviri API/reader-core hedef ve adres sözleşmelerine eklendiğinde aynı seçici kullanılır, yeni bir üst sekme eklenmez. Arayüz dili ayrı tutulur. Çeviri yükleme hatasında Türkçe fallback gösterilmez. parallel yalnız açık okuma tercihiyle kullanılır; çeviri kaynak metinden önce yer alır. Osmanlıca paralel görünümün mevcut sırası ve kaynak konumu davranışı korunur.

Tema ve bölüm geçmişi isteğe bağlı cihaz verisidir:

• munderecat.reader.preferences.v1: mevcut okuma tercihleri.
• munderecat.reader.position.v1: mevcut bölüm/paragraf konumu.
• munderecat.reader.recent.v1: en son açılan bölümün ID’si.
• munderecat.catalog.search-history.v1: en fazla altı kitap/bölüm seçim ID’si; sorgu metni veya corpus metni saklanmaz. Kullanıcı mobil aramada temizleyebilir.

Depolama kapalıysa metin gösterimi çalışır. Tema pre-hydration script’inde uygulanır; ana sayfa, okuyucu ve tasarım kataloğu aynı tercihi sürdürür.

Görsel Dosyalar

apps/web/public/images/library-engraving.webp, bu ürün için üretilmiş kitap gravürüdür; kompakt ana sayfa arka planında düşük kontrastla kullanılır. Kaynak eser kapağı veya metin sayfası iddiası taşımaz. Optimize WebP yaklaşık 130 KiB’dir. Marka işareti public/brand-mark.svg, kontrol ikonları mevcut Lucide bağımlılığıdır.

Görsel Dil

İkinci tasarım turunda ana eksen daha fazla bileşen değil, aynı bileşenlerin oranları ve uyumu oldu:

• Figtree: Arayüz ile Latin/İngilizce okuma metninin ortak, sade yazı ailesi.
• Newsreader: Marka, eser ve bölüm başlıklarında ayrı bir kitap karakteri.
• Noto Naskh Arabic: Osmanlıca ve Latin metin içindeki Arap harfli ibareler için cihazdan bağımsız web yazı ailesi.
• Ölçek: Masaüstünde 76px marka, 28px ana sayfa bölüm başlığı, 18px kitap etiketi; okuyucuda 44px eser başlığı ve 20px başlangıç metni. Telefon ölçekleri ayrı sabit basamaklardır.
• Yüzey: Kitap listesinde hafif çerçeve; arama ve mod seçimlerinde yumuşak kontrol yüzeyi. Sayfa bölümleri kartlara kapatılmaz.
• Vurgu: Cilt kırmızısı #96362f, beyaz düğme yazısı ve #812c26 hover üç temada da sabittir. Küçük yazı/ikon/odak için ayrı accentForeground rolü vardır; koyu zeminde #f28e85, diğer temalarda cilt kırmızısıdır. Marka dolgusu ile koyu zeminde okunabilir yazı aynı token’a yüklenmez.
• Tema ilişkisi: Ana zemin ve panel aynı taban tonundadır; açıkta beyaz, koyuda kömür grisi, sepyada sıcak kâğıt. Seçili gezinme satırı ve ayarlar ortak subtle yüzeyini kullanır. Sekme kanalı aynı yüzey, etkin sekme ana yüzeydir. Seçili modlar birincil komut gibi kırmızı dolgu almaz.
• Köşeler: Kontroller 12px, kitap kartları 8px; ana sayfa aksiyonları, arama ve dil/gezinme sekmeleri kapsül biçimindedir. Tam boy panellerin sayfa kenarları düz kalır.
• Gezinme: Sekmeler ile kapatma düğmesi aynı üst satırdadır. Görsel olarak gizlenen panel başlığı erişilebilir dialog adını korur.

Web fontları public/fonts/, native dosyalar apps/mobile/assets/fonts/ altında, özgün OFL dosyaları ve kaynak envanteriyle yerel sunulur. Google Fonts’a runtime bağlantısı kurulmaz. Her iki istemcide arayüz/Latin/İngilizce Figtree, başlıklar Newsreader, Osmanlıca Noto Naskh Arabic kullanır. Native’de sekiz statik TTF dosyası (toplam yaklaşık 720 KiB) expo-font/useFonts ile yüklenir. components/text.tsx, normal/orta/kalın ağırlıkları doğru dosyaya yönlendirir; iç içe cümlelerin üst metnin fontunu miras almasını ve bütün nativeID/onLayout özelliklerini korur. TextInput da aynı Figtree ailesindedir. Fontlar hazır olmadan okuyucu mount edilmez; yükleme hatası olursa platform fontuyla devam eder. Newsreader native’de opsz=16 sabit örneği, webde otomatik optik boyutlandırma kullanır. Aileler aynıdır; platformlar arası piksel/piksel eşitlik vaat edilmez. Expo font rehberinin platformlar arası statik font önerisi izlenir. Yeni native metinlerde ortak Text/TextInput kullanılmalıdır; global React Native defaultProps değiştirilmez.

Referansın güncel arayüzü ve kaynak deposu, tipografik hiyerarşi ve ortak gezinme davranışı için karşılaştırılmıştır. Bu kararlar görsel bir yön belirler; referansla aynı tasarım olgunluğuna ulaşıldığı iddiası taşımaz. Görsel kabul, masaüstü/telefon ve açık/koyu ekranların birlikte incelenmesiyle sürdürülmelidir.

Tema karşılaştırmasında referans deponun src/styles/themes/_light.scss, _dark.scss ve _sepia.scss dosyaları kullanılmıştır. Referansın sepya vurgu rengi farklıdır; Münderecat’ta cilt kimliğini korumak için marka dolgusu üç temada sabit bırakılmıştır. Ton hiyerarşisi örnek alınır, tüm palet kopyalanmaz.

Yerel Kontrol

make reader-dev
MUNDERECAT_READER_FOUNDATION_BASE_URL=http://127.0.0.1:3000 \
  corepack pnpm --filter @munderecat/web test:browser
corepack pnpm --filter @munderecat/web test
corepack pnpm --filter @munderecat/web typecheck
corepack pnpm --filter @munderecat/web lint
corepack pnpm --filter @munderecat/mobile typecheck

Tarayıcı paketi kısa/uzun bölümde birebir metin, dil ve heading geçişleri, ana sayfa araması, menü sekmeleri, odak, tema kalıcılığı, kapalı cihaz depolaması, 320/390px taşma ve otomatik WCAG A/AA kontrollerini kapsar. Bu görsel değişiklik için full corpus DB rebuild’i gerekmez.