Manual de Estilo de Gráficos

Esta é a referência canônica de como é um gráfico Blocklens "bom". Ela sintetiza as regras expressas nos ~70 modelos integrados (chart-templates), nos modelos populados no banco de dados (template-seeds) e no comportamento de renderização do the chart renderer.

Dois públicos:

Autores de frontend / modelos — apliquem estas regras ao projetar novos modelos ou dados de seed.
A skill lab-author do Buddy — carrega uma cópia condensada destas regras para que as configurações de gráfico geradas por IA correspondam à linguagem visual do catálogo curado.

Se uma regra abaixo contradisser o que um modelo faz atualmente, o modelo prevalece por questões de compatibilidade, mas novos trabalhos devem seguir este guia.

1. Eixos

1.1 O preço sempre no eixo Y direito, escala logarítmica

Todo modelo que sobrepõe o preço do BTC coloca o preço em um eixo direito separado com scale: "log". A métrica primária vai no eixo esquerdo. Vincular o preço visualmente mas separá-lo numericamente mantém legíveis tanto as métricas de crescimento rápido (holdings, AUM, supply) quanto o preço.

Exceção: modelos de preço (realized_price, transferred_price) colocam o preço no mesmo eixo do modelo, para que os usuários possam comparar dois preços em uma só escala. Esse eixo é logarítmico.

1.2 Métricas que compartilham uma unidade compartilham um eixo

lth_supply + sth_supply → um eixo esquerdo (ambos em BTC).
lth_mvrv + sth_mvrv → um eixo esquerdo (ambos razões).
Funding rate (%) à esquerda, preço (USD) à direita — unidades diferentes, eixos diferentes.

Não empilhe duas métricas com faixas muito diferentes no mesmo eixo linear. A série menor ficará visualmente esmagada.

1.3 Comparação de ciclos: `allLeftAxis: true` + escala logarítmica

Os modelos de desempenho de ciclo (por exemplo, cycle-perf-low, cycle-perf-ath, cycle-perf-halving) forçam allLeftAxis: true com yAxes: [{ side: "left", scale: "log" }]. Múltiplos ciclos se sobrepõem no mesmo eixo logarítmico, de modo que o crescimento exponencial seja comparável entre ciclos.

1.4 Cor do rótulo do eixo

Múltiplas séries de cores diferentes compartilhando um eixo → o rótulo do eixo é cinza-escuro neutro #6b7280.
Uma única métrica que possui um eixo → o rótulo pode herdar a cor dessa métrica (usado raramente; cinza é o padrão seguro).

2. Seleção de escala

Use linear	Use logarítmica
Supplies, fluxos, contagens, valores em USD, market cap	Preço do BTC (sempre)
Razões (MVRV, SOPR), percentuais, funding rates	Índices de ações quando exibidos sozinhos (SPY/QQQ/IWM)
Deltas diários, variações líquidas	Modelos de preço (`realized_price`, `transferred_price`)
Qualquer coisa que oscile dentro de uma faixa limitada	Sobreposições de desempenho de ciclo

Se uma métrica abrange mais de ~2 ordens de magnitude na janela visível, prefira logarítmica.

3. Tipo de gráfico por métrica

Estilo	Quando	`fillOpacity`
`area`	Holdings, supplies, fluxos cumulativos, AUM, coortes empilhadas	`0.3`
`line`	Razões (MVRV, SOPR), taxas (funding), sobreposições de preço	`0.1`
`bar`	Deltas diários / de 30 dias (fluxos líquidos, supply 30D Δ)	`0.5`
`candlestick`	Apenas OHLC	—

Barras em um eixo logarítmico ficam ilegíveis — mantenha as barras lineares.

4. Paleta de cores

4.1 Por domínio

Domínio	Elemento	Hex
Sobreposição de preço	Preço do BTC (neutro)	`#6b7280`
Supply	LTH	`#2563eb`
Supply	STH	`#dc2626`
Supply	terceira coorte	`#fbbf24` / `#FFBB28`
ETF	holdings	`#f59e0b`
ETF	AUM	`#3b82f6`
ETF	fluxo líquido	`#10b981`
ETF	fluxo cumulativo	`#059669`
ETF	dominância	`#8b5cf6`
ETF	holdings dos EUA	`#3b82f6`
ETF	realized price	`#dc2626` / `#ea580c`
DAT	total de holdings	`#F7931A` (marca Bitcoin)
DAT	empresas de capital aberto	`#0088FE`
DAT	governos	`#FF4444`
DAT	empresas privadas	`#FFBB28`
DAT	variação líquida	`#82ca9d`
DAT	dominância	`#ff7300`
Funding	rate	`#3b82f6`
Funding	spread	`#f97316`
Funding	zona de sobreaquecimento	`rgba(239,68,68,0.1)`
Funding	zona de capitulação	`rgba(34,197,94,0.1)`
Macro	yields (neutro)	`#6b7280`
Macro	inflação	`#f59e0b`
Macro	VIX / risco	`#ef4444`
Ciclo 1→4	violeta → azul → verde → laranja	`#8b5cf6` → `#3b82f6` → `#22c55e` → `#f97316`

4.2 Coloração de múltiplas métricas

Quando duas coortes relacionadas aparecem juntas (LTH/STH, EUA/não-EUA, público/privado), use o par estabelecido (azul + vermelho para LTH/STH), para que os usuários aprendam um único modelo mental. Não reinvente paletas a cada gráfico.

5. Linhas e áreas de referência

Use-as somente quando o limiar tem uma interpretação clara:

Funding rate > 20% → área sombreada em vermelho, rótulo "Sobreaquecido".
Funding rate < -10% → área sombreada em verde, rótulo "Capitulação".
SOPR = 1.0 → linha de referência no ponto de equilíbrio (oportunidade — ainda não presente nos modelos).
MVRV = 1.0 → linha de referência na paridade de valor justo.

Evite linhas decorativas sem significado numérico. No máximo uma ou duas anotações por gráfico.

"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. Padrões de intervalo de datas

Predefinição	Quando
`ALL`	Métricas de tendência longa — supply, valuation, sobreposições de ciclo, qualquer coisa com um histórico longo que os usuários queiram ver por completo.
`1Y`	Métricas ruidosas em que visões plurianuais obscurecem o sinal — fluxos líquidos diários, variação líquida de DAT, funding spread.
`1W` / `1M`	Nunca como padrão — estes são níveis de zoom controlados pelo usuário.

7. Constantes de estilo

Use-as em todo lugar, a menos que haja um motivo específico do gráfico para não usar:

strokeWidth: 2 para todas as linhas.
fillOpacity: 0.3 para áreas, 0.1 para sobreposições de linha, 0.5 para barras.
Formato de instanceId: {metricId}-{seq} (por exemplo, price-1, lth_supply-1). Estável entre edições.

8. Convenções de nomenclatura

Nome do gráfico — frase nominal, em maiúsculas iniciais como um cabeçalho de coluna. ≤60 caracteres. Sem emojis.
- Bom: BTC LTH Supply with 30D Change, ETF Net Flow vs. Price
- Ruim: 📈 Bitcoin Long-Term Holders!!! (2024)
Descrição — uma frase descrevendo o que o gráfico mostra e o insight que ele revela.
- Bom: Long-term holder supply with 30-day delta bars to surface accumulation and distribution waves.

9. Antipadrões

Rejeite estes ao revisar um modelo ou uma configuração gerada por IA:

Uma única métrica em um layout de dois eixos — o eixo vazio é espaço desperdiçado.
Mais de 4 séries em um eixo sem empilhamento — visualmente ilegível.
Misturar faixas muito diferentes em um único eixo linear (por exemplo, contagens de 1-2M com preço de 20k-100k) — a série menor fica invisível.
Preço do BTC em um eixo linear quando pareado com uma métrica de alto crescimento — o preço dominará visualmente.
Linhas de referência decorativas sem significado numérico — adicionam ruído, não sinal.
Barras em escala logarítmica — ficam ilegíveis.
Paleta sob medida por gráfico — quebra as associações de cor que o usuário aprendeu.

10. Referência rápida para a skill `lab-author`

Quando o Buddy monta uma configuração de gráfico a partir de linguagem natural:

Resolva os IDs das métricas via search_metrics / get_metric. Confirme que o grade de cada métrica está dentro do tier do usuário.
Decida o layout dos eixos:
- O preço do BTC é uma das séries? → preço à direita com scale: "log", primária à esquerda.
- As métricas restantes compartilham uma unidade? → mesmo eixo. Unidades diferentes? → eixos diferentes.
Escolha os estilos de gráfico conforme o §3.
Escolha as cores conforme o §4.1 — use a paleta estabelecida para o domínio.
Escolha a escala conforme o §2.
Escolha o intervalo de datas conforme o §6.
Adicione linhas/áreas de referência somente quando o limiar tiver um significado claro (§5).
Aplique as constantes de estilo (§7) e as convenções de nomenclatura (§8).
Execute a checklist de antipadrões (§9) antes de salvar.

11. Onde os modelos residem

Estáticos (frontend) — chart-templates. ~70 modelos carregados na inicialização do app.
Banco de dados (tabela templates) — modelos curados populados por template-seeds e expostos via the templates API.
Criados pelo usuário (tabela user-charts) — sobre o que trata o restante deste guia. Salvos pela UI do Lab, ao fazer um fork de um modelo, ou pela ferramenta MCP save_chart do Buddy.

O formato JSON da configuração (metrics, formulas, yAxes, dateRange, referenceLines, referenceAreas, etc.) é idêntico nas três fontes — consulte the chart config em the Lab API client para a definição TypeScript e the API schema para o esquema Pydantic.

1. Eixos​

1.1 O preço sempre no eixo Y direito, escala logarítmica​

1.2 Métricas que compartilham uma unidade compartilham um eixo​

1.3 Comparação de ciclos: allLeftAxis: true + escala logarítmica​

1.4 Cor do rótulo do eixo​

2. Seleção de escala​

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

4. Paleta de cores​

4.1 Por domínio​

4.2 Coloração de múltiplas métricas​

5. Linhas e áreas de referência​

6. Padrões de intervalo de datas​

7. Constantes de estilo​

8. Convenções de nomenclatura​

9. Antipadrões​

10. Referência rápida para a skill lab-author​

11. Onde os modelos residem​