Guía de estilo de gráficos

Esta es la referencia canónica sobre cómo debe verse un "buen" gráfico de Blocklens. Sintetiza las reglas expresadas en las ~70 plantillas integradas (chart-templates), las plantillas sembradas en la base de datos (template-seeds) y el comportamiento de renderizado de the chart renderer.

Dos audiencias:

Autores de plantillas / frontend — apliquen estas reglas al diseñar nuevas plantillas o datos de siembra.
La skill lab-author de Buddy — carga una copia condensada de estas reglas para que las configuraciones de gráficos generadas por IA coincidan con el lenguaje visual del catálogo curado.

Si una regla a continuación contradice lo que una plantilla hace actualmente, la plantilla prevalece por razones heredadas, pero el trabajo nuevo debe seguir esta guía.

1. Ejes

1.1 El precio siempre en el eje Y derecho, escala logarítmica

Toda plantilla que superpone el precio de BTC coloca el precio en un eje derecho separado con scale: "log". La métrica principal va en el eje izquierdo. Vincular el precio visualmente pero separarlo numéricamente mantiene legibles tanto las métricas de rápido crecimiento (tenencias, AUM, oferta) como el precio.

Excepción: las plantillas de modelos de precio (realized_price, transferred_price) colocan el precio en el mismo eje que el modelo para que los usuarios puedan comparar dos precios en una sola escala. Ese eje es logarítmico.

1.2 Las métricas que comparten unidad comparten eje

lth_supply + sth_supply → un eje izquierdo (ambas en BTC).
lth_mvrv + sth_mvrv → un eje izquierdo (ambos ratios).
Funding rate (%) a la izquierda, precio (USD) a la derecha — unidades distintas, ejes distintos.

No apile dos métricas con rangos muy distintos en el mismo eje lineal. La serie más pequeña quedará visualmente aplastada.

1.3 Comparación de ciclos: `allLeftAxis: true` + escala logarítmica

Las plantillas de rendimiento por ciclo (p. ej. cycle-perf-low, cycle-perf-ath, cycle-perf-halving) fuerzan allLeftAxis: true con yAxes: [{ side: "left", scale: "log" }]. Múltiples ciclos se superponen en el mismo eje logarítmico para que el crecimiento exponencial sea comparable entre ciclos.

1.4 Color de la etiqueta del eje

Múltiples series de distinto color que comparten un eje → la etiqueta del eje es gris oscuro neutro #6b7280.
Una sola métrica que posee un eje → la etiqueta puede heredar el color de esa métrica (se usa rara vez; el gris es la opción segura por defecto).

2. Selección de escala

Usar lineal	Usar logarítmica
Oferta, flujos, conteos, valores en USD, capitalización de mercado	Precio de BTC (siempre)
Ratios (MVRV, SOPR), porcentajes, funding rates	Índices bursátiles cuando se muestran solos (SPY/QQQ/IWM)
Variaciones diarias, cambios netos	Modelos de precio (`realized_price`, `transferred_price`)
Cualquier cosa que fluctúe en un rango acotado	Superposiciones de rendimiento por ciclo

Si una métrica abarca más de ~2 órdenes de magnitud en la ventana visible, prefiera la escala logarítmica.

3. Tipo de gráfico por métrica

Estilo	Cuándo	`fillOpacity`
`area`	Tenencias, oferta, flujos acumulados, AUM, cohortes apiladas	`0.3`
`line`	Ratios (MVRV, SOPR), tasas (funding), superposiciones de precio	`0.1`
`bar`	Variaciones diarias / a 30 días (flujos netos, oferta Δ 30D)	`0.5`
`candlestick`	Solo OHLC	—

Las barras sobre un eje logarítmico se renderizan de forma ilegible — mantenga las barras en escala lineal.

4. Paleta de colores

4.1 Por dominio

Dominio	Elemento	Hex
Superposición de precio	Precio de BTC (neutro)	`#6b7280`
Oferta	LTH	`#2563eb`
Oferta	STH	`#dc2626`
Oferta	tercera cohorte	`#fbbf24` / `#FFBB28`
ETF	tenencias	`#f59e0b`
ETF	AUM	`#3b82f6`
ETF	flujo neto	`#10b981`
ETF	flujo acumulado	`#059669`
ETF	dominancia	`#8b5cf6`
ETF	tenencias en EE. UU.	`#3b82f6`
ETF	realized price	`#dc2626` / `#ea580c`
DAT	tenencias totales	`#F7931A` (color de marca de Bitcoin)
DAT	empresas públicas	`#0088FE`
DAT	gobiernos	`#FF4444`
DAT	empresas privadas	`#FFBB28`
DAT	cambio neto	`#82ca9d`
DAT	dominancia	`#ff7300`
Funding	tasa	`#3b82f6`
Funding	spread	`#f97316`
Funding	zona de sobrecalentamiento	`rgba(239,68,68,0.1)`
Funding	zona de capitulación	`rgba(34,197,94,0.1)`
Macro	rendimientos (neutro)	`#6b7280`
Macro	inflación	`#f59e0b`
Macro	VIX / riesgo	`#ef4444`
Ciclo 1→4	violeta → azul → verde → naranja	`#8b5cf6` → `#3b82f6` → `#22c55e` → `#f97316`

4.2 Coloreado multimétrica

Cuando dos cohortes relacionadas aparecen juntas (LTH/STH, EE. UU./no EE. UU., públicas/privadas), use el par establecido (azul + rojo para LTH/STH) para que los usuarios aprendan un único modelo mental. No reinvente las paletas en cada gráfico.

5. Líneas y áreas de referencia

Úselas solo cuando el umbral tenga una interpretación clara:

Funding rate > 20% → área sombreada en rojo, etiqueta "Overheated".
Funding rate < -10% → área sombreada en verde, etiqueta "Capitulation".
SOPR = 1.0 → línea de referencia en el punto de equilibrio (oportunidad — aún no presente en las plantillas).
MVRV = 1.0 → línea de referencia en la paridad de valor justo.

Evite las líneas decorativas sin significado numérico. Una o dos anotaciones por gráfico como máximo.

"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. Rangos de fechas por defecto

Preajuste	Cuándo
`ALL`	Métricas de tendencia larga — oferta, valoración, superposiciones de ciclos, cualquier cosa con un historial largo que los usuarios quieran ver completo.
`1Y`	Métricas ruidosas donde las vistas plurianuales ocultan la señal — flujos netos diarios, cambio neto de DAT, spread de funding.
`1W` / `1M`	Nunca por defecto — son niveles de zoom que controla el usuario.

7. Constantes de estilo

Use estas en todas partes salvo que haya una razón específica del gráfico para no hacerlo:

strokeWidth: 2 para todas las líneas.
fillOpacity: 0.3 para áreas, 0.1 para superposiciones de línea, 0.5 para barras.
Formato de instanceId: {metricId}-{seq} (p. ej. price-1, lth_supply-1). Estable entre ediciones.

8. Convenciones de nomenclatura

Nombre del gráfico — sintagma nominal, en mayúsculas tipo título como un encabezado de columna. ≤60 caracteres. Sin emojis.
- Bien: BTC LTH Supply with 30D Change, ETF Net Flow vs. Price
- Mal: 📈 Bitcoin Long-Term Holders!!! (2024)
Descripción — una oración que describa qué muestra el gráfico y la idea que revela.
- Bien: Long-term holder supply with 30-day delta bars to surface accumulation and distribution waves.

9. Antipatrones

Rechácelos al revisar una plantilla o una configuración generada por IA:

Una sola métrica en un diseño de dos ejes — el eje vacío es espacio desperdiciado.
Más de 4 series en un eje sin apilar — visualmente ilegible.
Mezclar rangos muy distintos en un único eje lineal (p. ej. conteos de 1-2M con precio de 20k-100k) — la serie más pequeña es invisible.
Precio de BTC en un eje lineal cuando se combina con una métrica de alto crecimiento — el precio dominará visualmente.
Líneas de referencia decorativas sin significado numérico — añaden ruido, no señal.
Barras en escala logarítmica — se renderizan de forma ilegible.
Paleta a medida por gráfico — rompe las asociaciones de color aprendidas por el usuario.

10. Referencia rápida para la skill `lab-author`

Cuando Buddy construye una configuración de gráfico a partir de lenguaje natural:

Resuelva los IDs de métrica mediante search_metrics / get_metric. Confirme que el grade de cada métrica está dentro del nivel del usuario.
Decida el diseño de ejes:
- ¿Es el precio de BTC una de las series? → precio a la derecha con scale: "log", principal a la izquierda.
- ¿Las métricas restantes comparten unidad? → mismo eje. ¿Unidades distintas? → ejes distintos.
Elija los estilos de gráfico según §3.
Elija los colores según §4.1 — use la paleta establecida para el dominio.
Elija la escala según §2.
Elija el rango de fechas según §6.
Añada líneas/áreas de referencia solo cuando el umbral tenga un significado claro (§5).
Aplique las constantes de estilo (§7) y las convenciones de nomenclatura (§8).
Ejecute la lista de verificación de antipatrones (§9) antes de guardar.

11. Dónde viven las plantillas

Estáticas (frontend) — chart-templates. ~70 plantillas cargadas al iniciar la app.
Base de datos (tabla templates) — plantillas curadas sembradas por template-seeds y expuestas mediante the templates API.
Creadas por el usuario (tabla user-charts) — de lo que trata el resto de esta guía. Se guardan a través de la interfaz de Lab, al bifurcar una plantilla, o mediante la herramienta MCP save_chart de Buddy.

La estructura del JSON de configuración (metrics, formulas, yAxes, dateRange, referenceLines, referenceAreas, etc.) es idéntica en las tres fuentes — consulte the chart config en the Lab API client para la definición de TypeScript y the API schema para el esquema de Pydantic.

1. Ejes​

1.1 El precio siempre en el eje Y derecho, escala logarítmica​

1.2 Las métricas que comparten unidad comparten eje​

1.3 Comparación de ciclos: allLeftAxis: true + escala logarítmica​

1.4 Color de la etiqueta del eje​

2. Selección de escala​

3. Tipo de gráfico por métrica​

4. Paleta de colores​

4.1 Por dominio​

4.2 Coloreado multimétrica​

5. Líneas y áreas de referencia​

6. Rangos de fechas por defecto​

7. Constantes de estilo​

8. Convenciones de nomenclatura​

9. Antipatrones​

10. Referencia rápida para la skill lab-author​

11. Dónde viven las plantillas​