کتاب سبک نمودار

این مرجع متعارفِ ظاهرِ یک نمودار «خوب» در Blocklens است. این سند قواعدِ بیان‌شده در حدود ۷۰ قالب داخلی (chart-templates)، قالب‌های ذخیره‌شده در پایگاه‌داده (template-seeds) و رفتار رندرینگِ the chart renderer را تقطیر می‌کند.

دو مخاطب:

1. نویسندگان فرانت‌اند / قالب‌ها — هنگام طراحی قالب‌های جدید یا داده‌های اولیه (seed) این قواعد را به کار ببرید.
2. مهارت lab-author در Buddy — نسخه‌ای فشرده از این قواعد را بارگذاری می‌کند تا پیکربندی‌های نمودارِ تولیدشده با هوش مصنوعی با زبان بصریِ کاتالوگِ گزیده هماهنگ باشند.

اگر قاعده‌ای در ادامه با کاری که یک قالب در حال حاضر انجام می‌دهد در تضاد باشد، به دلایل قدیمی (legacy) قالب اولویت دارد، اما کارهای جدید باید از این راهنما پیروی کنند.

---

۱. محورها

۱.۱ قیمت همیشه روی محور Y سمت راست، با مقیاس لگاریتمی

هر قالبی که قیمت BTC را همپوشانی می‌کند، قیمت را روی یک محور راستِ جداگانه با scale: "log" قرار می‌دهد. متریک اصلی روی محور چپ می‌رود. پیوند بصریِ قیمت اما جداسازیِ عددیِ آن باعث می‌شود متریک‌های پُررشد (دارایی‌ها، AUM، عرضه) و قیمت هر دو خوانا بمانند.

استثنا: قالب‌های مدلِ قیمت (realized_price, transferred_price) قیمت را روی همان محورِ مدل قرار می‌دهند تا کاربران بتوانند دو قیمت را روی یک مقیاس مقایسه کنند. آن محور لگاریتمی است.

۱.۲ متریک‌هایی که واحد مشترک دارند، محور مشترک دارند

• lth_supply + sth_supply ← یک محور چپ (هر دو BTC).
• lth_mvrv + sth_mvrv ← یک محور چپ (هر دو نسبت‌اند).
• نرخ تأمین مالی (Funding rate) (%) روی چپ، قیمت (USD) روی راست — واحدهای متفاوت، محورهای متفاوت.

دو متریک با بازه‌های بسیار متفاوت را روی یک محور خطیِ واحد روی هم نگذارید. سری کوچک‌تر از نظر بصری له خواهد شد.

۱.۳ مقایسهٔ چرخه: allLeftAxis: true + مقیاس لگاریتمی

قالب‌های عملکردِ چرخه (مثلاً cycle-perf-low, cycle-perf-ath, cycle-perf-halving) مقدار allLeftAxis: true را با yAxes: [{ side: "left", scale: "log" }] اجبار می‌کنند. چند چرخه روی یک محور لگاریتمیِ یکسان همپوشانی می‌شوند تا رشد نمایی در میان چرخه‌ها قابل مقایسه باشد.

۱.۴ رنگ برچسبِ محور

• چند سریِ با رنگ‌های متفاوت که یک محور را به اشتراک می‌گذارند ← برچسبِ محور خاکستریِ تیرهٔ خنثی #6b7280 است.
• یک متریکِ تنها که مالک یک محور است ← برچسب می‌تواند رنگِ آن متریک را به ارث ببرد (به‌ندرت استفاده می‌شود؛ خاکستری گزینهٔ پیش‌فرضِ امن است).

---

۲. انتخاب مقیاس

از خطی استفاده کن	از لگاریتمی استفاده کن
عرضه‌ها، جریان‌ها، شمارش‌ها، مقادیر USD، ارزش بازار	قیمت BTC (همیشه)
نسبت‌ها (MVRV, SOPR)، درصدها، نرخ‌های تأمین مالی	شاخص‌های سهام وقتی به‌تنهایی نمایش داده می‌شوند (SPY/QQQ/IWM)
دلتاهای روزانه، تغییرات خالص	مدل‌های قیمت (realized_price, transferred_price)
هر چیزی که در یک بازهٔ کران‌دار نوسان می‌کند	همپوشانی‌های عملکردِ چرخه

اگر یک متریک در پنجرهٔ قابل‌مشاهده بیش از حدود ۲ مرتبهٔ بزرگی را پوشش دهد، لگاریتمی را ترجیح بدهید.

---

۳. نوع نمودار به ازای هر متریک

سبک	چه زمانی	fillOpacity
area	دارایی‌ها، عرضه‌ها، جریان‌های تجمعی، AUM، کوهورت‌های روی‌هم‌چیده	0.3
line	نسبت‌ها (MVRV, SOPR)، نرخ‌ها (تأمین مالی)، همپوشانی‌های قیمت	0.1
bar	دلتاهای روزانه / ۳۰ روزه (جریان‌های خالص، عرضه با Δ ۳۰ روزه)	0.5
candlestick	فقط OHLC	—

میله‌ها روی محور لگاریتمی به‌صورت ناخوانا رندر می‌شوند — میله‌ها را خطی نگه دارید.

---

۴. پالت رنگ

۴.۱ بر اساس دامنه

دامنه	عنصر	کد Hex
همپوشانی قیمت	قیمت BTC (خنثی)	#6b7280
عرضه	LTH	#2563eb
عرضه	STH	#dc2626
عرضه	کوهورت سوم	#fbbf24 / #FFBB28
ETF	دارایی‌ها	#f59e0b
ETF	AUM	#3b82f6
ETF	جریان خالص	#10b981
ETF	جریان تجمعی	#059669
ETF	سهم غالب (dominance)	#8b5cf6
ETF	دارایی‌های آمریکا	#3b82f6
ETF	قیمت تحقق‌یافته (realized price)	#dc2626 / #ea580c
DAT	کل دارایی‌ها	#F7931A (برند Bitcoin)
DAT	شرکت‌های سهامی‌عام (public)	#0088FE
DAT	دولت‌ها	#FF4444
DAT	شرکت‌های خصوصی	#FFBB28
DAT	تغییر خالص	#82ca9d
DAT	سهم غالب (dominance)	#ff7300
Funding	نرخ	#3b82f6
Funding	اسپرد	#f97316
Funding	ناحیهٔ بیش‌گرم‌شده (overheated)	rgba(239,68,68,0.1)
Funding	ناحیهٔ تسلیم (capitulation)	rgba(34,197,94,0.1)
Macro	بازده‌ها (خنثی)	#6b7280
Macro	تورم	#f59e0b
Macro	VIX / ریسک	#ef4444
چرخهٔ ۱←۴	بنفش ← آبی ← سبز ← نارنجی	#8b5cf6 ← #3b82f6 ← #22c55e ← #f97316

۴.۲ رنگ‌بندیِ چندمتریکی

وقتی دو کوهورتِ مرتبط با هم ظاهر می‌شوند (LTH/STH، آمریکا/غیرآمریکا، سهامی‌عام/خصوصی)، از جفت تثبیت‌شده استفاده کنید (آبی + قرمز برای LTH/STH) تا کاربران یک مدل ذهنی واحد بیاموزند. برای هر نمودار پالت را از نو اختراع نکنید.

---

۵. خطوط و نواحیِ مرجع

این‌ها را فقط زمانی استفاده کنید که آستانه تفسیری روشن دارد:

• نرخ تأمین مالی > 20% ← ناحیهٔ سایه‌خوردهٔ قرمز، با برچسب "Overheated".
• نرخ تأمین مالی < -10% ← ناحیهٔ سایه‌خوردهٔ سبز، با برچسب "Capitulation".
• 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" }
]

---

۶. بازهٔ زمانیِ پیش‌فرض

تنظیم آماده (Preset)	چه زمانی
ALL	متریک‌های روند بلندمدت — عرضه، ارزش‌گذاری، همپوشانی‌های چرخه، هر چیزی با تاریخچهٔ طولانی که کاربران می‌خواهند کامل ببینند.
1Y	متریک‌های پُرنوسان که نماهای چندساله سیگنال را پنهان می‌کنند — جریان‌های خالص روزانه، تغییر خالص DAT، اسپرد تأمین مالی.
1W / 1M	هرگز پیش‌فرض نیستند — این‌ها سطوح بزرگ‌نماییِ کاربرمحور هستند.

---

۷. ثابت‌های استایل

این‌ها را همه‌جا استفاده کنید مگر آنکه دلیلی خاصِ یک نمودار برای نکردنش وجود داشته باشد:

• strokeWidth: 2 برای همهٔ خطوط.
• fillOpacity: 0.3 برای نواحی، 0.1 برای همپوشانی‌های خطی، 0.5 برای میله‌ها.
• قالبِ instanceId: {metricId}-{seq} (مثلاً price-1, lth_supply-1). در میان ویرایش‌ها پایدار است.

---

۸. قراردادهای نام‌گذاری

• نام نمودار — عبارت اسمی، با قالب‌بندیِ عنوان مانند سرستونِ یک ستون. حداکثر ۶۰ نویسه. بدون ایموجی.
  • خوب: 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.

---

۹. الگوهای ناپسند (Anti-patterns)

هنگام بازبینیِ یک قالب یا پیکربندیِ تولیدشده با هوش مصنوعی، این‌ها را رد کنید:

• یک متریکِ تنها روی چیدمانِ دومحوره — محور خالی فضای هدررفته است.
• بیش از ۴ سری روی یک محور بدون روی‌هم‌چیدن (stacking) — از نظر بصری ناخوانا.
• آمیختنِ بازه‌های بسیار متفاوت روی یک محور خطیِ واحد (مثلاً شمارش‌های ۱ تا ۲ میلیون با قیمت ۲۰ هزار تا ۱۰۰ هزار) — سری کوچک‌تر نامرئی می‌شود.
• قیمت BTC روی محور خطی هنگامی که با یک متریکِ پُررشد جفت شده — قیمت از نظر بصری غالب می‌شود.
• خطوط مرجعِ تزیینی بدون معنای عددی — نویز اضافه می‌کند، نه سیگنال.
• میله‌ها روی مقیاس لگاریتمی — به‌صورت ناخوانا رندر می‌شوند.
• پالتِ سفارشی به ازای هر نمودار — تداعی‌های رنگیِ آموخته‌شدهٔ کاربر را می‌شکند.

---

۱۰. مرجع سریع برای مهارت lab-author

وقتی Buddy یک پیکربندیِ نمودار را از زبان طبیعی می‌سازد:

1. شناسه‌های متریک را از طریق search_metrics / get_metric پیدا کن. تأیید کن که grade هر متریک در محدودهٔ سطح اشتراکِ کاربر است.
2. دربارهٔ چیدمانِ محور تصمیم بگیر:
   • آیا قیمت BTC یکی از سری‌هاست؟ ← قیمت روی راست با scale: "log"، سریِ اصلی روی چپ.
   • آیا متریک‌های باقی‌مانده واحدی مشترک دارند؟ ← همان محور. واحدهای متفاوت؟ ← محورهای متفاوت.
3. سبک‌های نمودار را بر اساس §۳ انتخاب کن.
4. رنگ‌ها را بر اساس §۴.۱ انتخاب کن — از پالت تثبیت‌شدهٔ دامنه استفاده کن.
5. مقیاس را بر اساس §۲ انتخاب کن.
6. بازهٔ زمانی را بر اساس §۶ انتخاب کن.
7. خطوط/نواحیِ مرجع را فقط وقتی اضافه کن که آستانه معنای روشنی دارد (§۵).
8. ثابت‌های استایل (§۷) و قراردادهای نام‌گذاری (§۸) را به کار ببر.
9. پیش از ذخیره، فهرستِ بررسیِ الگوهای ناپسند (§۹) را اجرا کن.

---

۱۱. قالب‌ها کجا قرار دارند

• ایستا (فرانت‌اند) — chart-templates. حدود ۷۰ قالب که در زمان راه‌اندازیِ برنامه بارگذاری می‌شوند.
• پایگاه‌داده (جدول templates) — قالب‌های گزیده که توسط template-seeds به‌صورت اولیه پر می‌شوند و از طریق the templates API ارائه می‌شوند.
• ساخته‌شده توسط کاربر (جدول user-charts) — همان چیزی که بقیهٔ این راهنما دربارهٔ آن است. از طریق رابط کاربریِ Lab، با فورک‌کردنِ یک قالب، یا با ابزار MCP موسوم به save_chart در Buddy ذخیره می‌شوند.

شکلِ JSON پیکربندی (metrics, formulas, yAxes, dateRange, referenceLines, referenceAreas، و غیره) در میان هر سه منبع یکسان است — برای تعریفِ TypeScript به the chart config در the Lab API client و برای اسکیمای Pydantic به the API schema مراجعه کنید.