Grafik Stil Kitabı

Bu, "iyi" bir Blocklens grafiğinin nasıl göründüğüne dair standart referanstır. ~70 yerleşik şablonda (chart-templates), DB üzerinden tohumlanan şablonlarda (template-seeds) ve the chart renderer bileşeninin render davranışında ifade edilen kuralları özetler.

İki hedef kitle:

1. Frontend / şablon yazarları — yeni şablonlar veya tohum verisi tasarlarken bu kuralları uygulayın.
2. Buddy lab-author becerisi — bu kuralların yoğunlaştırılmış bir kopyasını yükleyerek yapay zeka tarafından üretilen grafik yapılandırmalarının küratörlü kataloğun görsel diline uymasını sağlar.

Aşağıdaki kurallardan biri, bir şablonun mevcut davranışıyla çelişiyorsa eski (legacy) nedenlerle şablon esas alınır; ancak yeni çalışmalar bu kılavuzu izlemelidir.

---

1. Eksenler

1.1 Fiyat her zaman sağ Y ekseninde, log ölçek

BTC fiyatını üst üste bindiren her şablon, fiyatı scale: "log" ile ayrı bir sağ eksene yerleştirir. Birincil metrik sol eksene gider. Fiyatı görsel olarak bağlamak ama sayısal olarak ayırmak, hızlı büyüyen metrikleri (holdings, AUM, supply) ve fiyatı birlikte okunabilir kılar.

İstisna: fiyat modeli şablonları (realized_price, transferred_price), kullanıcıların iki fiyatı tek ölçekte karşılaştırabilmesi için fiyatı modelle aynı eksene koyar. O eksen log'dur.

1.2 Aynı birimi paylaşan metrikler bir ekseni paylaşır

• lth_supply + sth_supply → tek sol eksen (ikisi de BTC).
• lth_mvrv + sth_mvrv → tek sol eksen (ikisi de oran).
• Funding rate (%) solda, fiyat (USD) sağda — farklı birimler, farklı eksenler.

Çok farklı aralıklara sahip iki metriği aynı lineer eksende üst üste yığmayın. Küçük olan seri görsel olarak ezilir.

1.3 Döngü karşılaştırması: allLeftAxis: true + log ölçek

Döngü performansı şablonları (ör. cycle-perf-low, cycle-perf-ath, cycle-perf-halving), yAxes: [{ side: "left", scale: "log" }] ile birlikte allLeftAxis: true değerini zorunlu kılar. Birden fazla döngü aynı log ekseninde üst üste bindirilir; böylece üstel büyüme döngüler arasında karşılaştırılabilir olur.

1.4 Eksen etiketi rengi

• Bir ekseni paylaşan, farklı renklerde birden fazla seri → eksen etiketi nötr koyu gri #6b7280.
• Bir ekseni tek başına kullanan tek bir metrik → etiket o metriğin rengini devralabilir (nadiren kullanılır; gri güvenli varsayılandır).

---

2. Ölçek seçimi

Lineer kullanın	Log kullanın
Supply, akışlar, sayımlar, USD değerleri, piyasa değeri	BTC fiyatı (her zaman)
Oranlar (MVRV, SOPR), yüzdeler, funding rate'ler	Tek başına gösterildiğinde hisse senedi endeksleri (SPY/QQQ/IWM)
Günlük deltalar, net değişimler	Fiyat modelleri (realized_price, transferred_price)
Sınırlı bir aralıkta dalgalanan her şey	Döngü performansı üst üste bindirmeleri

Bir metrik görünür pencerede ~2 büyüklük mertebesinden fazla yayılıyorsa log'u tercih edin.

---

3. Metriğe göre grafik türü

Stil	Ne zaman	fillOpacity
area	Holdings, supply'lar, kümülatif akışlar, AUM, yığılı kohortlar	0.3
line	Oranlar (MVRV, SOPR), oranlar (funding), fiyat üst üste bindirmeleri	0.1
bar	Günlük / 30 günlük deltalar (net akışlar, supply 30G Δ)	0.5
candlestick	Yalnızca OHLC	—

Log ekseninde çubuklar okunamaz şekilde render olur — çubukları lineer tutun.

---

4. Renk paleti

4.1 Alana göre

Alan	Öğe	Hex
Fiyat üst üste bindirme	BTC fiyatı (nötr)	#6b7280
Supply	LTH	#2563eb
Supply	STH	#dc2626
Supply	üçüncü kohort	#fbbf24 / #FFBB28
ETF	holdings	#f59e0b
ETF	AUM	#3b82f6
ETF	net akış	#10b981
ETF	kümülatif akış	#059669
ETF	baskınlık	#8b5cf6
ETF	ABD holdings	#3b82f6
ETF	realized price	#dc2626 / #ea580c
DAT	toplam holdings	#F7931A (Bitcoin markası)
DAT	halka açık şirketler	#0088FE
DAT	devletler	#FF4444
DAT	özel şirketler	#FFBB28
DAT	net değişim	#82ca9d
DAT	baskınlık	#ff7300
Funding	rate	#3b82f6
Funding	spread	#f97316
Funding	aşırı ısınmış bölge	rgba(239,68,68,0.1)
Funding	kapitülasyon bölgesi	rgba(34,197,94,0.1)
Makro	getiriler (nötr)	#6b7280
Makro	enflasyon	#f59e0b
Makro	VIX / risk	#ef4444
Döngü 1→4	mor → mavi → yeşil → turuncu	#8b5cf6 → #3b82f6 → #22c55e → #f97316

4.2 Çok metrikli renklendirme

İki ilişkili kohort birlikte göründüğünde (LTH/STH, ABD/ABD dışı, halka açık/özel), kullanıcıların tek bir zihinsel model öğrenmesi için yerleşik çifti kullanın (LTH/STH için mavi + kırmızı). Her grafik için paletleri yeniden icat etmeyin.

---

5. Referans çizgileri ve alanları

Bunları yalnızca eşiğin net bir yorumu olduğunda kullanın:

• Funding rate > 20% → kırmızı gölgeli alan, "Overheated" etiketi.
• Funding rate < -10% → yeşil gölgeli alan, "Capitulation" etiketi.
• SOPR = 1.0 → başabaş noktasında referans çizgisi (fırsat — henüz şablonlarda yok).
• MVRV = 1.0 → adil değer paritesinde referans çizgisi.

Sayısal anlamı olmayan dekoratif çizgilerden kaçının. Grafik başına en fazla bir veya iki açıklama.

"referenceAreas": [
  { "y1": 20, "y2": 100, "yAxisId": "axis-left", "fill": "rgba(239,68,68,0.1)", "label": "Overheated" },
  { "y1": -100, "y2": -10, "yAxisId": "axis-left", "fill": "rgba(34,197,94,0.1)", "label": "Capitulation" }
]

---

6. Tarih aralığı varsayılanları

Ön ayar	Ne zaman
ALL	Uzun trendli metrikler — supply, değerleme, döngü üst üste bindirmeleri, kullanıcıların tam olarak görmek isteyeceği uzun geçmişe sahip her şey.
1Y	Çok yıllı görünümlerin sinyali gizlediği gürültülü metrikler — günlük net akışlar, DAT net değişimi, funding spread.
1W / 1M	Asla varsayılan değil — bunlar kullanıcı tarafından yönlendirilen yakınlaştırma seviyeleridir.

---

7. Stil sabitleri

Grafiğe özgü bir neden olmadıkça bunları her yerde kullanın:

• Tüm çizgiler için strokeWidth: 2.
• Alanlar için fillOpacity: 0.3, çizgi üst üste bindirmeleri için 0.1, çubuklar için 0.5.
• instanceId formatı: {metricId}-{seq} (ör. price-1, lth_supply-1). Düzenlemeler arasında kararlı.

---

8. Adlandırma kuralları

• Grafik adı — isim öbeği, bir sütun başlığı gibi başlık biçiminde. ≤60 karakter. Emoji yok.
  • İyi: BTC LTH Supply with 30D Change, ETF Net Flow vs. Price
  • Kötü: 📈 Bitcoin Long-Term Holders!!! (2024)
• Açıklama — grafiğin ne gösterdiğini ve ortaya çıkardığı içgörüyü anlatan tek cümle.
  • İyi: Long-term holder supply with 30-day delta bars to surface accumulation and distribution waves.

---

9. Anti-pattern'ler

Bir şablonu veya yapay zeka tarafından üretilen yapılandırmayı incelerken bunları reddedin:

• İki eksenli düzende tek metrik — boş eksen israf edilmiş alandır.
• Yığma olmadan tek eksende 4'ten fazla seri — görsel olarak okunamaz.
• Tek bir lineer eksende çok farklı aralıkları karıştırmak (ör. 1-2M arası sayımlarla 20k-100k arası fiyat) — küçük seri görünmez olur.
• Yüksek büyümeli bir metrikle eşleştirildiğinde lineer eksende BTC fiyatı — fiyat görsel olarak baskın olur.
• Sayısal anlamı olmayan dekoratif referans çizgileri — sinyal değil, gürültü ekler.
• Log ölçeğinde çubuklar — okunamaz şekilde render olur.
• Grafiğe özel, kendine has palet — kullanıcının öğrendiği renk çağrışımlarını bozar.

---

10. lab-author becerisi için hızlı referans

Buddy doğal dilden bir grafik yapılandırması oluşturduğunda:

1. Metrik ID'lerini search_metrics / get_metric ile çözümleyin. Her metriğin grade değerinin kullanıcının seviyesi (tier) dahilinde olduğunu doğrulayın.
2. Eksen düzenine karar verin:
   • BTC fiyatı serilerden biri mi? → fiyat sağda scale: "log" ile, birincil solda.
   • Kalan metrikler bir birim paylaşıyor mu? → aynı eksen. Farklı birimler mi? → farklı eksenler.
3. §3'e göre grafik stillerini seçin.
4. §4.1'e göre renkleri seçin — alan için yerleşik paleti kullanın.
5. §2'ye göre ölçeği seçin.
6. §6'ya göre tarih aralığını seçin.
7. Referans çizgilerini/alanlarını yalnızca eşiğin net bir anlamı olduğunda ekleyin (§5).
8. Stil sabitlerini (§7) ve adlandırma kurallarını (§8) uygulayın.
9. Kaydetmeden önce anti-pattern kontrol listesini (§9) çalıştırın.

---

11. Şablonların bulunduğu yer

• Statik (frontend) — chart-templates. Uygulama başlangıcında yüklenen ~70 şablon.
• Veritabanı (templates tablosu) — template-seeds ile tohumlanan ve the templates API üzerinden sunulan küratörlü şablonlar.
• Kullanıcı tarafından oluşturulan (user-charts tablosu) — bu kılavuzun geri kalanının konusu olan şey. Lab arayüzü üzerinden, bir şablonu çatallayarak (forking) veya Buddy'nin save_chart MCP aracıyla kaydedilir.

Yapılandırma JSON şekli (metrics, formulas, yAxes, dateRange, referenceLines, referenceAreas vb.) her üç kaynakta da aynıdır — TypeScript tanımı için the Lab API client içindeki the chart config'ye ve Pydantic şeması için the API schema'ye bakın.