Guida allo stile dei grafici

Questo è il riferimento canonico su come appare un "buon" grafico Blocklens. Distilla le regole espresse nei circa 70 template integrati (chart-templates), nei template inizializzati nel DB (template-seeds) e nel comportamento di rendering di the chart renderer.

Due tipi di destinatari:

Autori frontend / di template — applica queste regole quando progetti nuovi template o dati di inizializzazione.
La skill lab-author di Buddy — carica una copia condensata di queste regole affinché le configurazioni dei grafici generate dall'AI corrispondano al linguaggio visivo del catalogo curato.

Se una regola qui sotto contraddice ciò che un template fa attualmente, vince il template per ragioni di retrocompatibilità, ma il nuovo lavoro dovrebbe seguire questa guida.

1. Assi

1.1 Il prezzo sempre sull'asse Y destro, scala logaritmica

Ogni template che sovrappone il prezzo di BTC colloca il prezzo su un asse destro separato con scale: "log". La metrica primaria va sull'asse sinistro. Collegare il prezzo visivamente ma separarlo numericamente mantiene leggibili sia le metriche a rapida crescita (holdings, AUM, supply) sia il prezzo.

Eccezione: i template dei modelli di prezzo (realized_price, transferred_price) collocano il prezzo sullo stesso asse del modello, così gli utenti possono confrontare due prezzi su un'unica scala. Quell'asse è logaritmico.

1.2 Le metriche che condividono un'unità condividono un asse

lth_supply + sth_supply → un asse sinistro (entrambe in BTC).
lth_mvrv + sth_mvrv → un asse sinistro (entrambi rapporti).
Funding rate (%) a sinistra, prezzo (USD) a destra — unità diverse, assi diversi.

Non sovrapporre due metriche con intervalli molto diversi sullo stesso asse lineare. La serie più piccola risulterà visivamente compressa.

1.3 Confronto tra cicli: `allLeftAxis: true` + scala logaritmica

I template di cycle-performance (ad es. cycle-perf-low, cycle-perf-ath, cycle-perf-halving) forzano allLeftAxis: true con yAxes: [{ side: "left", scale: "log" }]. Più cicli si sovrappongono sullo stesso asse logaritmico, così la crescita esponenziale è confrontabile tra i cicli.

1.4 Colore dell'etichetta dell'asse

Più serie di colori diversi che condividono un asse → l'etichetta dell'asse è grigio scuro neutro #6b7280.
Singola metrica che possiede un asse → l'etichetta può ereditare il colore di quella metrica (usato raramente; il grigio è l'impostazione predefinita sicura).

2. Selezione della scala

Usa lineare	Usa logaritmica
Supply, flussi, conteggi, valori in USD, market cap	Prezzo di BTC (sempre)
Rapporti (MVRV, SOPR), percentuali, funding rate	Indici azionari quando mostrati da soli (SPY/QQQ/IWM)
Delta giornalieri, variazioni nette	Modelli di prezzo (`realized_price`, `transferred_price`)
Tutto ciò che oscilla in un intervallo limitato	Sovrapposizioni di cycle-performance

Se una metrica copre più di ~2 ordini di grandezza nella finestra visibile, preferisci la scala logaritmica.

3. Tipo di grafico per metrica

Stile	Quando	`fillOpacity`
`area`	Holdings, supply, flussi cumulativi, AUM, coorti impilate	`0.3`
`line`	Rapporti (MVRV, SOPR), tassi (funding), sovrapposizioni di prezzo	`0.1`
`bar`	Delta giornalieri / a 30 giorni (flussi netti, supply 30D Δ)	`0.5`
`candlestick`	Solo OHLC	—

Le barre su un asse logaritmico risultano illeggibili — mantieni le barre lineari.

4. Palette di colori

4.1 Per dominio

Dominio	Elemento	Hex
Sovrapposizione prezzo	Prezzo BTC (neutro)	`#6b7280`
Supply	LTH	`#2563eb`
Supply	STH	`#dc2626`
Supply	terza coorte	`#fbbf24` / `#FFBB28`
ETF	holdings	`#f59e0b`
ETF	AUM	`#3b82f6`
ETF	flusso netto	`#10b981`
ETF	flusso cumulativo	`#059669`
ETF	dominanza	`#8b5cf6`
ETF	holdings USA	`#3b82f6`
ETF	realized price	`#dc2626` / `#ea580c`
DAT	holdings totali	`#F7931A` (colore brand Bitcoin)
DAT	società quotate	`#0088FE`
DAT	governi	`#FF4444`
DAT	società private	`#FFBB28`
DAT	variazione netta	`#82ca9d`
DAT	dominanza	`#ff7300`
Funding	rate	`#3b82f6`
Funding	spread	`#f97316`
Funding	zona di surriscaldamento	`rgba(239,68,68,0.1)`
Funding	zona di capitolazione	`rgba(34,197,94,0.1)`
Macro	rendimenti (neutro)	`#6b7280`
Macro	inflazione	`#f59e0b`
Macro	VIX / rischio	`#ef4444`
Ciclo 1→4	viola → blu → verde → arancione	`#8b5cf6` → `#3b82f6` → `#22c55e` → `#f97316`

4.2 Colorazione multi-metrica

Quando due coorti correlate appaiono insieme (LTH/STH, USA/non-USA, quotate/private), usa la coppia consolidata (blu + rosso per LTH/STH), così gli utenti imparano un unico modello mentale. Non reinventare le palette per ogni grafico.

5. Linee e aree di riferimento

Usale solo quando la soglia ha un'interpretazione chiara:

Funding rate > 20% → area ombreggiata in rosso, etichetta "Surriscaldamento".
Funding rate < -10% → area ombreggiata in verde, etichetta "Capitolazione".
SOPR = 1.0 → linea di riferimento al punto di pareggio (opportunità — non ancora nei template).
MVRV = 1.0 → linea di riferimento alla parità del fair value.

Evita le linee decorative prive di significato numerico. Una o due annotazioni per grafico al massimo.

"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. Intervalli di date predefiniti

Preset	Quando
`ALL`	Metriche di tendenza a lungo termine — supply, valutazione, sovrapposizioni di cicli, qualsiasi cosa con una lunga storia che gli utenti vogliono vedere per intero.
`1Y`	Metriche rumorose in cui le viste pluriennali oscurano il segnale — flussi netti giornalieri, variazione netta DAT, funding spread.
`1W` / `1M`	Mai come predefinito — sono livelli di zoom guidati dall'utente.

7. Costanti di stile

Usale ovunque a meno che non vi sia una ragione specifica del grafico per non farlo:

strokeWidth: 2 per tutte le linee.
fillOpacity: 0.3 per le aree, 0.1 per le sovrapposizioni di linea, 0.5 per le barre.
Formato instanceId: {metricId}-{seq} (ad es. price-1, lth_supply-1). Resta stabile tra una modifica e l'altra.

8. Convenzioni di denominazione

Nome del grafico — locuzione nominale, con le iniziali maiuscole come l'intestazione di una colonna. ≤60 caratteri. Niente emoji.
- Buono: BTC LTH Supply with 30D Change, ETF Net Flow vs. Price
- Cattivo: 📈 Bitcoin Long-Term Holders!!! (2024)
Descrizione — una frase che descrive ciò che il grafico mostra e l'insight che fa emergere.
- Buono: Long-term holder supply with 30-day delta bars to surface accumulation and distribution waves.

9. Anti-pattern

Rifiutali quando esamini un template o una configurazione generata dall'AI:

Singola metrica su un layout a due assi — l'asse vuoto è spazio sprecato.
Più di 4 serie su un asse senza impilamento — visivamente illeggibile.
Mescolare intervalli molto diversi su un singolo asse lineare (ad es. conteggi da 1-2M con prezzo da 20k-100k) — la serie più piccola è invisibile.
Prezzo di BTC su un asse lineare quando abbinato a una metrica ad alta crescita — il prezzo dominerà visivamente.
Linee di riferimento decorative prive di significato numerico — aggiungono rumore, non segnale.
Barre su una scala logaritmica — risultano illeggibili.
Palette su misura per ogni grafico — interrompe le associazioni di colore apprese dall'utente.

10. Riferimento rapido per la skill `lab-author`

Quando Buddy costruisce una configurazione di grafico a partire dal linguaggio naturale:

Risolvi gli ID delle metriche tramite search_metrics / get_metric. Conferma che il grade di ciascuna metrica rientri nel tier dell'utente.
Decidi il layout degli assi:
- Il prezzo di BTC è una delle serie? → prezzo a destra con scale: "log", primaria a sinistra.
- Le metriche rimanenti condividono un'unità? → stesso asse. Unità diverse? → assi diversi.
Scegli gli stili di grafico secondo il §3.
Scegli i colori secondo il §4.1 — usa la palette consolidata per il dominio.
Scegli la scala secondo il §2.
Scegli l'intervallo di date secondo il §6.
Aggiungi linee/aree di riferimento solo quando la soglia ha un significato chiaro (§5).
Applica le costanti di stile (§7) e le convenzioni di denominazione (§8).
Esegui la checklist degli anti-pattern (§9) prima di salvare.

11. Dove risiedono i template

Statici (frontend) — chart-templates. ~70 template caricati all'avvio dell'app.
Database (tabella templates) — template curati inizializzati da template-seeds ed esposti tramite the templates API.
Creati dall'utente (tabella user-charts) — l'argomento del resto di questa guida. Salvati tramite l'interfaccia di Lab, tramite il fork di un template o tramite lo strumento MCP save_chart di Buddy.

La forma JSON della configurazione (metrics, formulas, yAxes, dateRange, referenceLines, referenceAreas, ecc.) è identica in tutte e tre le fonti — vedi the chart config in the Lab API client per la definizione TypeScript e the API schema per lo schema Pydantic.

1. Assi​

1.1 Il prezzo sempre sull'asse Y destro, scala logaritmica​

1.2 Le metriche che condividono un'unità condividono un asse​

1.3 Confronto tra cicli: allLeftAxis: true + scala logaritmica​

1.4 Colore dell'etichetta dell'asse​

2. Selezione della scala​

3. Tipo di grafico per metrica​

4. Palette di colori​

4.1 Per dominio​

4.2 Colorazione multi-metrica​

5. Linee e aree di riferimento​

6. Intervalli di date predefiniti​

7. Costanti di stile​

8. Convenzioni di denominazione​

9. Anti-pattern​

10. Riferimento rapido per la skill lab-author​

11. Dove risiedono i template​