דלג לתוכן הראשי

ספר סגנון הגרפים

זהו המקור הקנוני לאופן שבו נראה גרף Blocklens "טוב". הוא מזקק את הכללים המובעים על פני ‎~70 התבניות המובנות (chart-templates), התבניות הנזרעות במסד הנתונים (template-seeds), והתנהגות הרינדור של the chart renderer.

שני קהלים:

  1. מחברי תבניות / Frontend — החילו את הכללים האלה בעת תכנון תבניות חדשות או נתוני זריעה.
  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 ← ציר שמאלי אחד (שניהם יחסים).
  • שיעור מימון (%) משמאל, מחיר (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), אחוזים, שיעורי מימוןמדדי מניות כשמוצגים לבד (SPY/QQQ/IWM)
דלתאות יומיות, שינויים נטומודלי מחיר (realized_price, transferred_price)
כל דבר שנע בטווח חסוםשכבות-על של ביצועי מחזור

אם מדד משתרע על יותר מ-‎~2 סדרי גודל לאורך החלון הנראה, העדיפו לוגריתמי.

3. סוג גרף לכל מדד​

סגנוןמתיfillOpacity
areaהחזקות, היצעים, זרימות מצטברות, AUM, קוהורטות מוערמות0.3
lineיחסים (MVRV, SOPR), שיעורים (מימון), שכבות-על של מחיר0.1
barדלתאות יומיות / 30 ימים (זרימות נטו, היצע 30D Δ)0.5
candlestickOHLC בלבד—

עמודות על ציר לוגריתמי מתרנדרות באופן בלתי קריא — שמרו על עמודות בליניארי.

4. פלטת צבעים​

4.1 לפי תחום​

תחוםרכיבHex
שכבת-על של מחירמחיר BTC (ניטרלי)#6b7280
היצעLTH#2563eb
היצעSTH#dc2626
היצעקוהורטה שלישית#fbbf24 / #FFBB28
ETFהחזקות#f59e0b
ETFAUM#3b82f6
ETFזרימה נטו#10b981
ETFזרימה מצטברת#059669
ETFדומיננטיות#8b5cf6
ETFהחזקות בארה"ב#3b82f6
ETFמחיר ממומש#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 צביעה רב-מדדית​

כששתי קוהורטות קשורות מופיעות יחד (LTH/STH, ארה"ב/לא-ארה"ב, ציבורי/פרטי), השתמשו בצמד המבוסס (כחול + אדום עבור LTH/STH) כדי שמשתמשים ילמדו מודל מנטלי אחד. אל תמציאו מחדש פלטות לכל גרף.

5. קווי וגזרי ייחוס​

השתמשו בהם רק כאשר לסף יש פרשנות ברורה:

  • שיעור מימון > 20% ← גזרה מוצללת באדום, תווית "מחומם יתר על המידה".
  • שיעור מימון < -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, מרווח מימון.
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 של כל מדד נמצא בתוך הדרגה (tier) של המשתמש.
  2. החליטו על פריסת הצירים:
    • האם מחיר BTC הוא אחת הסדרות? ← מחיר מימין עם scale: "log", ראשי משמאל.
    • האם המדדים הנותרים חולקים יחידה? ← אותו ציר. יחידות שונות? ← צירים שונים.
  3. בחרו סגנונות גרף לפי §3.
  4. בחרו צבעים לפי §4.1 — השתמשו בפלטה המבוססת עבור התחום.
  5. בחרו קנה מידה לפי §2.
  6. בחרו טווח תאריכים לפי §6.
  7. הוסיפו קווי/גזרי ייחוס רק כאשר לסף יש משמעות ברורה (§5).
  8. החילו קבועי עיצוב (§7) ומוסכמות מתן שמות (§8).
  9. הריצו את רשימת התיוג של האנטי-תבניות (§9) לפני השמירה.

11. היכן התבניות חיות​

  • סטטיות (Frontend) — chart-templates. ‎~70 תבניות נטענות בעת הפעלת האפליקציה.
  • מסד נתונים (טבלת templates) — תבניות אצורות הנזרעות על ידי template-seeds ונחשפות באמצעות the templates API.
  • שנוצרו על ידי המשתמש (טבלת user-charts) — מה ששאר המדריך הזה עוסק בו. נשמרות באמצעות ממשק ה-Lab, על ידי פיצול (fork) של תבנית, או על ידי כלי ה-MCP save_chart של Buddy.

מבנה ה-JSON של הקונפיגורציה (metrics, formulas, yAxes, dateRange, referenceLines, referenceAreas וכו') זהה בכל שלושת המקורות — ראו the chart config ב-the Lab API client עבור הגדרת ה-TypeScript ו-the API schema עבור סכמת ה-Pydantic.