Перейти к основному содержимому

Руководство по стилю графиков

Это канонический справочник о том, как выглядит «хороший» график Blocklens. В нём собраны правила, заложенные в ~70 встроенных шаблонов (chart-templates), в шаблоны, засеянные в БД (template-seeds), и в логику рендеринга the chart renderer.

Две аудитории:

  1. Авторы фронтенда / шаблонов — применяйте эти правила при разработке новых шаблонов или начальных данных.
  2. Скилл lab-author у Buddy — загружает сжатую копию этих правил, чтобы конфигурации графиков, сгенерированные ИИ, соответствовали визуальному языку курируемого каталога.

Если правило ниже противоречит текущему поведению шаблона, приоритет у шаблона — по историческим причинам, но в новых разработках следуйте этому руководству.

1. Оси​

1.1 Цена всегда на правой оси Y, логарифмическая шкала​

Каждый шаблон, накладывающий цену BTC, размещает цену на отдельной правой оси со scale: "log". Основная метрика идёт на левую ось. Цена остаётся визуально рядом с остальными рядами, но вынесена на отдельную шкалу — так читаемыми остаются и быстрорастущие метрики (объёмы хранения, AUM, предложение), и сама цена.

Исключение: шаблоны ценовых моделей (realized_price, transferred_price) размещают цену на той же оси, что и модель, чтобы пользователи могли сравнить две цены в одной шкале. Эта ось логарифмическая.

1.2 Метрики с общей единицей измерения делят одну ось​

  • lth_supply + sth_supply → одна левая ось (обе в BTC).
  • lth_mvrv + sth_mvrv → одна левая ось (обе — отношения).
  • Funding rate (%) слева, цена (USD) справа — разные единицы, разные оси.

Не размещайте две метрики с сильно различающимися диапазонами на одной линейной оси. Меньший ряд будет визуально сжат.

1.3 Сравнение циклов: allLeftAxis: true + логарифмическая шкала​

Шаблоны производительности циклов (например, cycle-perf-low, cycle-perf-ath, cycle-perf-halving) принудительно задают allLeftAxis: true с yAxes: [{ side: "left", scale: "log" }]. Несколько циклов накладываются на одну логарифмическую ось, чтобы экспоненциальный рост был сопоставим между циклами.

1.4 Цвет подписи оси​

  • Несколько разноцветных рядов, делящих одну ось → подпись оси нейтрально-тёмно-серая #6b7280.
  • Одна метрика, владеющая осью → подпись может наследовать цвет этой метрики (используется редко; серый — безопасное значение по умолчанию).

2. Выбор шкалы​

ЛинейнаяЛогарифмическая
Объёмы предложения, потоки, счётчики, значения в USD, рыночная капитализацияЦена BTC (всегда)
Отношения (MVRV, SOPR), проценты, funding rateФондовые индексы, когда показаны отдельно (SPY/QQQ/IWM)
Дневные дельты, чистые измененияЦеновые модели (realized_price, transferred_price)
Всё, что колеблется в ограниченном диапазонеНаложения производительности циклов

Если метрика охватывает более ~2 порядков величины в видимом окне, предпочтите логарифмическую шкалу.

3. Тип графика по метрике​

СтильКогдаfillOpacity
areaОбъёмы хранения, предложение, кумулятивные потоки, AUM, стопкованные когорты0.3
lineОтношения (MVRV, SOPR), ставки (funding), наложения цены0.1
barДневные / 30-дневные дельты (чистые потоки, 30D Δ предложения)0.5
candlestickТолько OHLC—

Столбцы на логарифмической оси отображаются нечитаемо — оставляйте столбцы на линейной шкале.

4. Цветовая палитра​

4.1 По домену​

ДоменЭлементHex
Наложение ценыЦена BTC (нейтральная)#6b7280
ПредложениеLTH#2563eb
ПредложениеSTH#dc2626
Предложениетретья когорта#fbbf24 / #FFBB28
ETFобъёмы хранения#f59e0b
ETFAUM#3b82f6
ETFчистый поток#10b981
ETFкумулятивный поток#059669
ETFдоминирование#8b5cf6
ETFобъёмы хранения в США#3b82f6
ETFrealized price#dc2626 / #ea580c
DATсовокупные объёмы хранения#F7931A (бренд Bitcoin)
DATпубличные компании#0088FE
DATправительства#FF4444
DATчастные компании#FFBB28
DATчистое изменение#82ca9d
DATдоминирование#ff7300
Fundingставка#3b82f6
Fundingспред#f97316
Fundingзона перегреваrgba(239,68,68,0.1)
Fundingзона капитуляцииrgba(34,197,94,0.1)
Макродоходности (нейтральная)#6b7280
Макроинфляция#f59e0b
МакроVIX / риск#ef4444
Цикл 1→4фиолетовый → синий → зелёный → оранжевый#8b5cf6 → #3b82f6 → #22c55e → #f97316

4.2 Раскраска нескольких метрик​

Когда две связанные когорты появляются вместе (LTH/STH, США/не-США, публичные/частные), используйте устоявшуюся пару (синий + красный для LTH/STH), чтобы пользователи усваивали единую ментальную модель. Не изобретайте палитры заново для каждого графика.

5. Опорные линии и области​

Используйте их только когда у порога есть чёткая интерпретация:

  • Funding rate > 20% → красная заливка области, подпись «Перегрев».
  • Funding rate < -10% → зелёная заливка области, подпись «Капитуляция».
  • SOPR = 1.0 → опорная линия на уровне безубыточности (возможность — пока нет в шаблонах).
  • MVRV = 1.0 → опорная линия на паритете справедливой стоимости.

Избегайте декоративных линий без числового смысла. Максимум одна-две аннотации на график.

"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, спред funding.
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. Антипаттерны​

Отклоняйте их при ревью шаблона или сгенерированной ИИ конфигурации:

  • Одна метрика в макете с двумя осями — пустая ось — это потраченное впустую место.
  • Более 4 рядов на одной оси без стопкования — визуально нечитаемо.
  • Смешивание сильно различающихся диапазонов на одной линейной оси (например, счётчики 1–2M с ценой 20k–100k) — меньший ряд невидим.
  • Цена BTC на линейной оси в паре с быстрорастущей метрикой — цена будет визуально доминировать.
  • Декоративные опорные линии без числового смысла — добавляют шум, а не сигнал.
  • Столбцы на логарифмической шкале — отображаются нечитаемо.
  • Уникальная палитра под каждый график — ломает усвоенные пользователем цветовые ассоциации.

10. Краткий справочник для скилла lab-author​

Когда Buddy строит конфигурацию графика из естественного языка:

  1. Разрешите идентификаторы метрик через search_metrics / get_metric. Подтвердите, что grade каждой метрики входит в тариф пользователя.
  2. Определите расположение осей:
    • Является ли цена BTC одним из рядов? → цена справа со scale: "log", основная слева.
    • Имеют ли остальные метрики общую единицу измерения? → одна ось. Разные единицы? → разные оси.
  3. Выберите стили графиков согласно §3.
  4. Выберите цвета согласно §4.1 — используйте устоявшуюся палитру для домена.
  5. Выберите шкалу согласно §2.
  6. Выберите диапазон дат согласно §6.
  7. Добавляйте опорные линии/области, только когда у порога есть чёткий смысл (§5).
  8. Примените константы стилизации (§7) и соглашения об именовании (§8).
  9. Прогоните чек-лист антипаттернов (§9) перед сохранением.

11. Где находятся шаблоны​

  • Статические (фронтенд) — chart-templates. ~70 шаблонов, загружаемых при старте приложения.
  • База данных (таблица templates) — курируемые шаблоны, засеянные через template-seeds и доступные через the templates API.
  • Созданные пользователем (таблица user-charts) — то, о чём идёт речь в остальной части этого руководства. Сохраняются через интерфейс Lab, путём форка шаблона или через MCP-инструмент save_chart у Buddy.

Форма конфигурационного JSON (metrics, formulas, yAxes, dateRange, referenceLines, referenceAreas и т. д.) идентична во всех трёх источниках — см. the chart config в the Lab API client для определения TypeScript и the API schema для схемы Pydantic.