Chart-Stilhandbuch

Dies ist die verbindliche Referenz dafür, wie ein „gutes" Blocklens-Chart aussieht. Es fasst die Regeln zusammen, die in den rund 70 integrierten Vorlagen (chart-templates), den per DB eingespielten Vorlagen (template-seeds) und im Rendering-Verhalten von the chart renderer zum Ausdruck kommen.

Zwei Zielgruppen:

1. Frontend- / Vorlagenautoren — wenden diese Regeln beim Entwurf neuer Vorlagen oder Seed-Daten an.
2. Die Buddy-Skill lab-author — lädt eine verdichtete Kopie dieser Regeln, damit KI-generierte Chart-Konfigurationen der visuellen Sprache des kuratierten Katalogs entsprechen.

Widerspricht eine der folgenden Regeln dem aktuellen Verhalten einer Vorlage, hat die Vorlage aus Gründen der Abwärtskompatibilität Vorrang — neue Arbeiten sollten sich jedoch an diesem Leitfaden orientieren.

---

1. Achsen

1.1 Preis immer auf der rechten Y-Achse, logarithmische Skala

Jede Vorlage, die den BTC-Preis überlagert, platziert den Preis auf einer separaten rechten Achse mit scale: "log". Die primäre Metrik liegt auf der linken Achse. Den Preis visuell zu verknüpfen, ihn aber numerisch zu trennen, hält sowohl schnell wachsende Metriken (Bestände, AUM, Supply) als auch den Preis lesbar.

Ausnahme: Preismodell-Vorlagen (realized_price, transferred_price) legen den Preis auf dieselbe Achse wie das Modell, damit Nutzer zwei Preise auf einer Skala vergleichen können. Diese Achse ist logarithmisch.

1.2 Metriken mit gleicher Einheit teilen sich eine Achse

• lth_supply + sth_supply → eine linke Achse (beide BTC).
• lth_mvrv + sth_mvrv → eine linke Achse (beide Verhältniszahlen).
• Funding Rate (%) links, Preis (USD) rechts — unterschiedliche Einheiten, unterschiedliche Achsen.

Stapeln Sie nicht zwei Metriken mit sehr unterschiedlichen Wertebereichen auf derselben linearen Achse. Die kleinere Datenreihe wird visuell erdrückt.

1.3 Zyklusvergleich: allLeftAxis: true + logarithmische Skala

Vorlagen zur Zyklus-Performance (z. B. cycle-perf-low, cycle-perf-ath, cycle-perf-halving) erzwingen allLeftAxis: true mit yAxes: [{ side: "left", scale: "log" }]. Mehrere Zyklen werden auf derselben logarithmischen Achse überlagert, sodass exponentielles Wachstum über die Zyklen hinweg vergleichbar ist.

1.4 Farbe der Achsenbeschriftung

• Mehrere unterschiedlich gefärbte Datenreihen, die sich eine Achse teilen → die Achsenbeschriftung ist neutrales Dunkelgrau #6b7280.
• Einzelne Metrik, die eine Achse für sich beansprucht → die Beschriftung kann die Farbe dieser Metrik übernehmen (selten verwendet; Grau ist die sichere Standardwahl).

---

2. Skalenauswahl

Linear verwenden	Log verwenden
Supplies, Flows, Anzahlen, USD-Werte, Marktkapitalisierung	BTC-Preis (immer)
Verhältniszahlen (MVRV, SOPR), Prozentsätze, Funding Rates	Aktienindizes, wenn allein dargestellt (SPY/QQQ/IWM)
Tägliche Deltas, Nettoveränderungen	Preismodelle (realized_price, transferred_price)
Alles, was in einem begrenzten Bereich schwankt	Überlagerungen zur Zyklus-Performance

Wenn eine Metrik über das sichtbare Fenster mehr als etwa 2 Größenordnungen umfasst, ist Log vorzuziehen.

---

3. Chart-Typ je Metrik

Stil	Wann	fillOpacity
area	Bestände, Supplies, kumulative Flows, AUM, gestapelte Kohorten	0.3
line	Verhältniszahlen (MVRV, SOPR), Raten (Funding), Preisüberlagerungen	0.1
bar	Tägliche / 30-Tage-Deltas (Netto-Flows, Supply 30D Δ)	0.5
candlestick	Nur OHLC	—

Balken auf einer logarithmischen Achse werden unleserlich dargestellt — halten Sie Balken linear.

---

4. Farbpalette

4.1 Nach Domäne

Domäne	Element	Hex
Preisüberlagerung	BTC-Preis (neutral)	#6b7280
Supply	LTH	#2563eb
Supply	STH	#dc2626
Supply	dritte Kohorte	#fbbf24 / #FFBB28
ETF	Bestände	#f59e0b
ETF	AUM	#3b82f6
ETF	Netto-Flow	#10b981
ETF	kumulativer Flow	#059669
ETF	Dominanz	#8b5cf6
ETF	US-Bestände	#3b82f6
ETF	Realized Price	#dc2626 / #ea580c
DAT	Gesamtbestände	#F7931A (Bitcoin-Markenfarbe)
DAT	börsennotierte Unternehmen	#0088FE
DAT	Regierungen	#FF4444
DAT	private Unternehmen	#FFBB28
DAT	Nettoveränderung	#82ca9d
DAT	Dominanz	#ff7300
Funding	Rate	#3b82f6
Funding	Spread	#f97316
Funding	überhitzte Zone	rgba(239,68,68,0.1)
Funding	Kapitulationszone	rgba(34,197,94,0.1)
Makro	Renditen (neutral)	#6b7280
Makro	Inflation	#f59e0b
Makro	VIX / Risiko	#ef4444
Zyklus 1→4	Violett → Blau → Grün → Orange	#8b5cf6 → #3b82f6 → #22c55e → #f97316

4.2 Färbung bei mehreren Metriken

Wenn zwei verwandte Kohorten gemeinsam auftreten (LTH/STH, US/Nicht-US, börsennotiert/privat), verwenden Sie das etablierte Paar (Blau + Rot für LTH/STH), damit Nutzer ein einziges mentales Modell erlernen. Erfinden Sie nicht für jedes Chart neue Paletten.

---

5. Referenzlinien und -flächen

Verwenden Sie diese nur, wenn der Schwellenwert eine klare Interpretation hat:

• Funding Rate > 20% → rot schattierte Fläche, Beschriftung „Overheated".
• Funding Rate < -10% → grün schattierte Fläche, Beschriftung „Capitulation".
• SOPR = 1.0 → Referenzlinie am Break-even (Verbesserungspotenzial — noch nicht in Vorlagen).
• MVRV = 1.0 → Referenzlinie bei Fair-Value-Parität.

Vermeiden Sie dekorative Linien ohne numerische Bedeutung. Maximal ein bis zwei Annotationen pro Chart.

"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. Standardwerte für den Datumsbereich

Voreinstellung	Wann
ALL	Langfristige Trendmetriken — Supply, Bewertung, Zyklusüberlagerungen, alles mit langer Historie, die Nutzer vollständig sehen möchten.
1Y	Verrauschte Metriken, bei denen Mehrjahresansichten das Signal verdecken — tägliche Netto-Flows, DAT-Nettoveränderung, Funding-Spread.
1W / 1M	Nie als Standard — dies sind nutzergesteuerte Zoom-Stufen.

---

7. Styling-Konstanten

Verwenden Sie diese überall, sofern es keinen chartspezifischen Grund gibt, davon abzuweichen:

• strokeWidth: 2 für alle Linien.
• fillOpacity: 0.3 für Flächen, 0.1 für Linienüberlagerungen, 0.5 für Balken.
• Format von instanceId: {metricId}-{seq} (z. B. price-1, lth_supply-1). Über Bearbeitungen hinweg stabil.

---

8. Namenskonventionen

• Chart-Name — Nominalphrase, wie eine Spaltenüberschrift in Title Case. ≤60 Zeichen. Keine Emojis.
  • Gut: BTC LTH Supply with 30D Change, ETF Net Flow vs. Price
  • Schlecht: 📈 Bitcoin Long-Term Holders!!! (2024)
• Beschreibung — ein Satz, der beschreibt, was das Chart zeigt und welche Erkenntnis es zutage fördert.
  • Gut: Long-term holder supply with 30-day delta bars to surface accumulation and distribution waves.

---

9. Anti-Patterns

Lehnen Sie diese bei der Prüfung einer Vorlage oder einer KI-generierten Konfiguration ab:

• Einzelne Metrik in einem Layout mit zwei Achsen — die leere Achse ist verschwendeter Platz.
• Mehr als 4 Datenreihen auf einer Achse ohne Stapelung — visuell unleserlich.
• Vermischung sehr unterschiedlicher Wertebereiche auf einer einzigen linearen Achse (z. B. Anzahlen von 1–2 Mio. mit Preis 20k–100k) — die kleinere Reihe ist unsichtbar.
• BTC-Preis auf einer linearen Achse, wenn er mit einer stark wachsenden Metrik gepaart ist — der Preis dominiert visuell.
• Dekorative Referenzlinien ohne numerische Bedeutung — fügen Rauschen hinzu, kein Signal.
• Balken auf einer logarithmischen Skala — werden unleserlich dargestellt.
• Chartspezifische Sonderpalette — bricht die vom Nutzer erlernten Farbzuordnungen.

---

10. Kurzreferenz für die lab-author-Skill

Wenn Buddy aus natürlicher Sprache eine Chart-Konfiguration erstellt:

1. Lösen Sie die Metrik-IDs über search_metrics / get_metric auf. Bestätigen Sie, dass der grade jeder Metrik innerhalb des Tarifs des Nutzers liegt.
2. Entscheiden Sie über das Achsenlayout:
   • Ist der BTC-Preis eine der Reihen? → Preis rechts mit scale: "log", primäre Metrik links.
   • Teilen sich die übrigen Metriken eine Einheit? → dieselbe Achse. Unterschiedliche Einheiten? → unterschiedliche Achsen.
3. Wählen Sie die Chart-Stile gemäß §3.
4. Wählen Sie die Farben gemäß §4.1 — verwenden Sie die etablierte Palette der jeweiligen Domäne.
5. Wählen Sie die Skala gemäß §2.
6. Wählen Sie den Datumsbereich gemäß §6.
7. Fügen Sie Referenzlinien/-flächen nur hinzu, wenn der Schwellenwert eine klare Bedeutung hat (§5).
8. Wenden Sie die Styling-Konstanten (§7) und die Namenskonventionen (§8) an.
9. Gehen Sie die Anti-Pattern-Checkliste (§9) durch, bevor Sie speichern.

---

11. Wo die Vorlagen liegen

• Statisch (Frontend) — chart-templates. ~70 Vorlagen, die beim App-Start geladen werden.
• Datenbank (Tabelle templates) — kuratierte Vorlagen, eingespielt durch template-seeds und bereitgestellt über the templates API.
• Nutzererstellt (Tabelle user-charts) — worum es im Rest dieses Leitfadens geht. Gespeichert über die Lab-Oberfläche, durch das Forken einer Vorlage oder über Buddys MCP-Tool save_chart.

Die Form des Konfigurations-JSON (metrics, formulas, yAxes, dateRange, referenceLines, referenceAreas usw.) ist über alle drei Quellen hinweg identisch — siehe the chart config in the Lab API client für die TypeScript-Definition und the API schema für das Pydantic-Schema.