ערכות נושא מותאמות אישית – מדריך מקיף

מבוא וסקירה כללית

מהי ערכת נושא מותאמת אישית?

ערכת נושא מותאמת אישית (Custom Theme) היא אוסף של משתני CSS המגדירים את המראה הוויזואלי של הממשק – צבעי רקע, טקסט, כפתורים, קוד ועוד.

היתרונות העיקריים:

  • התאמה אישית מלאה של המראה לפי טעמכם

  • ייבוא ערכות מ-VS Code בלחיצה אחת

  • שמירת מספר ערכות ומעבר ביניהן

  • תמיכה בהדגשת תחביר (Syntax Highlighting) ייחודית

ההבדל בין Presets לבין Custom Themes

Presets (ערכות מוכנות)

Custom Themes (ערכות מותאמות)

מקור

מוגדרות מראש במערכת (Dark, Ocean, Classic…)

נוצרות על ידי המשתמש או מיובאות

עריכה

לא ניתנות לעריכה

ניתנות לעריכה מלאה

הדגשת תחביר

קבועה לפי הערכה

מיובאת מ-VS Code או ברירת מחדל

שמירה

במערכת

ב-MongoDB לפי משתמש

יכולות המערכת

  • ייבוא מ-VS Code – תמיכה מלאה בפורמט JSON/JSONC של VS Code themes

  • יצירה ידנית – עורך צבעים מתקדם עם תצוגה מקדימה חיה

  • ערכות מוכנות – גלריה של ערכות פופולריות (GitHub, Dracula, Nord…)

  • הדגשת תחביר – מיפוי אוטומטי של tokenColors ל-CodeMirror

ייבוא ערכות VS Code

פורמטים נתמכים

המערכת תומכת בשני פורמטי JSON:

JSON רגיל:

קובץ JSON סטנדרטי ללא הערות.

JSONC (JSON with Comments):

פורמט מורחב שתומך בהערות – נפוץ מאוד בערכות VS Code כמו Nord, One Dark Pro ועוד:

{
  "name": "My Theme",
  /* זו הערה מרובת שורות */
  "type": "dark",
  "colors": {
    // זו הערה של שורה בודדת
    "editor.background": "#1a1b26",
    "editor.foreground": "#c0caf5",
    "focusBorder": "#7aa2f7"
  }
}

סוגי הערות נתמכים:

  • /* ... */ – הערות מרובות שורות (multi-line)

  • // ... – הערות של שורה בודדת (single-line)

הערה

המערכת מסירה אוטומטית את ההערות לפני פרסור ה-JSON, כך שאין צורך לערוך את הקובץ ידנית.

מבנה ערכת VS Code

ערכת VS Code מורכבת משלושה חלקים עיקריים:

{
  "name": "Theme Name",
  "type": "dark",
  "colors": {
    "editor.background": "#1e1e1e",
    "editor.foreground": "#d4d4d4",
    "button.background": "#569cd6",
    "sideBar.background": "#252526"
  },
  "tokenColors": [
    {
      "scope": "comment",
      "settings": {
        "foreground": "#6a9955",
        "fontStyle": "italic"
      }
    },
    {
      "scope": ["keyword", "storage"],
      "settings": {
        "foreground": "#569cd6"
      }
    }
  ]
}

הסבר השדות:

  • name – שם הערכה

  • type – סוג הערכה: "dark" או "light" (משפיע על ערכי fallback)

  • colors – מילון של צבעי UI (רקעים, טקסט, כפתורים)

  • tokenColors – כללי הדגשת תחביר

מיפוי צבעי UI

המערכת ממפה אוטומטית את צבעי VS Code למשתני CSS שלנו:

VS Code Key

CSS Variable(s)

תיאור

editor.background

--bg-primary, --md-surface

רקע ראשי

editor.foreground

--text-primary, --md-text

טקסט ראשי

sideBar.background

--bg-secondary

רקע משני

activityBar.background

--bg-tertiary

רקע שלישוני

button.background

--btn-primary-bg, --btn-primary-border

כפתור ראשי

button.foreground

--btn-primary-color

טקסט כפתור

button.hoverBackground

--btn-primary-hover-bg

כפתור בריחוף

input.background

--input-bg

רקע שדה קלט

input.border

--input-border

גבול שדה קלט

panel.border

--border-color

גבולות כלליים

focusBorder

--primary

צבע ראשי

textLink.foreground

--link-color

צבע קישורים

terminal.background

--code-bg

רקע קוד

terminal.foreground

--code-text

טקסט קוד

titleBar.activeBackground

--navbar-bg

רקע ניווט

editorWidget.background

--card-bg

רקע כרטיסים

notificationsErrorIcon.foreground

--error, --danger-bg

צבע שגיאה

notificationsWarningIcon.foreground

--warning

צבע אזהרה

testing.iconPassed

--success

צבע הצלחה

יצירה ידנית (Native Format)

מבנה הפורמט המקומי

אם אתם מעדיפים ליצור ערכה מאפס, השתמשו בפורמט המקומי:

{
  "name": "My Custom Theme",
  "description": "ערכה מותאמת אישית",
  "variables": {
    "--bg-primary": "#1a1b26",
    "--bg-secondary": "#24283b",
    "--bg-tertiary": "#414868",
    "--text-primary": "#c0caf5",
    "--text-secondary": "#9aa5ce",
    "--text-muted": "#565f89",
    "--primary": "#7aa2f7",
    "--primary-hover": "#89b4fa",
    "--btn-primary-bg": "#7aa2f7",
    "--btn-primary-color": "#1a1b26",
    "--glass-blur": "12px"
  }
}

משתנים חובה

הערכה חייבת לכלול לפחות את המשתנים הבאים לתפקוד תקין:

רקעים וטקסט (Level 2):

--bg-primary          רקע ראשי של הדף
--bg-secondary        רקע משני (סיידבר, כרטיסים)
--bg-tertiary         רקע שלישוני (אלמנטים משניים)
--text-primary        טקסט ראשי
--text-secondary      טקסט משני
--text-muted          טקסט מעומעם

צבעי מותג (Level 1):

--primary             צבע ראשי (כפתורים, קישורים, focus)
--primary-hover       צבע ראשי בריחוף
--primary-light       גרסה בהירה של הצבע הראשי

כפתורים (Level 2):

--btn-primary-bg       רקע כפתור ראשי
--btn-primary-color    טקסט כפתור ראשי
--btn-primary-border   גבול כפתור ראשי

נוספים:

--border-color        צבע גבולות
--card-bg             רקע כרטיסים
--input-bg            רקע שדות קלט
--code-bg             רקע קוד
--glass-blur          טשטוש glass (בפיקסלים, למשל "12px")

רשימת משתנים מלאה (Whitelist)

חשוב

רק משתנים שנמצאים ברשימה זו נשמרים — בייבוא, ביצירה ובעדכון של ערכה אישית, ובפרסום ערכה לציבורית. משתנים שאינם ברשימה מסוננים מטעמי אבטחה.

הרשימה כאן נמשכת מהקוד, ALLOWED_VARIABLES_WHITELIST ב-services/theme_parser_service.py, בכל בנייה של התיעוד. עד נובמבר 2026 היא הייתה עותק ידני, וטוקני ה-Level 3 של ערכה מיובאת בהירה (ערכה מיובאת בהירה: שדות טופס, הדשבורד, שורת החיפוש, הכפתורים שמעל העורך ותצוגת הקוד) חסרו בו.

services/theme_parser_service.py – ALLOWED_VARIABLES_WHITELIST
ALLOWED_VARIABLES_WHITELIST = frozenset([
    # Level 1 - Primitives
    "--primary", "--primary-hover", "--primary-light",
    "--secondary",
    "--success", "--warning", "--error",
    "--danger-bg", "--danger-border", "--text-on-warning",
    "--glass", "--glass-blur", "--glass-border", "--glass-hover",

    # Level 2 - Semantic Tokens (רקעים וטקסט)
    "--bg-primary", "--bg-secondary", "--bg-tertiary",
    "--text-primary", "--text-secondary", "--text-muted",
    "--border-color", "--shadow-color",
    "--card-bg", "--card-border",
    "--navbar-bg",
    "--input-bg", "--input-border",
    "--link-color",
    "--code-bg", "--code-text", "--code-border",

    # Level 2 - כפתורים (Button Tokens)
    "--btn-primary-bg", "--btn-primary-color", "--btn-primary-border", "--btn-primary-shadow",
    "--btn-primary-hover-bg", "--btn-primary-hover-color",

    # Level 2 - Markdown & Split View
    "--md-surface", "--md-text",
    "--split-preview-bg", "--split-preview-meta", "--split-preview-placeholder",

    # Level 2 - Markdown Enhanced (inline code, tables, mermaid)
    "--md-inline-code-bg", "--md-inline-code-border", "--md-inline-code-color",
    "--md-table-bg", "--md-table-border", "--md-table-header-bg",
    "--md-mermaid-bg",

    # Level 3 - Collections
    # מאפשר לערכה בודדת לקבוע את צבע שמות הקבצים בכרטיס אוסף, בלי שהדבר
    # ישפיע על ערכות אחרות. ראו את וו הדריסה ב-webapp/static/css/collections.css.
    "--collections-link-override",

    # Level 3 - Global Search
    # מאפשר לערכה בודדת לקבוע את צבע הטקסט בהצעות ההשלמה של החיפוש הגלובלי.
    # אותו מסלול בדיוק: ההצעות הן <a>, ולכן [data-theme="custom"] a צובע אותן
    # ב---primary על רקע לבן קבוע. ראו את וו הדריסה ב-
    # webapp/static/css/global_search.css.
    "--search-suggestion-text-override",

    # Level 3 - Repo Browser (Markdown preview)
    # מאפשר לערכה בודדת לקבוע את הרקע ואת הגבול של בלוקי הקוד בתצוגת ה-Markdown של
    # דפדפן הריפו, בלי שהדבר ישפיע על ערכות אחרות. ראו את וו הדריסה ב-
    # webapp/static/css/markdown-preview.css.
    "--repo-md-code-block-bg-override",
    "--repo-md-code-block-border-override",

    # Level 3 - Primary buttons
    # מאפשר לערכה בודדת לקבוע את צבע הטקסט של כפתור primary בכל מקום שבו הוא נצבע
    # היום ב---primary: כפתור שהוא <a> (דרך [data-theme="custom"] a), הכפתורים "ערוך"
    # ו"העתק קוד", ומצבי פוקוס/לחיצה. ראו את וו הדריסה ב-webapp/static/css/dark-mode.css,
    # בבלוק primary-btn-states-custom-type ב-webapp/templates/base.html, וב-
    # webapp/templates/view_file.html.
    "--btn-primary-text-override",

    # Level 3 - ערכה מיובאת בהירה
    # הרכיבים האלה צבועים בצבעים קבועים לרקע כהה (לבן שקוף, טקסט כמעט לבן), כמו כל ערכה
    # מיובאת, ולערכה בהירה אין דרך לקבוע אותם. כל טוקן נקרא בכלל שצובע היום את הרכיב, עם
    # fallback לערך שנצבע בו היום:
    # - שדות טופס: .form-field ב-webapp/static/css/file-editor.css (עריכה והעלאה), וה-style
    #   של שדות הסינון ב-webapp/templates/files.html.
    # - הפיד והפוש בדשבורד: .timeline-item, .timeline-group, .timeline-badge-*, .status-*
    #   ב-webapp/templates/dashboard.html.
    # - שורת החיפוש בתצוגת ה-Markdown: .md-search-capsule ב-webapp/templates/md_preview.html, ובתצוגת הקוד
    #   .search-capsule ב-webapp/templates/view_file.html.
    # - "שולחן עבודה" בעמוד הקבצים: .workspace-btn ב-webapp/templates/base.html.
    # - הכפתורים שמעל העורך: .btn-switch-editor ו-.btn-editor-clip ב-webapp/static/css/codemirror-custom.css,
    #   ו-.md-toolbar-trigger ב-webapp/static/css/markdown-toolbar.css.
    # - סרגל החיפוש ומלבני הפרטים בתצוגת הקוד: .editor-toolbar, .search-capsule, .icon-btn, .search-count,
    #   .divider, .fullscreen-btn ו-.meta-item ב-webapp/templates/view_file.html.
    "--form-field-border-override",
    "--form-field-bg-override",
    "--form-field-focus-border-override",
    "--timeline-block-bg-override",
    "--timeline-item-border-override",
    "--timeline-badge-text-override",
    "--status-pill-text-override",
    "--md-search-capsule-border-override",
    "--workspace-btn-bg-override",
    "--workspace-btn-border-override",
    "--editor-btn-text-override",
    "--editor-btn-bg-override",
    "--editor-btn-border-override",
    "--editor-btn-hover-bg-override",
    "--editor-switch-btn-bg-override",
    "--editor-switch-btn-hover-bg-override",
    "--code-toolbar-bg-override",
    "--code-toolbar-border-override",
    "--code-toolbar-hover-bg-override",
    "--code-toolbar-text-override",
    "--code-search-capsule-bg-override",
    "--code-search-capsule-focus-border-override",
    "--file-meta-item-bg-override",

    # Level 3 - צבעי המסמך (תצוגת ה-Markdown והתצוגה החיה)
    # התצוגה המרונדרת של VS Code צובעת כותרות והדגשה ב-editor.foreground, בלי מפתח משלהן, ולכן אין להם מקור
    # בקובץ ערכה: ערכה בודדת מצהירה עליהם בבלוק variables שלה. ראו את וו הדריסה ב-
    # webapp/static/css/md-content-colors.css ("צבעי המסמך" וכלל הציטוט).
    "--md-heading-color-override",
    "--md-subheading-color-override",
    "--md-strong-color-override",
    "--md-inline-code-color-override",
    "--md-blockquote-border-override",

    # Level 3 - שם הקובץ ותיאורו (כרטיס הקובץ בעמוד הקבצים, ובראש תצוגת הקוד, ה-Markdown וה-HTML)
    # בערכה מיובאת השם נצבע בכלל הכותרות של dark-mode.css, התיאור בכלל הפסקאות, והשורות, הגודל והתאריכים
    # בכרטיס יורשים את צבע הטקסט — כלומר הכול באותו צבע כשהערכה נותנת ל---text-primary ול---text-secondary
    # אותו ערך. ערכה בודדת מצהירה על צבעים לשם, לתיאור ולמטא בבלוק variables שלה. ראו את וו הדריסה ב-
    # webapp/static/css/dark-mode.css (.file-name-text, .file-description-text, .file-card-meta).
    "--file-name-color-override",
    "--file-description-color-override",
    "--file-card-meta-color-override",
])

דריסת טוקן שאין לו מקבילה ב-VS Code

חלק מהטוקנים אינם נגזרים משום מפתח של VS Code, כי אין להם מקבילה שם. --collections-link-override הוא כזה: הוא צובע את שמות הקבצים בדף /collections — גם בכרטיס אוסף וגם בשולחן העבודה, שני מסכים נפרדים שמרנדרים את אותו סוג קישור. בכוונה אין לו ערך ברירת מחדל בשום מקום, ולכן ה-CSS נופל לערך שנצבע היום כשהערכה אינה מצהירה עליו.

בערכה מיובאת שאינה מצהירה עליו, שמות הקבצים מקבלים את --primary של הערכה. זה נכון לרוב הערכות, אבל כרטיס האוסף נשאר לבן גם בערכות כהות — ולכן ערכה שה---primary שלה בהיר מקבלת טקסט בהיר על רקע בהיר.

כדי לפתור את זה בערכה בודדת, בלי להשפיע על שאר הערכות, אפשר להוסיף בלוק variables לצד colors באותו קובץ VS Code:

{
  "name": "Cobalt Next",
  "type": "dark",
  "colors": {
    "editor.background": "#1b2b34",
    "editor.foreground": "#d8dee9",
    "focusBorder": "#ffffff"
  },
  "tokenColors": [],
  "variables": {
    "--collections-link-override": "#2e6161"
  }
}

הבלוק עובר את אותה ולידציה ואת אותה רשימה לבנה כמו כל שאר הטוקנים — ערך שאינו צבע תקין מוחזר עם 400 ומציין את המפתח, ולא נזרק בשקט — ומתמזג מעל התוצאה שנגזרה מ-colors. tokenColors ממשיך להיות מעובד כרגיל, ולכן הדגשת התחביר אינה נפגעת. שימו לב ש-colors חייב להכיל לפחות שלושה מפתחות, אחרת הייבוא נדחה.

הערה

ערכה שאינה מצהירה על הטוקן מרונדרת ללא כל שינוי, בשני המצבים: webapp/static/css/collections.css נופל ל-var(--primary) במצב רגיל ול-var(--primary-dark) ב-:hover — בדיוק הערכים שנצבעו גם קודם. זו דריסה בהצטרפות מרצון, לא שינוי גורף.

הצעות ההשלמה בחיפוש הגלובלי

--search-suggestion-text-override הוא וו מאותו סוג בדיוק, ובאותו מסלול שורש. ההצעות שקופצות מתחת לתיבת החיפוש הגלובלי מרונדרות ב-webapp/static/js/global_search.js כאלמנטי <a>, ולכן [data-theme="custom"] a שב-dark-mode.css צובע אותן ב-var(--primary) — ספציפיות שגוברת על כלל המחלקה שב-global_search.css. רקע התיבה, לעומת זאת, אינו של הערכה כלל: הוא --solid-surface-bg, שנשאר לבן בכל ערכה. כלומר צבע הטקסט נגזר מהערכה והרקע לא, והניגודיות יוצאת מקרית — ערכה שה---primary שלה לבן מקבלת טקסט לבן על רקע לבן.

ההצהרה נראית זהה, ושני הטוקנים יכולים לחיות באותו בלוק:

"variables": {
  "--collections-link-override": "#2e6161",
  "--search-suggestion-text-override": "#2e6161"
}

הערה

כאן יש שלושה מצבים ולא שניים, ולכל אחד var() משלו ב-webapp/static/css/global_search.css: המצב הרגיל נופל ל-var(--primary), :hover נופל ל-var(--primary-dark), ו-:focus-visible נופל ל-var(--suggestions-text). השלישי אינו טעות: .search-suggestion:focus-visible מנצח כבר היום את כלל ה-<a> בזכות ספציפיות, ולכן הערך שנצבע בו היום שונה משני האחרים. ערכה שאינה מצהירה מרונדרת זהה לחלוטין בשלושת המצבים.

אזהרה

הערך נשמר ב-MongoDB בזמן הייבוא. ערכה שכבר קיימת בחשבון אינה מכירה טוקן שנוסף אחריה — צריך לייבא אותה מחדש. זו הסיבה הראשונה לבדוק כשההצהרה נוספה ולא נראה שינוי.

בלוקי הקוד בתצוגת ה-Markdown של דפדפן הריפו

--repo-md-code-block-bg-override ו---repo-md-code-block-border-override הם שני ווים מאותו סוג, לרקע ולגבול של בלוקי הקוד בתצוגת ה-Markdown של דפדפן הריפו. בערכה מיובאת, webapp/static/css/markdown-preview.css צובע את המעטפת של התצוגה ב---bg-tertiary, את הבלוק ב---code-bg ואת הגבול שלו ב---border-color. VSCODE_TO_CSS_MAP גוזר כל אחד מהשלושה ממפתחות אחרים של VS Code, ולכן ערכה שבה שלושתם יוצאים באותו צבע מקבלת בלוק שאינו נבדל מהטקסט שסביבו — בלי רקע אחר ובלי גבול נראה. כך קורה ב-Cobalt Next.

הדריסה היא בשני טוקנים חדשים ולא ב---code-bg עצמו, כי --code-bg צובע גם רכיבי קוד אחרים — למשל את תצוגת הקוד ב-/file ואת קטעי הקוד בחיפוש הגלובלי — ודריסה שלו בערכה הייתה משנה גם אותם. ההצהרה נראית זהה לשני הווים הקודמים, וכולם יכולים לחיות באותו בלוק:

"variables": {
  "--collections-link-override": "#2e6161",
  "--search-suggestion-text-override": "#2e6161",
  "--repo-md-code-block-bg-override": "#21313a",
  "--repo-md-code-block-border-override": "#374751"
}

הערה

ערכה שאינה מצהירה על הטוקנים מרונדרת ללא שינוי: הרקע נופל ל-var(--code-bg, var(--bg-secondary, #1e1e1e)) והגבול ל-var(--md-preview-border) — הטוקן של התצוגה, שקורא את --border-color של הערכה — מה שנצבע שם גם קודם. שני הטוקנים נקראים בכלל הקיים שצובע את הבלוק בערכות מיובאות ומשותפות, ולא בכלל חדש, כך שהמפל של ערכה שאינה מצהירה נשאר זהה. הגבול נקבע ב-border-color בלבד, והעובי והסגנון נשארים של הכלל הכללי .markdown-preview-content pre. tests/services/test_theme_variables_repo_md_code_block_hook.py נועל את החוזה הזה. וגם כאן, ערכה שכבר קיימת בחשבון מקבלת את הטוקנים רק אחרי ייבוא מחדש.

הטקסט בכפתורי primary

--btn-primary-text-override הוא וו מאותו סוג, לצבע הטקסט של כפתור primary. בערכה מיובאת או משותפת הטקסט הזה נצבע ב---primary בכמה מקומות:

  • כפתור שהוא קישור, <a class="btn btn-primary"> — למשל הלשונית הנבחרת בעמוד הקבצים והכפתורים בעמוד ההגדרות — נצבע דרך [data-theme="custom"] a שב-webapp/static/css/dark-mode.css, ובריחוף דרך a:hover שם, ב---primary-dark.

  • ”ערוך“ ו“העתק קוד“ בעמוד הקובץ נצבעים דרך .file-primary-action שב-webapp/templates/view_file.html, גם בריחוף.

  • מצבי הפוקוס, הלחיצה וההשבתה של כל כפתור primary, וכל כפתור primary בערכה משותפת, נצבעים דרך כללי ה-!important שבבלוק primary-btn-states-custom-type ב-webapp/templates/base.html.

--primary נגזר ממפתחות VS Code אחרים מאלה שקובעים את רקע הכפתור (button.background), ולכן השניים יכולים לצאת קרובים. ב-Everforest Dark --primary הוא #7fbbb3 — notificationsInfoIcon.foreground ממופה אליו אחרי focusBorder ב-VSCODE_TO_CSS_MAP, ולכן הוא שקובע — על רקע #a7c080, כלומר ניגודיות 1.09 לפי WCAG. כפתור primary שהוא <button>, כמו ”חפש“, אינו מושפע במצב רגיל: הוא נצבע ב---btn-primary-color, שהערכה קובעת דרך button.foreground.

{
  "name": "Everforest Dark",
  "type": "dark",
  "colors": {
    "editor.background": "#2d353b",
    "button.background": "#a7c080",
    "button.foreground": "#2d353b",
    "focusBorder": "#2d353b00",
    "notificationsInfoIcon.foreground": "#7fbbb3"
  },
  "tokenColors": [],
  "variables": {
    "--btn-primary-text-override": "#232a2e"
  }
}

הערה

ערכה שאינה מצהירה על הטוקן מרונדרת ללא שינוי, בכל מצב: כל כלל נופל לערך שהוא צבע עד היום — var(--primary), ובריחוף של קישור var(--primary-dark). בכללים הקיימים הטוקן נקרא בלי לשנות את הבורר. לקישורים נוספו ב-dark-mode.css שני כללים, רגיל וריחוף, עם הבוררים של כללי הקישורים עצמם ועם :where(.btn-primary): :where() אינו מוסיף ספציפיות, והכללים כתובים מיד אחרי כללי הקישורים, ולכן הם חלים בדיוק במקום שבו כללי הקישורים צובעים היום. הבורר הוא [data-theme="custom"] ולא [data-theme-type="custom"], בכוונה: סנכרון הערכה בין טאבים (initThemeCrossTabSync ב-base.html) מחליף את data-theme לערכה מובנית שנבחרה בטאב אחר ומשאיר את data-theme-type, וכלל שנשען עליו היה ממשיך לחול בטאב הזה על הערכה המובנית. tests/services/test_theme_variables_btn_primary_text_hook.py נועל את החוזה, וגם כאן ערכה שכבר קיימת בחשבון מקבלת את הטוקן רק אחרי ייבוא מחדש.

ערכה מיובאת בהירה: שדות טופס, הדשבורד, שורת החיפוש, הכפתורים שמעל העורך ותצוגת הקוד

כל ערכה מיובאת מקבלת את העיצוב של הערכות הכהות, וזה נשאר כך בכוונה. כמה רכיבים צבועים שם בצבעים קבועים לרקע כהה — לבן שקוף לגבולות ולרקעים, וטקסט לבן או כמעט לבן בתגים ובכפתורים — ולכן בערכה מיובאת בהירה הם לא נראים. לערכות המובנות הבהירות יש לחלק מהם כללים משלהן, ולערכה מיובאת אין. ווים מאותו סוג נותנים לערכה בהירה לקבוע אותם לעצמה:

  • --form-field-border-override, --form-field-bg-override ו---form-field-focus-border-override — הגבול, הרקע והגבול בפוקוס של השדות בעמודי העריכה וההעלאה (.form-field ב-webapp/static/css/file-editor.css): שם הקובץ, השפה, התיאור, התגיות והקוד. שני הראשונים נקראים גם בשדות הסינון בעמוד הקבצים (החיפוש, השפה והמיון), שצבועים רק ב-style שבתגית שלהם ב-webapp/templates/files.html.

  • --timeline-block-bg-override — הרקע של הבלוקים בפיד האחרון בדשבורד: הקבוצה (.timeline-group) והפריט שבתוכה (.timeline-item), שצבועים היום באותו ערך. --timeline-item-border-override — הפס בצד של כל פריט.

  • --timeline-badge-text-override — הטקסט של התג בפיד, בכל סוגי התג (.timeline-badge-code, -info, -warning ו--neutral). הרקע של כל סוג נשאר בגוון שלו.

  • --status-pill-text-override — הטקסט של הבאדג« בכרטיס הגדרות הפוש (”מופעל ב-X דפדפנים“), בכל סוגי הבאדג« (.status-success, -warning, -danger ו--neutral).

  • --md-search-capsule-border-override — הגבול של שורת החיפוש, שהוא שקוף עד שמתחילים להקליד: בתצוגת ה-Markdown (.md-search-capsule ב-webapp/templates/md_preview.html) ובתצוגת הקוד (.search-capsule ב-webapp/templates/view_file.html). זה אותו רכיב בשני עותקים, ולכן אותו וו.

  • --workspace-btn-bg-override ו---workspace-btn-border-override — ”שולחן עבודה“ בעמוד הקבצים (.workspace-btn ב-webapp/templates/base.html). הרקע שלו הוא מעבר צבע מ---primary ל---secondary, ו---secondary אינו ב-VSCODE_TO_CSS_MAP, ולכן בערכה מיובאת מעבר הצבע מסתיים בערך הקבוע שבבלוק ה-:root של base.html. הראשון מחליף את מעבר הצבע ברקע אחיד, והשני מוסיף מסגרת של פיקסל. המסגרת היא box-shadow ולא border, כי גבול היה מגדיל את הכפתור גם בערכה שאינה מצהירה; ההערה מעל הכלל ב-base.html מסבירה איך היא נשארת none בערכה כזו. הטקסט אינו נקבע כאן: בערכה מיובאת הוא נצבע, כמו בשאר הכפתורים שהם קישורים, בכלל [data-theme="custom"] a שב-webapp/static/css/dark-mode.css.

  • --editor-btn-text-override, --editor-btn-bg-override, --editor-btn-border-override ו---editor-btn-hover-bg-override — הכפתורים שמעל העורך, בכל עמוד שיש בו את הסרגל של addSwitcherButton (webapp/static/js/editor-manager.js): ”בטל“, ”בצע שוב“, ”בחר הכל“, ”העתק“ ו“הדבק“ (.btn-editor-clip ב-webapp/static/css/codemirror-custom.css). הטקסט והגבול נקראים גם ב-”עורך פשוט“ / ”עורך מתקדם“ (.btn-switch-editor), והטקסט גם בכפתור ה-MD (.md-toolbar-trigger ב-webapp/static/css/markdown-toolbar.css). בערכה שמצהירה על --editor-btn-border-override, הגבול של .btn-editor-clip בריחוף הוא אותו גבול כמו במצב הרגיל.

  • --editor-switch-btn-bg-override ו---editor-switch-btn-hover-bg-override — הרקע של ”עורך פשוט“ / ”עורך מתקדם“, רגיל ובריחוף, כדי שהכפתור יוכל להישאר מובחן משאר הכפתורים בשורה.

  • --code-toolbar-bg-override, --code-toolbar-border-override, --code-toolbar-hover-bg-override ו---code-toolbar-text-override — סרגל החיפוש בתצוגת הקוד (.editor-toolbar ב-webapp/templates/view_file.html): הרקע והגבול של הסרגל ושל ”מסך מלא“ (.fullscreen-btn), גם בריחוף; הקו המפריד בשורת החיפוש (.divider), בצבע הגבול; הרקע בריחוף של ”מסך מלא“ ושל ▲ ▼ ✕ (.icon-btn); והצבע של ▲ ▼ ✕ ושל מונה התוצאות (.search-count). בתצוגת ה-Markdown אותו סרגל (.md-editor-toolbar) צבוע ב---glass וב---glass-border של הערכה, ולכן שם אין צורך בווים.

  • --code-search-capsule-bg-override — הרקע של שורת החיפוש בתצוגת הקוד (.search-capsule), גם בזמן הקלדה. --code-search-capsule-focus-border-override — הגבול שלה בזמן הקלדה (.search-capsule:focus-within).

  • --file-meta-item-bg-override — המלבנים של גודל, שורות, נוצר ועודכן בתצוגת הקוד (.meta-item ב-view_file.html).

{
  "name": "Pen Paper Coffee UI",
  "type": "light",
  "colors": {
    "editor.background": "#f8f6f1",
    "editor.foreground": "#2b3f6a",
    "editorWidget.background": "#ebe8df"
  },
  "tokenColors": [],
  "variables": {
    "--form-field-border-override": "rgba(110, 78, 68, 0.35)",
    "--form-field-bg-override": "rgba(255, 253, 249, 0.6)",
    "--form-field-focus-border-override": "#6e4e44",
    "--timeline-block-bg-override": "rgba(110, 78, 68, 0.06)",
    "--timeline-item-border-override": "rgba(110, 78, 68, 0.35)",
    "--timeline-badge-text-override": "#2b3f6a",
    "--status-pill-text-override": "#2b3f6a",
    "--md-search-capsule-border-override": "rgba(110, 78, 68, 0.3)",
    "--workspace-btn-bg-override": "rgba(224, 218, 211, 0.55)",
    "--workspace-btn-border-override": "rgba(110, 78, 68, 0.3)",
    "--editor-btn-text-override": "#2b3f6a",
    "--editor-btn-bg-override": "rgba(255, 253, 249, 0.6)",
    "--editor-btn-border-override": "rgba(110, 78, 68, 0.3)",
    "--editor-btn-hover-bg-override": "rgba(110, 78, 68, 0.12)",
    "--editor-switch-btn-bg-override": "#e4dcc8",
    "--editor-switch-btn-hover-bg-override": "#d2b493",
    "--code-toolbar-bg-override": "rgba(224, 218, 211, 0.55)",
    "--code-toolbar-border-override": "rgba(110, 78, 68, 0.3)",
    "--code-toolbar-hover-bg-override": "rgba(110, 78, 68, 0.12)",
    "--code-toolbar-text-override": "#2b3f6a",
    "--code-search-capsule-bg-override": "rgba(248, 246, 241, 0.25)",
    "--code-search-capsule-focus-border-override": "#6e4e44",
    "--file-meta-item-bg-override": "rgba(255, 253, 249, 0.6)"
  }
}

הערה

ערכה שאינה מצהירה על הטוקנים מרונדרת ללא שינוי, וכך גם התצוגה המקדימה של ערכה מובנית מתוך אשף הערכות: כל טוקן נקרא בכלל שצובע היום את הרכיב, עם fallback לערך שנצבע בו, והבורר של הכלל לא השתנה. במקומות שבהם ל-Rose Pine Dawn יש כלל משלה — השדות בעמודי העריכה וההעלאה, הפיד והפוש, שורת החיפוש בתצוגת ה-Markdown, הכפתורים שמעל העורך ו“מסך מלא“ — הכלל שלה ספציפי יותר וממשיך לגבור. בשורת החיפוש של תצוגת ה-Markdown ה-fallback הוא transparent, הגבול של הכלל הכללי, וכלל ה-:focus-within ספציפי יותר מהכלל שקורא את הווו, ולכן בזמן הקלדה הגבול נשאר שלו. בתצוגת הקוד כלל ה-:focus-within קורא וו משלו, --code-search-capsule-focus-border-override. ב“שולחן עבודה“ הריחוף נשאר כמו שהוא, כמו בשאר הכפתורים בשורה: הרקע מגיע מ-.btn-secondary:hover, וה-box-shadow מ-.categories-section .btn:hover ב-webapp/templates/files.html, שספציפי יותר מהכלל של המסגרת ולכן מחליף אותה בזמן הריחוף. tests/services/test_theme_variables_light_import_hooks.py נועל את החוזה, כולל הדוגמה שלמעלה, וגם כאן ערכה שכבר קיימת בחשבון מקבלת את הטוקנים רק אחרי ייבוא מחדש. מה נמדד ב-31.10.2026, על הדוגמה שלמעלה עם הרקע של Pen Paper Coffee, מול הפיקסל האמיתי שמאחורי כל רכיב: הטקסט בתגים ובבאדג« עלה מניגודיות של 1.18–1.35 ל-5.75–7.18, והגבול של השדות מ-1.06 ל-1.51. בערכות שאינן מצהירות — Classic, Dark, Rose Pine Dawn, High Contrast, ערכה מיובאת כהה וערכה מיובאת בהירה — הרכיבים זהים למה שהיו לפני הווים, גם בפוקוס ובתצוגה המקדימה. ומה נמדד ב-15.11.2026, כשנוספו הווים של ”שולחן עבודה“, הכפתורים שמעל העורך ותצוגת הקוד, בדפדפן ומול הקוד שלפני השינוי: בערכות שאינן מצהירות — Classic, Dark, Rose Pine Dawn, High Contrast, ערכה מיובאת כהה וערכה מיובאת בהירה בלי ווים — ובתצוגה מקדימה של Ocean מתוך ערכה שמצהירה, כל הרכיבים האלה זהים למה שהיו, במצב רגיל, בריחוף ובפוקוס.

צבעי המסמך: כותרות, הדגשה, קוד בשורה וציטוט

בתצוגת ה-Markdown (md_preview.html) ובתצוגה החיה בעמודי העריכה וההעלאה, ערכה מיובאת מבדילה בין חלקי המסמך רק בשני צבעי טקסט: כותרות ורשימות ב---text-primary (מ-editor.foreground, ו-input.foreground דורס אותו כשהוא בקובץ), ופסקאות — גם בתוך ציטוט — ב---text-secondary (מ-sideBar.foreground), בכלל ה-Typography של webapp/static/css/dark-mode.css שצובע כל p, ולא בירושה מ-#md-content. כששני המפתחות זהים בקובץ, כמו ב-morass, כל המסמך יוצא בצבע אחד.

אין לזה מקור בקובץ הערכה. התצוגה המרונדרת של VS Code עצמו צובעת כותרות והדגשה ב-editor.foreground, בלי מפתח משלהן; רק לקישור (textLink.foreground), לקוד בשורה (textPreformat.foreground), לציטוט (textBlockQuote.background / textBlockQuote.border) ולבלוק קוד (textCodeBlock.background) יש מפתח — נקרא ב-microsoft/vscode@864824b4, בקבצים src/vs/workbench/contrib/webview/browser/pre/index.html ו-extensions/markdown-language-features/media/markdown.css. markup.heading, markup.bold ושכניהם ב-tokenColors אינם צבעי המסמך: הם צובעים את מקור ה-Markdown בעורך, דרך הדקדוק של TextMate, ובמערכת שלנו הם הופכים להדגשת תחביר בבלוקי קוד (הדגשת התחביר בפרסום).

לכן אלה ווים מאותו סוג של הקודמים: ערכה בודדת שרוצה מסמך צבעוני מצהירה עליהם בבלוק variables, וערכה שאינה מצהירה נשארת כמו היום. הם נקראים ב-webapp/static/css/md-content-colors.css, בכללים שחלים רק בתוך #md-content ורק בערכה מיובאת או משותפת:

  • --md-heading-color-override — כותרות H1 ו-H2. בלעדיו: --text-primary.

  • --md-subheading-color-override — כותרות H3 עד H6. בלעדיו: --text-primary.

  • --md-strong-color-override — הדגשה (strong ו-b), גם בתוך רשימה וציטוט. בלעדיו: הצבע שההדגשה יורשת מהטקסט שסביבה.

  • --md-inline-code-color-override — קוד בשורה. בלעדיו: --code-text (מ-terminal.foreground).

  • --md-blockquote-border-override — הפס של הציטוט. בלעדיו: --md-blockquote-border, צבע הטקסט בשקיפות.

  • לקישור אין טוקן חדש: הוא כבר נקרא מ---link-color, ובערכה שאין בה textLink.foreground אפשר להצהיר עליו באותו בלוק.

הדוגמה של morass — הצבעים שנבחרו לה מתוך הצבעים שכבר יש בקובץ שלה, וגם --primary רך יותר מה-focusBorder שהמייבא גוזר:

"variables": {
  "--primary": "#E1C636",
  "--md-heading-color-override": "#E1C636",
  "--md-subheading-color-override": "#cfd394",
  "--md-strong-color-override": "#dcdcaa",
  "--link-color": "#7fdbca",
  "--md-inline-code-color-override": "#b5cea8",
  "--md-blockquote-border-override": "#E1C636"
}

הערה

ערכה שאינה מצהירה על הטוקנים מרונדרת ללא שינוי. הקוד בשורה והציטוט נקראים בכללים שצובעים אותם היום, ו-fallback של כל טוקן הוא הערך שנצבע שם. לכותרות ולהדגשה אין במסמך כלל משלהן: הכותרות נצבעות היום בכלל ה-Typography של webapp/static/css/dark-mode.css, שחל על כל כותרת באתר, וההדגשה יורשת את צבע הטקסט שסביבה. לכן נוספו להן כללים שחלים רק בתוך #md-content — לכותרות עם fallback לאותו --text-primary, ולהדגשה עם fallback ל-inherit. כותרות בממשק, מחוץ למסמך, לא מושפעות. tests/services/test_theme_variables_md_document_colors_hook.py נועל את החוזה, ו-tests/test_md_document_colors_hook_browser.py מודד בדפדפן את שתי התצוגות, בערכה אישית ובערכה שפורסמה לציבורית. מצבי הרקע של תצוגת המסמך (ספיה ושאר הגוונים) לא חלים כאן: הם מוצעים רק בערכות מובנות בהירות (ALLOWED_THEMES ב-md_preview.html). וכמו בכל וו, ערכה שכבר קיימת בחשבון מקבלת את הטוקנים רק אחרי ייבוא מחדש, וערכה ציבורית — אחרי פרסום מחדש.

שם הקובץ ותיאורו: כרטיס הקובץ ותצוגות הקובץ

שם הקובץ מוצג ככותרת בכרטיס הקובץ בעמוד הקבצים, ובראש תצוגת הקוד (/file/<id>), תצוגת ה-Markdown (/md/<id>) ותצוגת ה-HTML (/html/<id>). בערכה מיובאת או משותפת הוא נצבע בכלל ה-Typography של webapp/static/css/dark-mode.css שצובע כל כותרת, ב---text-primary. התיאור — בכרטיס ובתצוגת הקוד; לשתי התצוגות האחרות אין תיאור — נצבע בכלל הפסקאות שם, ב---text-secondary. והשורות, הגודל והתאריכים בכרטיס לא נצבעים בשום כלל: הם יורשים את צבע הטקסט. כש-editor.foreground ו-sideBar.foreground זהים בקובץ, כמו ב-morass, כל הכרטיס יוצא בצבע אחד.

גם כאן אלה ווים מאותו סוג: ערכה בודדת מצהירה על צבעים בבלוק variables, וערכה שאינה מצהירה נשארת כמו היום. הם נקראים ב-dark-mode.css, בכללים שחלים רק בערכה מיובאת או משותפת, על class שנמצא על האלמנט שמציג את השם או את התיאור בכל אחד מהעמודים:

  • --file-name-color-override — שם הקובץ (.file-name-text), בכרטיס ובשלוש התצוגות. בתצוגת ה-HTML השם הוא חלק מהכותרת ”תצוגת דפדפן: <שם>“, וה-class נמצא רק על השם: התחילית נשארת בצבע של הכותרת. בלעדיו: --text-primary.

  • --file-description-color-override — התיאור (.file-description-text), בכרטיס ובתצוגת הקוד. בלעדיו: --text-secondary.

  • --file-card-meta-color-override — השורות, הגודל והתאריכים בכרטיס (.file-card-meta), כולל האייקונים של התאריכים. בלעדיו: הצבע שהם יורשים. השקיפות שלהם נקבעת ב-style שבתגית ב-webapp/templates/files.html ונשארת, ולכן הצבע שנבחר נראה על הכרטיס כהה מהערך שבבלוק — את הניגודיות כדאי לבדוק אחרי השקיפות.

  • התגיות וכפתורי הפעולה בכרטיס לא מושפעים.

הדוגמה של morass — בז« לשם, ירוק חיוור למטא, והתיאור ב-#e4e3e1, צבע הטקסט של הערכה, כלומר כמו היום:

"variables": {
  "--file-name-color-override": "#dcdcaa",
  "--file-description-color-override": "#e4e3e1",
  "--file-card-meta-color-override": "#b5cea8"
}

הערה

ערכה שאינה מצהירה על הטוקנים מרונדרת ללא שינוי: ה-fallback של השם הוא ה---text-primary של כלל הכותרות, של התיאור ה---text-secondary של כלל הפסקאות, ושל המטא inherit. הבורר ([data-theme="custom"] .file-name-text ושכניו) ספציפי יותר מכללי ה-Typography, ולכן הוא גובר עליהם בלי תלות בסדר. הוא [data-theme="custom"] ולא [data-theme-type="custom"], מאותה סיבה כמו בכפתורי primary: סנכרון הערכה בין טאבים (initThemeCrossTabSync ב-base.html) מחליף את data-theme לערכה מובנית שנבחרה בטאב אחר ומשאיר את data-theme-type, וכלל שנשען עליו היה ממשיך לחול בטאב הזה על הערכה המובנית. בערכה מובנית ה-class אינו משנה דבר. tests/services/test_theme_variables_file_name_hook.py נועל את החוזה — כולל שה-class נמצא בכל תבנית על האלמנט שהטקסט שלו הוא השם או התיאור — ורץ גם בלי דפדפן; tests/test_file_name_colors_hook_browser.py מודד בדפדפן את ארבעת העמודים, בערכה אישית, בערכה שפורסמה לציבורית ובערכות מובנות. וכמו בכל וו, ערכה שכבר קיימת בחשבון מקבלת את הטוקנים רק אחרי ייבוא מחדש, וערכה ציבורית — אחרי פרסום מחדש.

ערכת מסמך: ערכה שחלה רק על תצוגת ה-Markdown

יש ערכות שנראות מצוין במסמך ופחות טוב בשאר הממשק — למשל ערכה בהירה בגוון נייר. ערכת מסמך מחילה ערכה כזו רק על הכרטיס ”תצוגת Markdown“ בעמוד /md/<id> (#mdCard ב-webapp/templates/md_preview.html), והממשק סביבו נשאר בערכה הפעילה: דף נייר בהיר על שולחן כהה. הכרטיס כולו עובר — הכותרת ”תצוגת Markdown“, שורת החיפוש, הכפתורים שבו והמסמך עצמו, כולל קוד בשורה, בלוקי קוד והדגשת התחביר שלהם, ציטוטים, טבלאות, הקטעים המתקפלים והדיאגרמות. מה שמעליו — סרגל הניווט, שם הקובץ והכפתורים ”חזרה“ ו“ערוך“ — נשאר בערכת הממשק.

איפה בוחרים. בשני מקומות. בגלריית הערכות (/settings/theme-gallery), בלשונית ”ייבוא“: התיבה ”ערכת המסמך“ מציגה מה פעיל, ובוחרים בה ערכה אישית או ציבורית, או ”ללא ערכת מסמך“ כדי לכבות. ליד הייבוא יש תיבת סימון ”להחיל את הערכה שמייבאים רק על תצוגת המסמך“: אחרי ייבוא מוצלח הערכה החדשה נבחרת כערכת המסמך. מסלול הייבוא עצמו (POST /api/themes/import) לא השתנה — הבחירה היא קריאה שנייה, ל-/api/ui_prefs.

ובכל עמוד — במודאל ערכות הנושא שנפתח מתפריט קיצורי הדרך (”ערכת נושא“), דרך המתג ”ערכת ממשק / ערכת מסמך“ שבראשו. במצב ”ערכת מסמך“ הרשת מציגה את הכרטיס ”ללא ערכת מסמך“ ואחריו רק ערכות אישיות וציבוריות (הטאב ”מובנות“ מוסתר); הכרטיס של ערכת המסמך הנוכחית מסומן, ולחיצה על כרטיס אחר הופכת אותו לערכת המסמך, או מכבה אותה. עד שהשמירה חוזרת כל הכרטיסים נעולים (docSaving ב-initThemePicker): בחירה שנייה הייתה נבדקת מול הבחירה הקודמת, שעוד לא התעדכנה, ושתי שמירות במקביל היו מסתיימות בסדר שאין עליו שליטה. כשערכת הממשק מובנית מופיעה הערה שהבחירה נשמרת אבל רדומה (ראו ”מתי היא חלה“ למטה); התנאי שהמודאל בודק הוא MD_DOC_THEME_UI_CONDITION, החצי של MD_DOC_THEME_ROOT_SELECTOR שעוסק בערכת הממשק. בעמוד מסמך, כשערכת המסמך חלה, העמוד נטען מחדש כדי שהכרטיס יקבל אותה; בכל עמוד אחר הרשת פשוט מתעדכנת. הבחירה נשמרת בתחולה שמוגדרת במכשיר (ה-cookie MD_DOC_THEME_SCOPE_COOKIE, ולכל המכשירים כשאין), כך שבחירה ”רק במכשיר הזה“ נשארת במכשיר. כל פתיחה של המודאל מתחילה ב“ערכת ממשק“, שהיא המודאל כמו שהיה.

מתי היא חלה. רק כשערכת הממשק מותאמת או ציבורית. בערכה מובנית (Classic, Nebula, ניגודיות גבוהה ושאר המובנות) הבחירה נשמרת אבל רדומה, והכרטיס בערכת הממשק: הכללים שהערכות המובנות מחילות על הכרטיס שונים מאלה של ערכה מותאמת, ולא רק במשתנים, ולכן משתני ערכת המסמך לבדם לא היו צובעים אותו כמו כשהיא ערכת הממשק. ניגודיות גבוהה היא ערכת נגישות שכופה צבעים בכוונה, ולכן גם לא הייתה אמורה לקבל ערכה אחרת. התנאי כתוב בבורר אחד, MD_DOC_THEME_ROOT_SELECTOR ב-services/theme_parser_service.py, והוא בודק את data-theme ולא את data-theme-type, מאותה סיבה כמו בווי הדריסה (סנכרון הערכה בין טאבים).

איפה נשמרת הבחירה. ui_prefs.md_doc_theme במסמך המשתמש, בפורמט של ui_prefs.theme: custom:<id> לערכה אישית, shared:<slug> לציבורית, ושדה חסר כשאין ערכת מסמך. זה מצביע לערכה ולא העתק שלה, ולכן עריכה של הערכה בבונה הערכות מגיעה למסמך מעצמה. כמו גודל הטקסט בפתק, אפשר לבחור ”רק במכשיר הזה“: אז הבחירה ב-cookie ui_md_doc_theme ולא במסד, וכיבוי במכשיר נשמר שם כ-MD_DOC_THEME_DEVICE_OFF — כך הוא גובר על בחירה ששמורה במסד. ההכרעה ב-_resolve_md_doc_theme_token (webapp/app.py). מחיקת ערכה אישית מוחקת גם את ui_prefs.md_doc_theme כשהוא מצביע עליה; מצביע שנשאר — ב-cookie של מכשיר אחר, או לערכה ציבורית שכובתה — לא מוצא ערכה, והמסמך מוצג בערכת הממשק.

השמירה. POST /api/ui_prefs עם md_doc_theme (טוקן, או null לכיבוי) ו-md_doc_theme_scope (global / device). ערך שאינו טוקן תקין ← 400, ערכה שלא קיימת ← 404 md_doc_theme_not_found, ומסד שלא ענה ← 503 database_unavailable — כך ”לא נמצא“ ו“נשבר“ לא נראים אותו דבר. במצב global התשובה היא מה שנקרא מהמסד אחרי הכתיבה, ולא מה שנשלח.

הבחירה הנוכחית. שני המסכים קוראים אותה מ-GET /api/ui_prefs/md_doc_theme (api_md_doc_theme_state), ולא מה-HTML של העמוד: המודאל נמצא בכל עמוד, ומצב שמרונדר לתוך ה-HTML היה צריך להיכנס למפתח הקאש ול-ETag של כל עמוד ששומר HTML. התשובה היא ההכרעה של _resolve_md_doc_theme_token — מה שהמסמך יקבל במכשיר הזה — עם השם של הערכה, ו-found: false למצביע לערכה שכבר לא קיימת. מסד שלא ענה ← 503 database_unavailable ולא ”אין ערכת מסמך“ (strict ב-_resolve_md_doc_theme_token): עד שהבחירה ידועה המודאל לא מציג כרטיסים, והתיבה בגלריה מושבתת — אחרת ”ללא“, שמוצג כברירת מחדל, היה נראה כמו המצב, ולחיצה הייתה מכבה. מאותה סיבה גם תיבת הסימון שליד הייבוא נעולה עד אז: היא שומרת בתחולה שבבורר, ועד שהשרת ענה הבורר מציג ”לכל המכשירים“ גם למי שבחר ”רק במכשיר הזה“. השמירה עצמה (saveDocTheme ב-theme-importer.js) מסרבת כשהבחירה לא ידועה, כך שאף מסלול לא שומר בתחולה שלא נקראה. מה ששני המסכים צריכים — הטוקן של ערכה מתוך /api/themes/list, הקריאה והשמירה, עם תקרת זמן לכל בקשה — כתוב פעם אחת, ב-webapp/static/js/utils/md-doc-theme.js (window.CkMdDocTheme).

איך זה בנוי

המטרה מוגדרת במדויק: כל אלמנט בכרטיס צריך להיראות בדיוק כמו כשערכת המסמך היא ערכת הממשק. משתני CSS עוברים בירושה, ולכן הבסיס פשוט — המשתנים של ערכת המסמך מוצהרים על הכרטיס (build_md_doc_theme_css, בבלוק <style id="md-doc-theme">), וכל כלל בתוך הכרטיס שקורא משתנה מקבל אותם. אבל ארבעה דברים היו נשארים מערכת הממשק, וכל אחד מטופל:

  • משתנה ברשימה הלבנה שערכת המסמך לא מצהירה עליו — בעיקר ווי הדריסה: הכותרות הצהובות של morass היו מגיעות למסמך של ערכה שלא מצהירה על --md-heading-color-override. build_md_doc_theme_css מאפס כל משתנה כזה ל-initial, כלומר ”לא מוגדר“, כמו בערכה שאינה מצהירה עליו.

  • ברירות המחדל של הצבעים. משתנה שגם ערכת המסמך לא מצהירה עליו וגם אינו וו — --secondary, למשל, שממנו נגזר צבע שמות הפונקציות בקוד כשלערכה אין tokenColors — מגיע בעמוד רגיל מבלוק ה-:root של base.html. הבלוק הזה חל גם על הכרטיס (הבורר השני שלו), ולכן הכרטיס חוזר אליהן לפני שהמשתנים של ערכת המסמך דורסים. מה שאינו צבע — --ui-font-scale ו---scrollbar-width — בבלוק :root נפרד, כי הוא חייב לחול רק על השורש.

  • משתנים שנגזרים ממשתנים אחרים על :root — הנייר (--md-paper-* ב-md-content-colors.css) וצבעי הקטעים המתקפלים והסימון (ב-markdown-enhanced.css). הם מחושבים פעם אחת על השורש ועוברים לכרטיס כצבע הסופי של ערכת הממשק. הבלוקים שלהם חלים גם על הכרטיס, ושם הם נגזרים שוב מצבעי ערכת המסמך.

  • הדגשת התחביר. הכללים של ערכת הממשק מוזרקים לכל העמוד עם !important. בעמוד שיש בו ערכת מסמך base.html מעביר אותם דרך exclude_md_doc_theme_from_hljs_css, וכל כלל highlight.js מקבל תנאי שמוציא את הכרטיס — בלי לשנות את הספציפיות שלו, ובלי לגעת בכללים אחרים. הכללים של ערכת המסמך נכנסים לכרטיס דרך rebase_hljs_css (שנכתב לייצוא), עם הכלל הבסיסי .hljs (include_base). בכל עמוד אחר ה-CSS של ערכת הממשק יוצא כמו שהוא.

ועוד שני חלקים קטנים: רקע הכרטיס הוא הרקע של העמוד של ערכת המסמך עם שכבת הזכוכית מעליו (הכלל ב-md_preview.html), כי מאחוריו עמוד בערכה אחרת; ובחירת הבהיר או הכהה של Mermaid נעשית לפי --bg-primary של הכרטיס.

הקאש. ה-CSS של ערכת המסמך מרונדר לתוך ה-HTML, ולכן _md_doc_theme_etag_key — הטוקן וה-updated_at של הערכה — נכנס ל-ETag של /md/<id> ולמפתח הקאש שלו. בלי זה בחירה, כיבוי או עריכה של הערכה היו מחזירים 304 עם המראה הישן. המפתח נוסף רק כשיש ערכת מסמך, ולכן מי שאין לו כזו מקבל את אותו ETag כמו קודם.

מה לא עובר לערכת המסמך

  • הפתקים הדביקים: הם לא בתוך הכרטיס (נתלים על העמוד), ויש להם נייר משלהם בכל ערכה.

  • תוכן העניינים הצף: מחוץ לכרטיס.

  • צבעים שקבועים בכל ערכה: כותרות ה-callouts (.admonition-* ב-markdown-enhanced.css) והרקע השקוף שלהן, הסימון ==טקסט==, ה-# ליד כותרות וכפתור ”העתק כמארקדאון“. הם נראים בדיוק כמו כשערכת המסמך היא ערכת הממשק — הם פשוט לא באים מאף ערכה.

  • בורר צבעי הרקע (”נייר חם“ ודומיו) מוצג רק בערכות מובנות בהירות, ולכן לא מופיע כשערכת המסמך פעילה.

  • מחוץ להיקף: מצב קריאה (עמוד נפרד), תצוגת השיתוף /share/<id>, התצוגה החיה בעמוד העריכה ותצוגת ה-Markdown של דפדפן הריפו.

הערה

ממצא שלא תוקן כאן: ערכה ציבורית כערכת ממשק מקבלת היום דיאגרמות Mermaid כהות גם כשהיא בהירה — ההחלטה ב-md_preview.html מחשבת בהירות רק כש-data-theme הוא custom. בכרטיס של ערכת מסמך ההחלטה היא לפי הבהירות גם לערכה ציבורית. תיקון בעמוד הרגיל היה משנה את המראה של ערכות ציבוריות קיימות, ולכן הוא נשאר להחלטה נפרדת.

tests/test_md_doc_theme_browser.py מודד בדפדפן את הכרטיס מול העמוד שבו ערכת המסמך היא ערכת הממשק — כל אלמנט, כולל פסאודו-אלמנטים, ריחוף ופוקוס — בכהה עם בהירה ולהפך, בערכה בלי tokenColors ובערכה ציבורית בשני הצדדים; בודק שמחוץ לכרטיס דבר לא השתנה; ושבערכה מובנית ערכת המסמך רדומה. הוא גם מפעיל את שני המסכים דרך הממשק שלהם: את התיבה בגלריה, ואת המצב ”ערכת מסמך“ במודאל — מעבר וכיבוי שהכרטיס עוקב אחריהם, בחירה שנשארת במכשיר, ההערה בערכת ממשק מובנית, עדכון בלי טעינה מחדש בעמוד שאין בו הכרטיס, מסך בלי כרטיסים כשהבחירה הנוכחית לא נטענה, שמצב ”ערכת ממשק“ חוזר בדיוק למה שהיה, שכל עוד שמירה לא חזרה שום בחירה נוספת לא יוצאת מהמודאל, ושייבוא בגלריה לא מחיל ערכה על המסמך לפני שהבחירה הנוכחית נקראה — בשניהם הטסט מחזיק את הבקשה בדרך. tests/test_md_doc_theme.py בודק בלי דפדפן את השמירה, הבחירה הנוכחית, ה-ETag, ה-HTML, ושהבורר של השורש זהה בכל הקבצים שכותבים אותו.

הדגשת תחביר (Syntax Highlighting)

כאשר מייבאים ערכת VS Code עם tokenColors, parse_vscode_theme ממיר אותם אוטומטית ל-syntax_css עם שלוש קבוצות כללים, אחת לכל מנוע צביעה: CodeMirror בעורך (generate_codemirror_css_from_tokens), highlight.js בבלוקי הקוד של Markdown (generate_hljs_css_from_tokens), ו-Pygments (generate_pygments_css_from_tokens). מה שעובר מהן בפרסום לציבורית — הדגשת התחביר בפרסום.

ארכיטקטורה

זרימת המרת צבעים מ-VS Code ל-CodeMirror:

tokenColors (VS Code)
     │
     ▼
VSCODE_TO_CM_TAG מיפוי
     │
     ▼
syntax_colors JSON
     │
     ▼
HighlightStyle.define() (CodeMirror)

מיפוי VS Code Scopes ל-CodeMirror Tags

VS Code Scope

CodeMirror Tag

הערות

comment

comment

הערות

comment.block.documentation

docComment

תיעוד

string

string

מחרוזות

string.regexp

regexp

Regex

keyword

keyword

מילות מפתח

keyword.control

controlKeyword

if, for, while

keyword.control.import

moduleKeyword

import, export

storage.type

definitionKeyword

def, class

entity.name.function

function(definition(variableName))

הגדרת פונקציה

meta.function-call

function(variableName)

קריאה לפונקציה

support.function.builtin

standard(function(variableName))

פונקציות מובנות

variable

variableName

משתנים

variable.parameter

local(variableName)

פרמטרים

variable.language.self

self

self, this

constant.numeric

number

מספרים

constant.language.boolean

bool

true, false

entity.name.class

definition(className)

שם מחלקה

entity.name.type

typeName

שם טיפוס

keyword.operator

operator

אופרטורים

entity.name.tag

tagName

תגיות HTML

entity.other.attribute-name

attributeName

מאפיינים

מנגנון Fallback

כאשר ערכה לא מגדירה צבע לתג ספציפי, המערכת יורשת מתגים הוריים:

function(definition(variableName))
     │
     ├── יורש מ-definition(variableName)
     │        │
     │        └── יורש מ-variableName
     │                 │
     │                 └── יורש מ-name
     │
     └── יורש מ-function(variableName)
              │
              └── יורש מ-variableName

דוגמה:

אם הערכה מגדירה צבע רק ל-variableName, כל ההגדרות שיורשות ממנו יקבלו את אותו הצבע עד שתוגדר דריסה ספציפית.

CodeMirror CSS Classes

מעבר ל-Tags המשמשים ב-HighlightStyle.define(), המערכת תומכת גם ב-CSS Classes עבור classHighlighter. אלו מאפשרים דריסה ישירה ב-CSS:

Classes בסיסיים:

CSS Class

תיאור

.tok-comment

הערות

.tok-string, .tok-string2

מחרוזות (רגילות / template)

.tok-keyword

מילות מפתח

.tok-number

מספרים

.tok-operator

אופרטורים

.tok-punctuation

סימני פיסוק

.tok-atom, .tok-bool

קבועים וערכי boolean

.tok-literal

ערכים ליטרליים

משתנים ופונקציות:

CSS Class

תיאור

.tok-variableName

משתנים רגילים

.tok-variableName.tok-definition

הגדרות משתנים (צבע שונה)

.tok-variableName.tok-local

משתנים מקומיים (לעתים עם italic)

.tok-variableName2

משתנים מיוחדים (self, this, super)

.tok-function

פונקציות

.tok-macroName

מאקרו / decorators

טיפוסים ומחלקות:

CSS Class

תיאור

.tok-className

שמות מחלקות

.tok-typeName

שמות טיפוסים

.tok-namespace

namespaces / modules

.tok-propertyName

שמות properties

.tok-propertyName.tok-definition

הגדרות properties

HTML/XML:

CSS Class

תיאור

.tok-tagName

תגיות HTML/XML

.tok-attributeName

מאפיינים

.tok-angleBracket

סוגריים זוויתיים < >

עיצוב טקסט (Markdown):

CSS Class

תיאור

.tok-heading

כותרות

.tok-emphasis

טקסט נטוי (italic)

.tok-strong

טקסט מודגש (bold)

.tok-link, .tok-url

קישורים

.tok-quote

ציטוטים

.tok-monospace

קוד inline

מיוחדים:

CSS Class

תיאור

.tok-meta

מטא-דאטה

.tok-labelName

labels

.tok-inserted

שורות שנוספו (git diff)

.tok-deleted

שורות שנמחקו (git diff)

.tok-changed

שורות ששונו

.tok-invalid

קוד לא תקין

דוגמת CSS לדריסה:

/* דריסת צבע הגדרות פונקציות */
:root[data-theme="custom"] .tok-variableName.tok-definition {
    color: #7aa2f7 !important;
    font-weight: bold !important;
}

/* משתנים מקומיים באיטליק */
:root[data-theme="custom"] .tok-variableName.tok-local {
    color: #bb9af7 !important;
    font-style: italic !important;
}

/* self/this בצבע מיוחד */
:root[data-theme="custom"] .tok-variableName2 {
    color: #f7768e !important;
}

/* שורות שנוספו בדיף */
:root[data-theme="custom"] .tok-inserted {
    color: #9ece6a !important;
    background: rgba(158, 206, 106, 0.1);
}

/* שורות שנמחקו בדיף */
:root[data-theme="custom"] .tok-deleted {
    color: #f7768e !important;
    background: rgba(247, 118, 142, 0.1);
}

הערה

ה-!important נדרש כדי לדרוס את ה-inline styles שמוזרקים על ידי CodeMirror themes. הסלקטור :root[data-theme="custom"] מבטיח שהדריסות יחולו רק כשערכה מותאמת פעילה.

אבטחה וולידציה

ולידציית צבעים

המערכת מאפשרת רק פורמטים בטוחים:

פורמטים נתמכים:

#fff          Hex קצר (3 תווים)
#ffff         Hex עם alpha (4 תווים)
#ffffff       Hex מלא (6 תווים)
#ffffffff     Hex עם alpha (8 תווים)
rgb(r, g, b)  RGB (ערכים 0-255)
rgba(r, g, b, a)  RGBA עם שקיפות (alpha 0-1)

ערכים חסומים (אבטחה):

url(...)          CSS injection
expression(...)   IE legacy injection
javascript:       XSS
data:             Data URI injection
@import           CSS import injection

סניטציה

המערכת מבצעת מספר שלבי ניקוי:

  1. הסרת הערות JSONC – לפני פרסור ה-JSON

  2. בדיקת תקינות JSON – וולידציה של מבנה הקובץ

  3. ולידציית צבעים – לפי ה-Regex המגביל

  4. בדיקת whitelist – רק משתנים מוכרים מותרים

  5. הגבלת גודל – מניעת קבצים גדולים מדי

אזהרה

לא כל ערך פסול מטופל באותה דרך, וההבדל חשוב:

  • ערך פסול בבלוק variables — הייבוא נדחה עם 400, וההודעה מציינת את המפתח.

  • מפתח שאינו ברשימה הלבנה — עובר את הוולידציה ואז מסונן בשקט, עם אזהרה בלוג.

  • ערך פסול בתוך colors — עובר את הוולידציה, והטוקן שהוא ממופה אליו נופל לערך ברירת המחדל, עם אזהרה בלוג.

כלומר שתי הצורות האחרונות אינן מפילות את הייבוא. אם ערכה נשמרה אך צבע מסוים אינו מופיע, זו הסיבה הסבירה.

API Reference

Endpoints

רשימת ערכות:

GET /api/themes

מחזיר רשימת כל הערכות של המשתמש (ללא variables הכבדים).

פרטי ערכה:

GET /api/themes/<id>

מחזיר ערכה מלאה כולל variables לעריכה.

יצירת ערכה:

POST /api/themes
Content-Type: application/json

{
  "name": "My Theme",
  "variables": {...}
}

ייבוא ערכה:

POST /api/themes/import
Content-Type: application/json

{
  "json_content": "{...JSON content...}"
}

הפורמט מזוהה מתוך התוכן עצמו ולא נמסר כפרמטר: קובץ שיש בו מפתח colors מפורסר כערכת VS Code, וכל השאר כפורמט המקומי. לחלופין אפשר להעלות ב-multipart/form-data תחת השדה file, בסיומת .json.

עדכון ערכה:

PUT /api/themes/<id>
Content-Type: application/json

{
  "name": "Updated Name",
  "variables": {...}
}

הפעלת ערכה:

POST /api/themes/<id>/activate

מפעיל את הערכה (מכבה את כל האחרות) ומעדכן ui_prefs.theme="custom".

ביטול הפעלה:

POST /api/themes/deactivate

מבטל את כל הערכות המותאמות וחוזר ל-Classic.

מחיקת ערכה:

DELETE /api/themes/<id>

מוחק ערכה. אם הייתה פעילה – חוזרים ל-Classic.

מבנה תגובה

{
  "success": true,
  "theme": {
    "id": "uuid-string",
    "name": "My Theme",
    "description": "תיאור הערכה",
    "is_active": true,
    "source": "vscode",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "variables": {
      "--bg-primary": "#1a1b26"
      // ... additional variables
    },
    "syntax_css": "/* CodeMirror CSS */",
    "syntax_colors": {
      "keyword": {"color": "#7aa2f7"}
      // ... additional colors
    }
  }
}

פרסום ערכה לציבורית (Shared Themes)

אדמינים יכולים לפרסם ערכות אישיות לכל המשתמשים.

מבנה נתונים ב-DB

ערכות ציבוריות נשמרות ב-collection shared_themes:

{
  "_id": "cyber_purple",           // slug ייחודי
  "name": "Cyber Purple",          // שם לתצוגה
  "description": "ערכה סגולה",
  "colors": {                      // CSS variables (מסונן לפי whitelist)
    "--bg-primary": "#0d0221",
    "--primary": "#7b2cbf"
  },
  "syntax_css": "...",             // CSS להדגשת תחביר, אחרי sanitize_syntax_css
  "syntax_colors": {               // מילון צבעים ל-HighlightStyle דינמי
    "keyword": {"color": "#7b2cbf"}
  },
  "created_by": 6865105071,
  "created_at": ISODate("..."),
  "is_active": true,
  "is_featured": false
}

שמירת משתנים בפרסום

בבונה הערכות (theme_builder.html), הקוד שומר את המשתנים המקוריים כדי שלא יאבדו בפרסום:

// משתנים לשמירת נתונים מקוריים
let currentThemeOriginalVariables = {};  // כל משתני CSS
let currentThemeSyntaxCss = '';          // CSS להדגשת תחביר
let currentThemeSyntaxColors = {};       // מילון צבעים דינמי

// בטעינת ערכה
currentThemeOriginalVariables = { ...theme.variables };
currentThemeSyntaxCss = theme.syntax_css || '';
currentThemeSyntaxColors = theme.syntax_colors || {};

// בפרסום - מיזוג: משתנים מקוריים + ערכי טופס
const colors = {
  ...currentThemeOriginalVariables,  // משתנים שאינם בטופס
  ...collectThemeValues(),           // ערכי הטופס (דורסים)
};

טיפ

משתנים כמו --link-color ו---code-bg אינם בטופס אך נשמרים מהערכה המקורית, כך שצבעי קישורים וקוד לא נאבדים בפרסום.

הדגשת התחביר בפרסום

ה-syntax_css של הערכה האישית נשלח עם הפרסום, וגם בעדכון של ערכה ציבורית, ו-SharedThemeService מנקה אותו ב-sanitize_syntax_css לפני שמירה. הניקוי מקבל את שלוש הקבוצות ש-parse_vscode_theme מייצר, כל אחת בבורר שהמחולל שלה כותב, ואת הכלל הבסיסי .hljs עם הרקע של העורך — כך שערכה ציבורית נצבעת כמו הערכה האישית שממנה פורסמה. tests/services/test_sanitize_syntax_css.py מריץ את המחוללים על כל ה-scopes שבמפות שלהם, ונכשל אם כלל שהם כותבים לא עובר.

  • כלל שלא עבר — מערכה ישנה בפורמט קודם, או מ-CSS שנערך ביד — לא נשמר. הפרסום מצליח, והתשובה מחזירה כמה כללים לא עברו (syntax_rules_dropped). בונה הערכות מציג אז אזהרה במקום הודעת הצלחה, ובלוג נרשמת אזהרה.

  • syntax_css שאינו מחרוזת ← 400 invalid_syntax_css, ו-syntax_css ארוך מ-MAX_SYNTAX_CSS_LENGTH ← 400 syntax_css_too_long עם max. בשני המקרים לא נשמר דבר — לא CSS ריק ולא CSS קטוע.

עד נובמבר 2026 הפרסום עבר דרך sanitize_codemirror_css, שמכיר רק את כללי CodeMirror. ערכה ציבורית איבדה בשקט את כללי highlight.js ו-Pygments, ובלוקי קוד ב-Markdown נצבעו בפלטה שנגזרת ממשתני הממשק (md-content-colors.css) במקום בצבעים של הערכה. ערכה ציבורית שפורסמה לפני התיקון נשארת כך עד שמפרסמים אותה מחדש מהערכה האישית: tokenColors לא נשמרים עם הערכה, ולכן אין ממה לשחזר את הכללים.

פתרון בעיות (Troubleshooting)

בעיות נפוצות

”קובץ JSON לא תקין“:

  • בדקו שאין הערות שגויות (// בתוך מחרוזת)

  • ודאו שכל הסוגריים מאוזנים

  • בדקו שאין פסיקים מיותרים בסוף

צבעים לא מופיעים:

  • ודאו שפורמט הצבע תקין (#fff, #ffffff, rgb(...))

  • בדקו שהמשתנה נמצא ברשימת ה-whitelist

  • בדקו את לוג האזהרות בקונסול

הדגשת תחביר לא עובדת:

  • ודאו שהערכה מיובאת מ-VS Code ומכילה tokenColors

  • ערכות שנוצרו ידנית לא כוללות הדגשת תחביר ייחודית

  • בדקו שה-syntax_colors נשמר כראוי

  • בערכה ציבורית: בדקו אם בפרסום הופיעה אזהרה על כללי הדגשה שלא נשמרו (הדגשת התחביר בפרסום)

הערכה לא נשמרת:

  • ודאו שאתם מחוברים למערכת

  • בדקו שלא עברתם את מגבלת 10 הערכות

  • בדקו הרשאות כתיבה למסד הנתונים

דוגמה לייבוא ערכת Nord

  1. הורידו את קובץ nord-theme.json מהריפו הרשמי

  2. פתחו את Theme Builder בהגדרות

  3. לחצו ”ייבוא מ-VS Code“

  4. העלו את הקובץ

  5. שמרו והפעילו

קישורים קשורים

ראה גם

  • מערכת ערכות הנושא והטוקנים החדשה – תיעוד ארכיטקטורת הטוקנים והערכות

  • GUIDES/custom_themes_guide.md – מדריך פנימי מורחב

  • services/theme_parser_service.py – קוד המקור של הפרסור

  • services/theme_presets_service.py – ניהול ערכות מוכנות

  • webapp/static/data/theme_presets.json – קובץ ה-Presets