Web tema mimarisi

Sözleşme

Web okuyucunun tema tercihi kapalı bir kümedir: system, light, dark. system, canlı (prefers-color-scheme: dark) sonucunu izler; açık light veya dark seçimi sistem sonucundan üstündür. Tercih munderecat-theme anahtarıyla localStorage içinde saklanır.

Tema sunum durumudur. API isteğine, reader release context’ine, dil veya yazı seçimine ve canonical reconstruction sonucuna katılmaz. Bu sınır tema değişikliğinin metin kimliği ya da annotation davranışı üretmesini engeller.

İlk boyama ve hydration

apps/web/src/lib/theme.ts iki katman sağlar:

1. THEME_BOOTSTRAP_SCRIPT, root layout’un head bölümünde hydration’dan önce çalışır. Saklanan tercihi doğrular, sistem tercihini çözer ve html üzerinde data-theme, data-theme-preference ile color-scheme değerlerini yazar.
2. ThemeControl, hydration sonrasında tercihi yönetir; kullanıcı, sistem media-query ve başka sekmedeki storage değişikliklerini aynı uygulama fonksiyonuna yönlendirir.

Başlangıç betiği sabit repo kodudur ve kullanıcı girdisi içermez. Storage veya media-query erişimi hata verirse system ve açık görünüm güvenli varsayımdır. JavaScript çalışmazsa CSS media query sistemin koyu tercihini yine uygular.

Paylaşılan CSS sınırı

Light/dark semantic renklerin canonical kaynağı @munderecat/theme/tokens.css workspace paketidir. Web, bu değerleri --background, --surface, --surface-muted, --border, --text, --muted, --accent, --accent-contrast ve --control-border uygulama değişkenlerine bağlar. Docs aynı tokenları Starlight semantic değişkenlerine bağlar.

Paket yalnız renk tokenlarını paylaşır. Web’in munderecat-theme, docs’un starlight-theme preference state’i ve ilk boyama kodu birbirinden bağımsızdır; farklı origin’ler arasında localStorage taşınmaz. Bileşenler doğrudan tema adına göre renk seçmemelidir. data-theme="light" ve data-theme="dark" iki uygulamada aynı canonical palette’i çözer.

Doğrulama

Tema bir frontend kapsamıdır. Olağan değişiklikte gereken odaklı kapılar:

pnpm --filter @munderecat/web test
pnpm --filter @munderecat/web lint
pnpm --filter @munderecat/web typecheck
pnpm --filter @munderecat/web build

Unit test başlangıç betiğinin explicit, system, hatalı ve erişilemeyen storage durumlarını doğrular. F8-013 mobil/masaüstü görsel matrisi, F8-014 ise tam accessibility audit’ini ayrıca sahiplenir. F8-020’nin tek cross-app senaryosu iki uygulamanın dark semantic tokenlarını ve erişilebilir karşılıklı navigasyonu birlikte doğrular. Tema değişikliği DB veya corpus doğrulaması gerektirmez.