Guide de style des graphiques

Ce document est la référence canonique décrivant à quoi ressemble un « bon » graphique Blocklens. Il synthétise les règles exprimées dans les ~70 modèles intégrés (chart-templates), les modèles initialisés en base de données (template-seeds) et le comportement de rendu d'the chart renderer.

Deux publics :

Auteurs de modèles / front-end — appliquez ces règles lors de la conception de nouveaux modèles ou de données initiales.
La compétence lab-author de Buddy — charge une copie condensée de ces règles afin que les configurations de graphiques générées par l'IA correspondent au langage visuel du catalogue organisé.

Si une règle ci-dessous contredit le comportement actuel d'un modèle, le modèle l'emporte pour des raisons historiques, mais tout nouveau travail doit suivre ce guide.

1. Axes

1.1 Le prix toujours sur l'axe Y de droite, en échelle logarithmique

Chaque modèle qui superpose le prix du BTC place le prix sur un axe de droite distinct avec scale: "log". La métrique principale se trouve sur l'axe de gauche. Lier visuellement le prix tout en le séparant numériquement permet de garder lisibles à la fois le prix et les métriques à croissance rapide (avoirs, AUM, offre).

Exception : les modèles de prix (realized_price, transferred_price) placent le prix sur le même axe que le modèle, afin que les utilisateurs puissent comparer deux prix sur une seule échelle. Cet axe est logarithmique.

1.2 Les métriques qui partagent une unité partagent un axe

lth_supply + sth_supply → un seul axe de gauche (les deux en BTC).
lth_mvrv + sth_mvrv → un seul axe de gauche (les deux sont des ratios).
Taux de financement (%) à gauche, prix (USD) à droite — unités différentes, axes différents.

N'empilez pas deux métriques aux plages très différentes sur le même axe linéaire. La série la plus petite sera visuellement écrasée.

1.3 Comparaison de cycles : `allLeftAxis: true` + échelle logarithmique

Les modèles de performance de cycle (p. ex. cycle-perf-low, cycle-perf-ath, cycle-perf-halving) imposent allLeftAxis: true avec yAxes: [{ side: "left", scale: "log" }]. Plusieurs cycles se superposent sur le même axe logarithmique, de sorte que la croissance exponentielle est comparable d'un cycle à l'autre.

1.4 Couleur des étiquettes d'axe

Plusieurs séries de couleurs différentes partageant un axe → l'étiquette de l'axe est en gris foncé neutre #6b7280.
Une seule métrique possédant un axe → l'étiquette peut hériter de la couleur de cette métrique (rarement utilisé ; le gris est la valeur par défaut sûre).

2. Choix de l'échelle

Utiliser une échelle linéaire	Utiliser une échelle logarithmique
Offres, flux, comptages, valeurs en USD, capitalisation boursière	Prix du BTC (toujours)
Ratios (MVRV, SOPR), pourcentages, taux de financement	Indices actions affichés seuls (SPY/QQQ/IWM)
Variations quotidiennes, variations nettes	Modèles de prix (`realized_price`, `transferred_price`)
Tout ce qui fluctue dans une plage bornée	Superpositions de performance de cycle

Si une métrique couvre plus de ~2 ordres de grandeur sur la fenêtre visible, préférez l'échelle logarithmique.

3. Type de graphique par métrique

Style	Quand	`fillOpacity`
`area`	Avoirs, offres, flux cumulés, AUM, cohortes empilées	`0.3`
`line`	Ratios (MVRV, SOPR), taux (financement), superpositions de prix	`0.1`
`bar`	Variations quotidiennes / sur 30 jours (flux nets, Δ d'offre sur 30 J)	`0.5`
`candlestick`	OHLC uniquement	—

Les barres sur un axe logarithmique sont illisibles — gardez les barres en échelle linéaire.

4. Palette de couleurs

4.1 Par domaine

Domaine	Élément	Hex
Superposition de prix	Prix du BTC (neutre)	`#6b7280`
Offre	LTH	`#2563eb`
Offre	STH	`#dc2626`
Offre	troisième cohorte	`#fbbf24` / `#FFBB28`
ETF	avoirs	`#f59e0b`
ETF	AUM	`#3b82f6`
ETF	flux net	`#10b981`
ETF	flux cumulé	`#059669`
ETF	dominance	`#8b5cf6`
ETF	avoirs US	`#3b82f6`
ETF	prix réalisé	`#dc2626` / `#ea580c`
DAT	avoirs totaux	`#F7931A` (couleur de marque Bitcoin)
DAT	sociétés cotées	`#0088FE`
DAT	gouvernements	`#FF4444`
DAT	sociétés privées	`#FFBB28`
DAT	variation nette	`#82ca9d`
DAT	dominance	`#ff7300`
Financement	taux	`#3b82f6`
Financement	écart	`#f97316`
Financement	zone de surchauffe	`rgba(239,68,68,0.1)`
Financement	zone de capitulation	`rgba(34,197,94,0.1)`
Macro	rendements (neutre)	`#6b7280`
Macro	inflation	`#f59e0b`
Macro	VIX / risque	`#ef4444`
Cycle 1→4	violet → bleu → vert → orange	`#8b5cf6` → `#3b82f6` → `#22c55e` → `#f97316`

4.2 Coloration multi-métriques

Lorsque deux cohortes liées apparaissent ensemble (LTH/STH, US/non-US, cotées/privées), utilisez la paire établie (bleu + rouge pour LTH/STH) afin que les utilisateurs apprennent un seul modèle mental. Ne réinventez pas les palettes pour chaque graphique.

5. Lignes et zones de référence

Utilisez-les uniquement lorsque le seuil a une interprétation claire :

Taux de financement > 20% → zone ombrée en rouge, étiquette « Surchauffe ».
Taux de financement < -10% → zone ombrée en vert, étiquette « Capitulation ».
SOPR = 1.0 → ligne de référence au seuil de rentabilité (opportunité — pas encore dans les modèles).
MVRV = 1.0 → ligne de référence à la parité de juste valeur.

Évitez les lignes décoratives sans signification numérique. Une ou deux annotations par graphique au maximum.

"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. Plages de dates par défaut

Préréglage	Quand
`ALL`	Métriques de tendance longue — offre, valorisation, superpositions de cycles, tout ce qui possède un long historique que les utilisateurs veulent voir en entier.
`1Y`	Métriques bruitées où les vues pluriannuelles masquent le signal — flux nets quotidiens, variation nette DAT, écart de financement.
`1W` / `1M`	Jamais par défaut — ce sont des niveaux de zoom pilotés par l'utilisateur.

7. Constantes de style

Utilisez-les partout, sauf raison spécifique à un graphique :

strokeWidth: 2 pour toutes les lignes.
fillOpacity: 0.3 pour les aires, 0.1 pour les superpositions de lignes, 0.5 pour les barres.
Format d'instanceId : {metricId}-{seq} (p. ex. price-1, lth_supply-1). Stable d'une modification à l'autre.

8. Conventions de nommage

Nom du graphique — groupe nominal, en casse de titre comme un en-tête de colonne. ≤60 caractères. Pas d'emojis.
- Bon : BTC LTH Supply with 30D Change, ETF Net Flow vs. Price
- Mauvais : 📈 Bitcoin Long-Term Holders!!! (2024)
Description — une phrase décrivant ce que montre le graphique et l'enseignement qu'il met en évidence.
- Bon : Long-term holder supply with 30-day delta bars to surface accumulation and distribution waves.

9. Anti-modèles

Rejetez ces éléments lors de la revue d'un modèle ou d'une configuration générée par l'IA :

Une seule métrique sur une disposition à deux axes — l'axe vide est de l'espace gaspillé.
Plus de 4 séries sur un axe sans empilement — visuellement illisible.
Mélanger des plages très différentes sur un seul axe linéaire (p. ex. des comptages de 1 à 2 M avec un prix de 20 k à 100 k) — la série la plus petite devient invisible.
Prix du BTC sur un axe linéaire lorsqu'il est associé à une métrique à forte croissance — le prix dominera visuellement.
Lignes de référence décoratives sans signification numérique — ajoute du bruit, pas du signal.
Barres sur une échelle logarithmique — rendu illisible.
Palette sur mesure par graphique — casse les associations de couleurs apprises par l'utilisateur.

10. Référence rapide pour la compétence `lab-author`

Lorsque Buddy construit une configuration de graphique à partir du langage naturel :

Résolvez les identifiants de métriques via search_metrics / get_metric. Vérifiez que le grade de chaque métrique est compris dans le palier de l'utilisateur.
Décidez de la disposition des axes :
- Le prix du BTC fait-il partie des séries ? → prix à droite avec scale: "log", principale à gauche.
- Les métriques restantes partagent-elles une unité ? → même axe. Unités différentes ? → axes différents.
Choisissez les styles de graphique selon le §3.
Choisissez les couleurs selon le §4.1 — utilisez la palette établie pour le domaine.
Choisissez l'échelle selon le §2.
Choisissez la plage de dates selon le §6.
N'ajoutez des lignes/zones de référence que lorsque le seuil a une signification claire (§5).
Appliquez les constantes de style (§7) et les conventions de nommage (§8).
Exécutez la liste de contrôle des anti-modèles (§9) avant d'enregistrer.

11. Où se trouvent les modèles

Statiques (front-end) — chart-templates. ~70 modèles chargés au démarrage de l'application.
Base de données (table templates) — modèles organisés initialisés par template-seeds et exposés via the templates API.
Créés par l'utilisateur (table user-charts) — ce dont traite le reste de ce guide. Enregistrés via l'interface du Lab, en dérivant un modèle, ou par l'outil MCP save_chart de Buddy.

La forme du JSON de configuration (metrics, formulas, yAxes, dateRange, referenceLines, referenceAreas, etc.) est identique pour les trois sources — voir the chart config dans the Lab API client pour la définition TypeScript et the API schema pour le schéma Pydantic.

1. Axes​

1.1 Le prix toujours sur l'axe Y de droite, en échelle logarithmique​

1.2 Les métriques qui partagent une unité partagent un axe​

1.3 Comparaison de cycles : allLeftAxis: true + échelle logarithmique​

1.4 Couleur des étiquettes d'axe​

2. Choix de l'échelle​

3. Type de graphique par métrique​

4. Palette de couleurs​

4.1 Par domaine​

4.2 Coloration multi-métriques​

5. Lignes et zones de référence​

6. Plages de dates par défaut​

7. Constantes de style​

8. Conventions de nommage​

9. Anti-modèles​

10. Référence rapide pour la compétence lab-author​

11. Où se trouvent les modèles​