チャートスタイルブック
これは「良い」Blocklens チャートがどのように見えるべきかについての標準的なリファレンスです。約 70 種類の組み込みテンプレート（chart-templates）、DB にシードされたテンプレート（template-seeds）、および the chart renderer のレンダリング動作全体にわたって表現されているルールを集約したものです。
対象とする読者は 2 種類です。
- フロントエンド / テンプレート作成者 — 新しいテンプレートやシードデータを設計する際にこれらのルールを適用してください。
- Buddy の
lab-authorスキル — これらのルールの要約版を読み込み、AI が生成するチャート設定がキュレーションされたカタログのビジュアル言語に合致するようにします。
以下のルールがテンプレートの現在の挙動と矛盾する場合、過去の経緯からテンプレート側が優先されますが、新規の作業はこのガイドに従ってください。
1. 軸
1.1 価格は常に右側の Y 軸、対数スケール
BTC 価格を重ねて表示するすべてのテンプレートでは、価格を scale: "log" を指定した別個の右軸に配置します。主要なメトリクスは左軸に配置します。価格を視覚的に関連付けつつ数値的には分離することで、急成長するメトリクス（保有量、AUM、供給量）と価格の双方を読みやすく保ちます。
例外: 価格モデルテンプレート（realized_price、transferred_price）では、ユーザーが 2 つの価格を 1 つのスケール上で比較できるよう、価格をモデルと同じ軸に配置します。その軸は対数です。
1.2 単位を共有するメトリクスは軸を共有する
lth_supply+sth_supply→ 1 つの左軸（どちらも BTC）。lth_mvrv+sth_mvrv→ 1 つの左軸（どちらも比率）。- ファンディングレート（%）を左に、価格（USD）を右に — 単位が異なるため軸も異なります。
レンジが大きく異なる 2 つのメトリクスを同じ線形軸上に重ねないでください。小さい方の系列が視覚的に押しつぶされてしまいます。
1.3 サイクル比較: allLeftAxis: true + 対数スケール
サイクルパフォーマンスのテンプレート（例: cycle-perf-low、cycle-perf-ath、cycle-perf-halving）では、yAxes: [{ side: "left", scale: "log" }] とともに allLeftAxis: true を強制します。複数のサイクルが同じ対数軸上に重なるため、指数関数的な成長をサイクル間で比較できます。
1.4 軸ラベルの色
- 異なる色の複数の系列が軸を共有する場合 → 軸ラベルは中立的な濃いグレー
#6b7280。 - 単一のメトリクスが軸を占有する場合 → ラベルはそのメトリクスの色を継承してもかまいません（使用頻度は低く、グレーが安全なデフォルトです）。
2. スケールの選択
| 線形を使う場合 | 対数を使う場合 |
|---|---|
| 供給量、フロー、件数、USD 値、時価総額 | BTC 価格（常に） |
| 比率（MVRV、SOPR）、パーセンテージ、ファンディングレート | 単独で表示する株価指数（SPY/QQQ/IWM） |
| 日次デルタ、純変化 | 価格モデル（realized_price、transferred_price） |
| 限定された範囲内で変動するもの | サイクルパフォーマンスのオーバーレイ |
メトリクスが表示ウィンドウ内で約 2 桁を超える範囲にわたる場合は、対数を優先してください。
3. メトリクスごとのチャートタイプ
| スタイル | 使用する場面 | fillOpacity |
|---|---|---|
area | 保有量、供給量、累積フロー、AUM、積み上げコホート | 0.3 |
line | 比率（MVRV、SOPR）、レート（ファンディング）、価格オーバーレイ | 0.1 |
bar | 日次 / 30 日デルタ（純フロー、供給量 30D Δ） | 0.5 |
candlestick | OHLC のみ | — |
対数軸上の棒グラフは読み取れない形でレンダリングされます — 棒グラフは線形のままにしてください。
4. カラーパレット
4.1 ドメイン別
| ドメイン | 要素 | Hex |
|---|---|---|
| 価格オーバーレイ | BTC 価格（中立） | #6b7280 |
| 供給量 | LTH | #2563eb |
| 供給量 | STH | #dc2626 |
| 供給量 | 第 3 コホート | #fbbf24 / #FFBB28 |
| ETF | 保有量 | #f59e0b |
| ETF | AUM | #3b82f6 |
| ETF | 純フロー | #10b981 |
| ETF | 累積フロー | #059669 |
| ETF | ドミナンス | #8b5cf6 |
| ETF | 米国保有量 | #3b82f6 |
| ETF | Realized Price | #dc2626 / #ea580c |
| DAT | 総保有量 | #F7931A（Bitcoin ブランド） |
| DAT | 公開企業 | #0088FE |
| DAT | 政府 | #FF4444 |
| DAT | 非公開企業 | #FFBB28 |
| DAT | 純変化 | #82ca9d |
| DAT | ドミナンス | #ff7300 |
| ファンディング | レート | #3b82f6 |
| ファンディング | スプレッド | #f97316 |
| ファンディング | 過熱ゾーン | rgba(239,68,68,0.1) |
| ファンディング | 投げ売りゾーン | rgba(34,197,94,0.1) |
| マクロ | 利回り（中立） | #6b7280 |
| マクロ | インフレ | #f59e0b |
| マクロ | VIX / リスク | #ef4444 |
| サイクル 1→4 | バイオレット → ブルー → グリーン → オレンジ | #8b5cf6 → #3b82f6 → #22c55e → #f97316 |
4.2 複数メトリクスの配色
関連する 2 つのコホートが一緒に表示される場合（LTH/STH、米国/非米国、公開/非公開）、確立されたペア（LTH/STH には青 + 赤）を使用し、ユーザーが 1 つのメンタルモデルを習得できるようにします。チャートごとにパレットを作り直さないでください。
5. 参照線と参照エリア
これらはしきい値に明確な解釈がある場合にのみ使用してください。
- ファンディングレート
> 20%→ 赤い網掛けエリア、ラベル「過熱」。 - ファンディングレート
< -10%→ 緑の網掛けエリア、ラベル「投げ売り」。 - SOPR
= 1.0→ 損益分岐点の参照線（検討の余地あり — まだテンプレートには含まれていません）。 - MVRV
= 1.0→ 公正価値パリティの参照線。
数値的な意味を持たない装飾的な線は避けてください。1 チャートあたり注釈は最大で 1 〜 2 個までです。
"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. 日付範囲のデフォルト
| プリセット | 使用する場面 |
|---|---|
ALL | 長期トレンドのメトリクス — 供給量、評価、サイクルオーバーレイ、ユーザーが全体を見たい長い履歴を持つもの。 |
1Y | 複数年のビューがシグナルを覆い隠してしまうノイズの多いメトリクス — 日次純フロー、DAT 純変化、ファンディングスプレッド。 |
1W / 1M | デフォルトにはしない — これらはユーザー主導のズームレベルです。 |
7. スタイリング定数
チャート固有の理由がない限り、これらをあらゆる場所で使用してください。
- すべての線に
strokeWidth: 2。 - エリアには
fillOpacity: 0.3、線オーバーレイには0.1、棒には0.5。 instanceIdの形式:{metricId}-{seq}（例:price-1、lth_supply-1）。編集をまたいで安定。
8. 命名規則
- チャート名 — 名詞句で、列見出しのようにタイトルケースにします。60 文字以下。絵文字なし。
- 良い例:
BTC LTH Supply with 30D Change、ETF Net Flow vs. Price - 悪い例:
📈 Bitcoin Long-Term Holders!!! (2024)
- 良い例:
- 説明 — チャートが何を示し、どのようなインサイトを浮かび上がらせるかを記述した一文。
- 良い例:
Long-term holder supply with 30-day delta bars to surface accumulation and distribution waves.
- 良い例:
9. アンチパターン
テンプレートや AI 生成の設定をレビューする際は、これらを却下してください。
- 2 軸レイアウト上の単一メトリクス — 空の軸はスペースの無駄です。
- 積み上げなしで 1 軸上に 4 系列を超える — 視覚的に読み取れません。
- 大きく異なるレンジを単一の線形軸上で混在させる（例: 100 〜 200 万の件数と 2 万 〜 10 万の価格） — 小さい方の系列が見えなくなります。
- 高成長メトリクスと組み合わせたときに線形軸へ置く BTC 価格 — 価格が視覚的に他を圧倒してしまいます。
- 数値的な意味のない装飾的な参照線 — シグナルではなくノイズを加えます。
- 対数スケール上の棒グラフ — 読み取れない形でレンダリングされます。
- チャートごとの独自パレット — ユーザーが習得した色の関連付けを壊します。
10. lab-author スキルのためのクイックリファレンス
Buddy が自然言語からチャート設定を構築する際は、以下を行います。
search_metrics/get_metricを介してメトリクス ID を解決します。各メトリクスのgradeがユーザーのティア内であることを確認します。- 軸レイアウトを決定します。
- BTC 価格が系列の 1 つか？ → 価格を
scale: "log"で右に、主要メトリクスを左に配置。 - 残りのメトリクスは単位を共有するか？ → 同じ軸に。単位が異なるか？ → 異なる軸に。
- BTC 価格が系列の 1 つか？ → 価格を
- §3 に従ってチャートスタイルを選びます。
- §4.1 に従って色を選びます — そのドメインの確立されたパレットを使用します。
- §2 に従ってスケールを選びます。
- §6 に従って日付範囲を選びます。
- しきい値に明確な意味がある場合にのみ参照線/参照エリアを追加します（§5）。
- スタイリング定数（§7）と命名規則（§8）を適用します。
- 保存する前にアンチパターンのチェックリスト（§9）を実行します。
11. テンプレートの所在
- 静的（フロントエンド） —
chart-templates。アプリ起動時に約 70 種類のテンプレートが読み込まれます。 - データベース（
templatesテーブル） —template-seedsによってシードされ、the templates APIを介して提供されるキュレーション済みテンプレート。 - ユーザー作成（
user-chartsテーブル） — このガイドの残りの部分が扱う対象です。Lab UI から直接、テンプレートをフォークして、あるいは Buddy のsave_chartMCP ツール経由で保存されます。
設定 JSON の構造（metrics、formulas、yAxes、dateRange、referenceLines、referenceAreas など）は 3 つのソースすべてで共通です — TypeScript の定義については the Lab API client の the chart config を、Pydantic スキーマについては the API schema を参照してください。