מערכת ערכות הנושא והטוקנים החדשה
רקע ומוטיבציה
בריפקטור האחרון הוסרו צבעים ייחודיים מקבצים כגון
global_search.cssוהופיעו באגים של black/white zebra, איבוד גרדיאנטים ולבן מסנוור ב‑Live Preview.עדכוני Theme נקודתיים בעבר חזרו לצבעים קשיחים (HEX/RGB) ולכן נשברו ב‑Classic/Ocean/Forest שנוספו מאוחר יותר.
מטרת המערכת החדשה: ריכוז כל המשתנים ב‑שלוש שכבות, צמצום FOUC (קביעת
data-themeעוד לפני טעינת ה‑CSS), שימור נגישות וייחודיות, והגדרה ברורה של מה חייב Override בכל Theme.ההנחיות כאן מחליפות קוד קשיח ותלויות מערכת הפעלה (
prefers-color-scheme) ומייצרות תשתית אחת עבור Theme Builder, Split View, Collections, Markdown Viewer ועוד.
שכבות משתנים וטעינת data-theme
Level 1 – Primitives (:root ב‑``webapp/templates/base.html``)
קבועים לכולם, ומרוכזים בבלוק ה‑<style> שבתוך webapp/templates/base.html, בכלל ה‑:root הגלובלי — זה שפותח ב‑--primary. לכלל הזה יש בורר שני, השורש של ערכת מסמך (MD_DOC_THEME_ROOT_SELECTOR, ערכת מסמך: ערכה שחלה רק על תצוגת ה-Markdown): הכרטיס ”תצוגת Markdown“ חוזר בו לברירות המחדל לפני שהמשתנים של ערכת המסמך דורסים אותן. לכן מה שאינו צבע — --ui-font-scale ו‑--scrollbar-width — יושב ב‑:root נפרד מיד אחריו, וחל רק על השורש. (יש בקובץ עוד :root, בתוך media query של פס הגלילה, שקובע רק את --scrollbar-width.) כאן מגדירים צבעי מותג (–primary, –secondary), צבעי מצב (–success וכו«), טוקני סכנה (–danger-bg, –danger-border, –text-on-warning), ערכי markdown (–md-surface, –md-text), הגדרות כפתור ברירת מחדל וערכי גלאס (–glass*). אין להשתמש ב‑HEX מחוץ לקטע זה.
הערה
המיקום הזה אינו מה שתוכנן. webapp/FEATURE_SUGGESTIONS/css_refactor_plan.md תכנן לרכז את הטוקנים בקובץ ייעודי בשם variables.css, והמימוש הזריק אותם ישירות לתבנית. הקובץ ההוא אינו קיים בריפו, ואין קוד שמנסה לטעון אותו. העמוד הזה מתאר את מה שקיים בפועל.
Level 2 – Semantic Tokens per Theme
בלוקים של :root[data-theme="..."] ב‑webapp/templates/base.html קובעים רקעים (–bg-*), טקסט (–text-*), כרטיסים (–card-*), צבעי קוד, כפתורים (–btn-primary-*) וטוקנים ל‑Split View (–split-preview-*). הבלוקים הקיימים שם הם classic, ocean, rose-pine-dawn, dark, dim, nebula ו‑custom. ל‑High Contrast אין בלוק שם — ראו את הסעיף הייעודי למטה. Dark/Dim/Nebula נשענים גם על static/css/dark-mode.css, שמשתמש באותם ערכים גלובליים.
Level 3 – Component Tokens
נוצר רק כשיש צורכי עיצוב ייחודיים: –search-card-shadow ב‑global_search.css, –bookmarks-panel-bg ב‑bookmarks.css, משפחת –split-* ב‑split-view.css. את ערכי ברירת המחדל מגדירים ברכיב עצמו, אך מומלץ להוסיף הפניה לטוקן סמנטי מ‑base.html (או ל‑:root[data-theme]) כאשר הרכיב חוצה דפים, כדי למנוע חזרה לצבעים קשיחים.
טעינת המערכת
base.html קובע data-theme על <html> מתוך localStorage כבר ב‑<head> כדי למנוע FOUC, והטוקנים עצמם יושבים בבלוק <style> באותה תבנית. כך הם זמינים מיד, עוד לפני טעינת dark-mode.css / high-contrast.css / קבצים ייעודיים. Theme Wizard ו‑Theme Builder מזריקים Overrides דינמיים ל‑<style id="user-custom-theme"> (נוצר בעת שמירת Theme מותאם) ומגדירים data-theme=“custom“ או Override ל‑Theme קיים. על כל סקריפט שמשנה Theme לעדכן גם את localStorage באותה צורה.
תרשים זרימת היררכיית טוקנים
graph TD
subgraph "Global Scope (base.html)"
L1["<b>Level 1: Primitives</b><br/>:root<br/>--primary, --danger, --glass"]
L2["<b>Level 2: Semantic Overrides</b><br/>:root[data-theme='...']<br/>--bg-app, --text-main, --card-bg"]
end
subgraph "Component Scope"
L3_A["<b>Level 3: Global Search</b><br/>--search-highlight-bg"]
L3_B["<b>Level 3: Split View</b><br/>--split-preview-bg"]
L3_C["<b>Level 3: Markdown</b><br/>--md-surface"]
end
L4["<b>User Custom Theme</b><br/>style id='user-custom-theme'<br/>Dynamic User Overrides"]
L1 --> L2
L2 --> L3_A
L2 --> L3_B
L2 --> L3_C
L3_A --> L4
L3_B --> L4
L3_C --> L4
style L1 fill:#f9f9f9,stroke:#333,stroke-width:2px
style L2 fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
style L4 fill:#fff3e0,stroke:#ff9800,stroke-width:2px,stroke-dasharray: 5 5
התרשים ממחיש את שרשרת ההורשה: מתחילים ב‑Primitives, עוברים לטוקנים סמנטיים לפי Theme, ממשיכים לטוקני רכיב ורק לבסוף ל‑Overrides דינמיים עבור Theme מותאם אישית.
טבלת טוקנים עיקריים
הטבלה מציגה את הטוקנים שחובה למלא עבור כל Theme, השכבה האחראית והקובץ שבו מעדכנים.
טוקן |
שכבה |
תיאור |
מיקום / Override חובה |
|---|---|---|---|
|
Level 1 |
צבעי מותג, משמשים גם לגרדיאנטים ו‑focus |
|
|
Level 2 |
רקעים לגוף, למודלים ולכרטיסים |
|
|
Level 2 |
משפחת צבעי טקסט לכל הרכיבים |
|
|
Level 2 |
כרטיסים, מודלים, dropdowns |
|
|
Level 1 |
בסיס ל‑Glassmorphism navbar, badges, מודלים |
|
|
Level 1 |
רוחב פס גלילה גלובלי לפי מכשיר (מובייל שליש, טאבלט/דסקטופ חצי) |
|
|
Level 2 |
כל כפתור ראשי, כולל מצבי hover (–btn-primary-hover-*) |
|
|
Level 1 |
שימשו לטיפול Banner Login, Inline Alerts, Sticky Notes |
|
|
Level 1 + Level 2 |
משטח כהה גם בתמות בהירות, לעמודים שקוראים אותו (בונה הערכות, גלריית הערכות, אינדקס התיעוד לאדמין), ורקע התצוגה החיה במצבי קוד ו‑HTML. הנייר של מסמך Markdown אינו הוא — ראו |
|
|
Level 3 |
הנייר של מסמך Markdown: הרקע והטקסט של |
|
|
Level 3 |
רכיב Split View + Live Preview. |
|
|
Level 3 |
UI החיפוש הגלובלי |
|
|
Level 3 |
רכיבי Bookmarks ו‑Glass Badges |
|
|
Level 3 |
טקסט משני בתצוגת Markdown |
|
|
Level 2 |
CodeMirror, כרטיסי קוד, Split View |
|
|
Level 2 |
צבע הקישורים במסמך Markdown ( |
|
|
Level 3 |
שמות הקבצים בכרטיס אוסף ובשולחן העבודה. ברשימה הלבנה, ובכוונה ללא ערך ברירת מחדל — כך ערכה בודדת דורסת אותו לעצמה בלי להשפיע על אחרות |
|
|
Level 3 |
הטקסט בהצעות ההשלמה של החיפוש הגלובלי. אותו מבנה בדיוק: ברשימה הלבנה, ובכוונה ללא ערך ברירת מחדל |
|
|
Level 3 |
ההתאמות של החיפוש בתוך קובץ בתצוגה המרונדרת של דפדפן הריפו (חיפוש בתוך הקובץ בתצוגה המרונדרת): צהוב וטקסט שחור כמו שאר הדגשות החיפוש בדפדפן הריפו, והפעילה כתומה. אותו ערך בכל הערכות, ולכן לא ברשימה הלבנה. הטבעת של הפעילה בשני צבעים בכוונה — שחורה ( |
|
|
Level 3 |
הצ’קליסט ”צעדים ראשונים“ בדשבורד (הצ’קליסט ”צעדים ראשונים“ בדשבורד): הוי, מילוי פס ההתקדמות והפס של הצעד הבא, המסלול של הפס, והרקע והמסגרת של כל צעד. נגזרים מ- |
|
|
Level 3 |
הרקע והגבול של בלוקי הקוד בתצוגת ה-Markdown של דפדפן הריפו. אותו מבנה: ברשימה הלבנה, ובכוונה ללא ערך ברירת מחדל |
|
|
Level 3 |
הטקסט של כפתור primary בכל מקום שבו ערכה מיובאת או משותפת צובעת אותו ב- |
|
|
Level 3 |
רכיבים שצבועים בצבעים קבועים לרקע כהה, ולכן לא נראים בערכה מיובאת בהירה: השדות בעמודי העריכה וההעלאה ושדות הסינון בעמוד הקבצים, הבלוקים, התגים והבאדג« של הפוש בדשבורד, הגבול של שורת החיפוש בתצוגת ה-Markdown ובתצוגת הקוד, ”שולחן עבודה“ בעמוד הקבצים, הכפתורים שמעל העורך, וסרגל החיפוש ומלבני הפרטים בתצוגת הקוד. אותו מבנה: ברשימה הלבנה, ובכוונה ללא ערך ברירת מחדל |
|
|
Level 3 |
צבעי המסמך בתצוגת ה-Markdown ובתצוגה החיה: כותרות H1–H2, כותרות H3–H6, הדגשה, קוד בשורה ופס הציטוט. לתצוגה המרונדרת של VS Code אין מפתח לכותרות ולהדגשה, ולכן ערכה בודדת מצהירה עליהם בבלוק |
|
|
Level 3 |
שם הקובץ, בכרטיס הקובץ בעמוד הקבצים ובראש תצוגת הקוד, ה-Markdown וה-HTML; התיאור, בכרטיס ובתצוגת הקוד; והשורות, הגודל והתאריכים בכרטיס. נקראים על |
|
רשימת הטוקנים המורחבת זמינה בקובץ webapp/FEATURE_SUGGESTIONS/css_refactor_plan.md ובטבלת הפלטות webapp/FEATURE_SUGGESTIONS/webapp_theme_palettes.md.
מפת ערכות הנושא (Theme Reference)
ערכה |
|
בסיס צבע |
הערות / טוקנים ייחודיים |
|---|---|---|---|
Dark |
|
אפור/סגול כהה |
משמש כברירת מחדל עם |
Dim |
|
רך יותר מדארק |
אותם טוקנים כמו Dark עם ניגודיות נמוכה יותר |
Nebula |
|
כחול‑סגול קוסמי |
|
Classic |
|
גרדיאנט סגול‑כחול |
|
Ocean |
|
כחול עמוק |
כל טוקן רקע/טקסט מוגדר ידנית; Split View מקבל |
Rose Pine Dawn |
|
ורוד‑שמנת |
ערכת אור מלאה עם |
High Contrast |
|
שחור/לבן/צהוב |
אין לה בלוק ב‑ |
ערכת Classic מציגה כפתור ראשי לבן, רקע גרדיאנטי, ומסמך Markdown — בתצוגת המסמך ובתצוגה החיה — על נייר לבן (--md-paper-bg).
ערכת High Contrast משתמשת רק בשחור, לבן וצהוב לפי WCAG 2.1 AA. כל שינוי חייב לשמור על יחס ניגודיות 4.5:1 לטקסט רגיל.
הערה
High Contrast מתנהגת אחרת מכל שאר הערכות, וזה משפיע ישירות על כל רכיב חדש.
base.html אינו מגדיר לה טוקנים. static/css/high-contrast.css (נטען גלובלית) מגדיר בבלוק :root[data-theme="high-contrast"] רק את הטוקנים --primary, --secondary, --glass, --glass-border, --md-surface, --md-text ו‑--link-color — ואת השאר משלימים ברמת הרכיב: bookmarks.css, collections.css, global_search.css, lang-badge.css, markdown-enhanced.css ו‑split-view.css.
המשמעות המעשית: --card-bg, --card-border ו‑--text-primary אינם מוגדרים בערכה הזו. רכיב שנשען עליהם מקבל את ה‑fallback שלו, ובעמוד שאינו טוען אחד מששת הקבצים לעיל התוצאה עלולה להיות בלתי קריאה — למשל כרטיס לבן עם גבול לבן. רכיב חדש שאמור לעבוד ב‑High Contrast צריך בלוק :root[data-theme="high-contrast"] משלו, בדיוק כפי שששת הקבצים האלה עושים.
Markdown Viewer ו‑Split View
הנייר והדיו של מסמך Markdown — עותק אחד, לתצוגת המסמך ולתצוגה החיה. הצבעים של המסמך יושבים ב‑
webapp/static/css/md-content-colors.css: הנייר (--md-paper-bgו‑--md-paper-textעל:root), הטוקנים של כל ערכה על#md-content(קוד בשורה, בלוק קוד וצבעי התחביר, ציטוט, טבלה, סימון, Mermaid), והכללים שצובעים בהם את מה ש‑markdown-it מייצר, כולל הקישורים.md_preview.htmlטוען אותו בראשextra_css, ו‑_live_preview_styles.htmlטוען אותו בעמודי העריכה וההעלאה ובעורך הציבורי (העורך הציבורי (/markdown-editor)). במצב Markdown,setMarkdownContextב‑live-preview.jsנותן ל‑canvas אתid="md-content"— ולכן אותם כללים חלים עליו — ולמכלdata-mode="markdown", שבוsplit-view.cssצובע את כל אזור התצוגה בנייר. הפריסה של אותם אלמנטים משותפת באותה דרך, ב‑md-content-layout.css(בבולט על הפריסה, בהמשך). ב‑md_preview.htmlנשאר מה שרק תצוגת המסמך בונה או מציגה, וההערה בראשmd-content-layout.cssמפרטת מה. למה עד אוקטובר 2026 התצוגה החיה הייתה כהה בכל ערכה: PR 2015 הציב על המכלdata-theme="dark", וזה הכניס לתצוגה את כללי הטקסט של הערכות הכהות ב‑dark-mode.cssעם צבעי הטקסט של העמוד — ב‑Classic וב‑Ocean לבן — ו‑PR 2087 פתר את הלבן‑על‑לבן ברקע כהה קבוע (--md-surface). התווית הוסרה, והצבעים של המסמך משותפים: בלי זה, על נייר לבן הדיו של התצוגה החיה לא היה קריא (המדידה ב‑What’s New, 2026-10-31).tests/test_live_preview_paper_browser.pyמשווה בדפדפן את התצוגה החיה לתצוגת המסמך בכל ערכה, כולל ערכה מיובאת בהירה.ערכת מסמך. כרטיס ”תצוגת Markdown“ יכול לקבל ערכה מותאמת או ציבורית משלו, בזמן שהממשק בערכה אחרת (ערכת מסמך: ערכה שחלה רק על תצוגת ה-Markdown). בלוק משתנים של ערכה מותאמת שמוצהר על
:rootונגזר ממשתנים אחרים — כמו הנייר ב‑md-content-colors.css— חל גם על השורש של ערכת המסמך (MD_DOC_THEME_ROOT_SELECTOR), אחרת הכרטיס יורש אותו כצבע הסופי של ערכת הממשק. בלוק כזה שנוסף בעתיד צריך את אותו בורר;tests/test_md_doc_theme_browser.pyמשווה את הכרטיס לעמוד שבו ערכת המסמך היא ערכת הממשק, ונכשל אם משהו נשאר מערכת הממשק.--md-surfaceו‑--md-textנשארים כהים גם בערכות בהירות, ואסור לרוקן אותם ב‑:root: בונה הערכות, גלריית הערכות ואינדקס התיעוד לאדמין קוראים אותם, והתצוגה החיה צובעת בהם את הרקע במצבי קוד ו‑HTML (--split-preview-bg).כפתור ”רקע לבן“ ב‑
md_preview.htmlפשוט מסיר מחלקותbg-sepia/light/medium/dark. השתמשו בטוקנים כשהדבר מתאפשר, אך שמרו על Presets לפי COLORS בסקריפט – אלו חריגים שהוגדרו בכוונה.Live Preview (split-view.css) משתמש ב‑
--split-preview-*למסגרת, לשורות הסטטוס ולמצבי קוד ו‑HTML; במצב Markdown הוא על הנייר של המסמך (ראו למעלה). בורר הרקע (bg-sepiaודומיו) קיים רק בתצוגת המסמך, ולכן מי שבחר בו רואה תצוגה חיה בנייר של הערכה. הוספת preset חדש, או הבאת הבורר לתצוגה החיה, מחייבת: 1. הוספת המחלקה בקובץ התבנית. 2. יצירת טוקן חדש ברמת Level 3 (--split-sepia-bg) אם נדרש. 3. בדיקות ניגודיות ב‑High Contrast.הפריסה של מסמך Markdown — עותק אחד, לתצוגת המסמך ולתצוגה החיה. ריווח, כותרות, רשימות, ציטוט, טבלאות, תמונות, קוד בשורה ובלוק הקוד עם פס הכותרת שלו יושבים ב‑
webapp/static/css/md-content-layout.css, שנטען באותם שני מקומות כמוmd-content-colors.cssועובד באותה דרך: הכללים כתובים על#md-content, וה‑canvas של התצוגה החיה מקבל את המזהה הזה במצב Markdown. בורר המזהה הוא גם מה שגובר על כלל האיפוס*שבבלוק ה‑<style>שלbase.html, שמוחק את ה‑margin וה‑padding — בלי זה ציטוט נראה כמו פסקה רגילה, ורשימה בלי תבליטים. ובאותה ספציפיות הכללים האלה גוברים גם על כללים של קבצים אחרים שחלים על אותם אלמנטים, למשל של האדמוניציות ב‑markdown-enhanced.css: הריווח מעל הפסקה הראשונה באדמוניציה הוא של#md-content pולא של.admonition-content > *:first-child, בשתי התצוגות. למה עד אוקטובר 2026 התצוגה החיה נראתה אחרת מהמסמך: הכללים ישבו ב‑<style>שלmd_preview.html, שאינו נטען בעמודי העריכה, ול‑split-view.cssהיה בלוק תוכן משלו, עטוף ב‑:where(). שני העותקים נסחפו: בתצוגה החיה קוד בשורה קיבלword-break: break-word, ובטבלה עמודה עם קוד בשורה נשברה כל אות או שתיים, בזמן שבתצוגת המסמך אותו קוד נשאר בשורה אחת והטבלה נגללת לרוחב; ובלוק קוד נראה שם כמו בדפדפן הריפו. הבלוק נמחק מ‑split-view.css, יחד עם הטוקנים--split-preview-code-bgו‑--split-preview-code-textשרק הוא קרא.tests/test_live_preview_paper_browser.pyמשווה בדפדפן, בכל ערכה, את הצבעים ואת הפריסה של האלמנטים שברשימתSELECTORSשבו בין התצוגה החיה לתצוגת המסמך, ובודק שקוד בשורה בתוך תא בטבלה נשאר בשורה אחת.tests/test_live_preview_blockquote_browser.pyמודד את הפריסה בשני העמודים, בכל ערכה שברשימתTHEMESשבו.בלוק קוד — אותו בלוק בשתי התצוגות, והתלויות שעמודי העריכה מספקים לו.
webapp/static/js/md-code-blocks.js(window.MdCodeBlocks.enhance) עוטף כלpreב‑div.code-blockומוסיף מעליו פס כותרת (.md-code-header) עם שם השפה (.md-code-lang) וכפתור העתקה (.md-copy-btn), שהאייקונים שלו SVG בתוך הכפתור.md_preview.htmlקורא לו אחרי רינדור ה‑Mermaid, והתצוגה החיה קוראת לו מ‑MarkdownLiveRenderer.enhanceב‑live-preview.js, כשהאפשרותdocumentCodeBlocksדלוקה, באותו סדר. רקLivePreviewControllerמדליק אותה:MarkdownLiveRenderer.enhanceמשמש גם את התצוגה המרונדרת בדפדפן הריפו ואת כרטיסי החיפוש בתיעוד, ושם נשאר הכפתור הקטן בפינת ה‑pre(.code-copy-btnעםbi-clipboard), שמעוצב ב‑markdown-preview.css. כשהאפשרות דלוקה,highlightBlocksרק מדגיש ואינו בונה את הכפתור הקטן. עד אוקטובר 2026 הבלוק נבנה בתוךmd_preview.html(addCopyButtons), והתצוגה החיה הציגה את הכפתור הקטן, כמו בדפדפן הריפו. את התלויות העמוד צריך לספק, ובעמוד העריכה, בעמוד ההעלאה ובעורך הציבורי הן מגיעות משני partials,_live_preview_styles.htmlו‑_live_preview_scripts.html, ולא מרשימה שכל עמוד מחזיק לעצמו: שתי הרשימות שהיו שם חסרו את אותם דברים, בלי שום שגיאה — הקוד נראה כמו טקסט רגיל בגופן מונו, בלי צבעים, והכפתור יצא ריבוע ריק מתחת לקוד. התלויות:utils/safe-highlight.js(highlightBlocksמדגיש רק דרךwindow.SafeHighlight),md-code-blocks.jsלפניlive-preview.js(בלעדיו התצוגה החיה כותבת אזהרה לקונסול, והבלוק נשאר בלי מסגרת ובלי כפתור), ו‑md-content-colors.cssעםmd-content-layout.css. האייקונים של Bootstrap כבר לא נטענים בעמודים האלה: הם שימשו בתצוגה החיה רק את הכפתור הקטן.tests/sticky-notes-target.test.jsבודק שכל עמוד שטוען אתlive-preview.jsמספק את ההדגשה (אחרי פתרון ה‑{% include %}); שעמוד עם#livePreviewRootטוען אתmd-code-blocks.jsלפניlive-preview.js, ועמוד אחר שטוען אתlive-preview.jsטוען את האייקונים; שכל עמוד עם#livePreviewRootכולל את שני ה‑partials; ושתצוגת המסמך בונה את הבלוק מ‑md-code-blocks.jsולא מעותק בתבנית. צבעי התחביר הם של המסמך:#md-content .hljs-*ב‑md-content-colors.cssקוראים את--hljs-*של כל ערכה, וגוברים בספציפיות על הצבעים של הבאנדל (md_preview.bundle.css, הערכה github-dark-dimmed של highlight.js); ערכה מיובאת מקבלת את צבעי התחביר שלה מה‑syntax_cssשלה, כמו בתצוגת המסמך — וגם ערכה ציבורית שפורסמה ממנה, כי הפרסום שומר את כל הקבוצות של ה‑syntax_css(הדגשת התחביר בפרסום). גם הרקע והמסגרת של הבלוק, של פס הכותרת ושל הכפתור הם הטוקנים של המסמך (--md-code-*). הבלוק כולו כתוב משמאל לימין (direction: ltrעל#md-content .code-block), ולכן הכפתור בצד ימין של הפס גם בבלוק עברי, שרק ה‑preשלו מקבלrtl-code. שורה ארוכה נגללת לרוחב בתוך הבלוק, מתחת לפס, והפס והכפתור לא זזים איתה.tests/test_live_preview_blockquote_browser.pyמודד את הבלוק, את פס הכותרת ואת הכפתור בשני העמודים, בכל ערכה שברשימתTHEMESשבו.הקישורים במסמך, ובפרט ב‑High Contrast. הכללים של
#md-content aב‑md-content-colors.css— שחלים גם בתצוגה החיה — קוראים את--link-color(ראו בטבלת הטוקנים), וקו ה‑::afterשמתרחב בריחוף צבוע ב‑currentColor, כלומר בצבע הקישור. ב‑High Contrast זה לא מספיק:[data-theme="high-contrast"] a,a:hoverו‑a:focusב‑high-contrast.cssהם!important, בצבע שנבחר לרקע השחור של הערכה, והדף של המסמך נשאר לבן גם בה — כך שהכללים הרגילים הפסידו והקישור כמעט לא נראה. לכן ל‑[data-theme="high-contrast"] #md-content aיש כלל!importantמשלו, עם קו תחתון. בין שתי הצהרות!importantמכריעה הספציפיות, ובורר המזהה גובר על שלושתם, גם בריחוף ובפוקוס — אותו מנגנון של הקישורים בפתקים (ראו בהמשך). הכלל יושב ב‑md-content-colors.cssולא ב‑high-contrast.css:tests/test_sticky_notes_link_color.pyמתייחס לכל כללaבקובץ ההוא ככלל שחל על כל העמוד, גם על הפתקים, שאינם בתוך#md-content.tests/test_md_preview_link_color.pyגוזר את היריבים מקבצי הערכות.המסגרת של ה‑Split View, פס הגלילה של התצוגה והצ’קליסט — משותפים לכל עמודי העורך. (1) הריפוד של הנייר בתצוגה,
--split-preview-pad, יושב בתוך הגולל (.split-preview-canvas) ובשורות שמתחתיו, ולא על המכל, ולכן פס הגלילה צמוד לקצה הנייר;file-editor.cssמקטין את הטוקן בנייד, ואינו מגדיר ריפוד משלו. (2) ל‑.split-viewישuser-select: none, ולעורך ולתצוגהuser-select: text: כשנוגעים באזור בלי טקסט, Chrome מציב את הסמן בטקסט הקרוב לנקודה, ונגיעה במסגרת שמימין לעורך הכניסה את הסמן לעורך — ובנייד פתחה מקלדת (tests/test_edit_page_frame_browser.py). (3) האלמנט הראשון במסמך בליmarginעליון (#md-content > :first-childב‑md-content-layout.css), בשתי התצוגות. (4) הצ’קבוקס של פריט משימה מעוצב ב‑md-content-layout.css(#md-content .task-list-item-checkbox), בשתי התצוגות; עד אוקטובר 2026 העיצוב ישב ב‑md_preview.html, והתצוגה החיה גם סימנה כל צ’קבוקסdisabled, ולכן הוא יצא אפור ולא לחיץ. בתצוגה החיה לחיצה עליו משנה את[ ]/[x]בשורה שלו בעורך (handleTaskToggleב‑live-preview.js): כל פריט משימה מסומן בשורת המקור שלו (data-source-line, מ‑md-source-lines-plugin.js— ראו את הבולט על הגלילה המסונכרנת, למטה), דרך מפת השורות שלMdAnchors.extractExplicitAnchors— שורה שכולה עוגנים מוסרת לפני הפענוח, ובלי המפה הלחיצה הייתה מסמנת את השורה שמעל. לפני הכתיבה הבקר בודק שהטקסט בעורך הוא זה שהתצוגה רונדרה ממנו, ושהשורה עדיין משימה; אחרת הוא לא כותב, ומרנדר מחדש. בדפדפן הריפו ובכרטיסי החיפוש בתיעוד, שאין בהם טקסט לשנות, הצ’קבוקס נשארdisabled(האפשרותinteractiveTasksשלMarkdownLiveRenderer.enhance). בתצוגת המסמך הסימון נשמר בדפדפן ולא בקובץ, כמו קודם.קו הפרדה וכותרות — בשתי התצוגות.
---הוא קו של פיקסל אחד (#md-content hrב‑md-content-layout.css: גובה,border: 0ומרווח), בצבע הדיו של הנייר בשקיפות (color-mixשל--md-paper-textב‑md-content-colors.css), כך שהוא עוקב אחרי כל ערכה בלי צבע משלו. עד אוקטובר 2026 לא היה לו כלל, והדפדפן צייר קו ”בולט“ אפור, שעל נייר כהה נראה כמו פס לבן. ול‑h1ול‑h2אין יותר קו תחתון: הוא היה בסגנון GitHub, בצבע אפור‑בהיר קבוע שלא עקב אחרי הערכה.tests/test_live_preview_paper_browser.pyמשווה את הקו בין שתי התצוגות, ובודק אותו בתצוגת המסמך בכל ערכה.הלשוניות ”עורך“ / ”תצוגה חיה“ בטלפון — סימון שלא בוחר צבע. עד 767px העורך והתצוגה מוצגים אחד בכל פעם, עם לשוניות (
.split-tabsב‑split-view.css), ורק כשהתצוגה דלוקה (.split-view.is-active): כשהיא כבויה יש רק עורך. הלשונית הנבחרת בצבע הטקסט של שורת הכלים (inherit), שכל ערכה כבר קבעה כקריא על הרקע שלה, מודגשת, עם קו תחתון באותו צבע — ולכן הקו נראה בכל מקום שבו הטקסט נקרא — ועם רקע של אותו צבע בעוצמה נמוכה (color-mixעםcurrentColor). הלא נבחרת באותו צבע, בלי קו, בלי רקע ובלי דהייה. ככה זה עובד גם בערכה מיובאת, בלי טוקן חדש. ניגודיות גבוהה קובעת--split-tabs-selected-bg/--split-tabs-selected-color(לבן, ושחור עליו), וכלל עם!importantגובר בה על הצבעים ש‑high-contrast.cssנותן לכלbutton— עד נובמבר 2026 שתי הלשוניות נראו שם אותו דבר. למה כך (נמדד ב‑2026-11-04, בדגימת פיקסלים): עד אז הנבחרת קיבלה את צבע הטקסט של התצוגה החיה, כמעט לבן, ובערכה בהירה כמעט נעלמה (ניגודיות 1.42 ב‑Rose Pine Dawn). קו בצבע--primaryנבלע ב‑Classic וב‑Forest (ניגודיות 1.0 מול הרקע של הלשונית), ודהייה של הלא נבחרת הורידה אותה מתחת ל‑4.5 בארבע ערכות שהיו מעליו. הערכים וההסבר בהערה שמעל הכלל ב‑split-view.css;test_on_a_phone_the_tabs_come_with_the_preview_and_the_selected_one_stands_out_in_every_themeב‑tests/test_edit_page_frame_browser.pyמודד את הקו ואת הניגודיות בכל ערכה.הגובה של ה‑Split View כשהתצוגה דלוקה — גובה, לא תקרה.
.split-view.is-active .split-panelsב‑split-view.cssמקבלheight(מ‑768px ומעלה), וזה הכלל היחיד שקובע את גובה הפאנלים. עד אוקטובר 2026 זו הייתה תקרה (max-height), ולכן הגובה נקבע לפי אורך התוכן: מסמך ריק כיווץ את העורך ואת התצוגה. ההערה הגדולה מעל הכללים ב‑split-view.cssמפרטת את כל שרשרת הגובה, ו‑tests/split-view-editor-height.test.jsאוכף אותה.מתחת לתצוגה — רק הודעת שגיאה. בכל עמודי העורך שורת המידע (
.split-preview-meta: שפה, גודל, זמן) מוסתרת, והסטטוס (.split-preview-status) מוצג רק במצבerror. שאר הסטטוסים נראים ממילא במקום אחר: ”טוען תצוגה חיה…“ בשכבה מעל התצוגה (.is-loading), ו“אין תוכן להצגה.“ בתוך התצוגה. השגיאה כן מוצגת, כי כשהרינדור נכשל התצוגה ממשיכה להציג את הרינדור הקודם, ובלי ההודעה הוא היה נראה תקין. הכלל ב‑split-view.css; עד נובמבר 2026 הוא ישב רק בעורך הציבורי, ובעמודי העריכה וההעלאה הוצגו מתחת לתצוגהmarkdown • 8.6 KB • 207msו“התצוגה מעודכנת.“.updateMetaב‑live-preview.jsממשיך לעדכן את שורת המידע, והטוקן--split-preview-metaנשאר, כך שאפשר להחזיר אותה בשינוי של הכלל לבדו.test_under_the_preview_only_an_error_is_shownב‑tests/test_edit_page_frame_browser.pyבודק את שני המצבים, וטסט הנייר (tests/test_live_preview_paper_browser.py) מודד את הניגודיות של הודעת השגיאה בכל ערכה.בלי קו גרירה בין הפאנלים. העורך והתצוגה בחצי‑חצי (
flex: 1של.split-panel)..split-resizerהוסר מכל עמודי העורך, יחד עם הטוקנים--split-resizer-*ו‑--split-editor-ratio: במגע הגרירה הסתיימה ב‑pointercancelולא ב‑pointerup, מאזין התזוזה נשאר רשום, וכל גלילה אחר כך שינתה את רוחב הפאנלים. ומצב ”דלוק“ של כפתור Live Preview נצבע לפי.split-view.is-active .split-toggleולא לפיaria-pressed, כי בעורך הציבורי לכפתור איןaria-pressed(העורך הציבורי (/markdown-editor)).גלילה מסונכרנת בין העורך לתצוגה — לפי שורות, לא לפי אחוזים. בכל עמודי העורך, כשהתצוגה החיה דלוקה, גלילה בעורך מביאה את התצוגה לאותו מקום בטקסט, וגלילה בתצוגה מביאה את העורך. המנוע הוא
webapp/static/js/live-preview-scroll-sync.js, ו‑setupScrollSyncב‑live-preview.jsמחבר אותו; ההערה בראש המנוע מפרטת את כל ההחלטות.למה לא אחוזים. ב‑
/compare/pasteובהשוואת הקומיטים כל צד זז באותו אחוז מהגובה שלו, וזה עובד כי שני הצדדים בנויים מאותן שורות. ב‑Markdown לא: תמונה היא שורה אחת בעורך ושטח גדול בתצוגה, ולכן אחוז זהה מראה בכל צד מקום אחר. כאן כל בלוק בתצוגה מסומן בשורות המקור שלו (data-source-line/data-source-line-end) ב‑md-source-lines-plugin.js, אותו תוסף שתצוגת המסמך מתקינה (עד נובמבר 2026 הוא היה כתוב בתוךmd_preview.html, והתצוגה החיה סימנה רק פריטי משימה). מהסימונים נבנות נקודות התאמה (buildPoints), ובעורך CodeMirror יודע את הגובה של כל שורה גם כשהיא נשברת לכמה שורות מסך. תרשים Mermaid שומר את הסימון של בלוק הקוד שהוא מחליף (renderMermaid). בתצוגה החיה מסומנים גם הקונטיינרים (::: note,::: details) והאלרטים (!!! note), כי הכותרת שלהם תופסת גובה (extraBlockTypes, וההסבר בראש התוסף);::: detailsסגור נמדד בגובה ה‑summaryשלו, והבלוקים שבתוכו לא נכנסים. בתצוגת המסמך הם לא מסומנים, כדי לא לשנות את מה ש“העתק כמארקדאון“ והפתקים נצמדים אליו.נקודת הקריאה זזה לפי המיקום במסמך (
readingY): בראש החלון כשהגלילה בהתחלה, בתחתית בסוף, ובאמצע לפי היחס. כך ההתחלה והסוף של שני הצדדים מתיישרים תמיד. ובכל שורה יש נקודת התאמה אחת, ולכן גם בין שני בלוקים צמודים בלי שורה ריקה (כותרת ומיד אחריה כותרת) התצוגה לא קופצת.מי מוביל: הצד שהמשתמש עשה בו משהו אחרון — גלגלת, מגע, לחיצה, מקלדת או פוקוס (
INTENT_EVENTS). רק גלילה שלו מזיזה את הצד השני, והגלילה שהמנוע עושה לא חוזרת אליו כהד. אחרי כל רינדור של התצוגה הצדדים מתיישרים מחדש לפי הצד המוביל, ולכן כשכותבים, התצוגה מראה את מה שכותבים. ובזמן הרינדור עצמו — מהרגע שהתוכן מוחלף ועד שהתרשימים במקומם — אין סנכרון: הצד השני מחכה, ואז זז פעם אחת (contentClearedלפני ההחלפה ב‑renderClientMarkdown). וכשמקלידים בזמן שתרשים מצויר, רינדור חדש מתחיל לפני שהקודם נגמר; רק האחרון שומר את התוצאות שלו — הסנכרון ומיפוי הצ’קבוקסים — כי כל מסלול שמחליף את התוכן בתצוגה מקדם את מספר הרינדור (invalidateRenderedContentב‑live-preview.js).מתי אין סנכרון: בעורך הפשוט (textarea), בטלפון במעבר בין הלשוניות (שם מוצג פאנל אחד בכל פעם) — שתיהן החלטות של המשתמש, נובמבר 2026 — ובתצוגה בלי סימוני שורות: HTML, ורינדור מהשרת כשהרינדור בדפדפן נכשל. שם אין סנכרון בכלל, ולא גלילה לפי אחוזים במקומו.
הבדיקות.
tests/live-preview-scroll-sync.test.jsבודק את החשבון, ו‑tests/md-source-lines-plugin.test.jsאת הסימון. בדפדפן:tests/test_markdown_editor_browser.py(כותרת שמוצבת בנקודת הקריאה של צד אחד נמצאת בנקודת הקריאה של השני, בשני הכיוונים; הכותרת של כל קונטיינר; ההתחלה והסוף; כתיבה בסוף המסמך; שהצד שגוללים בו לא נמשך אחורה; שגלילה בזמן רינדור מחכה לסופו; ושרינדור שרינדור חדש הקדים אותו לא שומר את התוצאות שלו) ו‑tests/test_edit_page_frame_browser.py(עורך משמאל לימין עם מספרי שורות, ושבעורך הפשוט אין סנכרון). המדידה המשותפת להם ב‑tests/_scroll_sync_harness.py, וכל בדיקת יישור מוודאת גם שגלילה לפי אחוזים הייתה נכשלת על המסמך שלה.
צבעי הקוד בערכה מותאמת או משותפת — גם בייצוא ל‑HTML מעוצב. בבלוק של ערכה מותאמת או משותפת ב‑
md-content-colors.css,--hljs-*נגזרים ממשתני הערכה (מילת מפתח ב‑--primary, מחרוזת ב‑--success, הערה ב‑--text-mutedוכו«), וכללי#md-content .hljs-*מחברים אליהם את מחלקות highlight.js. הייצוא ל‑HTML מעוצב קורא את שני החלקים האלה מהקובץ, בין הסימוניםexport-hljs-paletteו‑export-hljs-rules, לכל ערכה שאין לה צבעי highlight.js משלה (export_hljs_fallback_cssב‑webapp/markdown_editor.py), כך שהקובץ נצבע כמו התצוגה בלי עותק שני של הפלטה. מי שמזיז את השורות או את הסימונים שובר את הייצוא, ו‑tests/test_styled_export_skeleton.pyנכשל.theme_preview.htmlו‑Reader modes ב‑md_preview.htmlנשארים Hardcoded לצורכי תצוגת פלטות – אין להמיר אותם ל‑var() כדי לשמור על נאמנות ל‑brand colors.
הנחיות למפתחים (Best Practices)
❌ אין לציין HEX בקבצי רכיבים (למעט חריגים מתועדים). ✅ תמיד להשתמש ב‑
var(--token-name)ולוודא שהטוקן עלה לטבלת הרפרנס.כשצריך פס גלילה צר ברכיב מקומי: - הגדירו
::-webkit-scrollbarעםwidth/heightעל בסיסvar(--scrollbar-width). - הוסיפוscrollbar-width: thinכדי לכסות גם Firefox.כלל אצבע: - צריך צבע שחוזר בכמה קומפוננטות → טוקן סמנטי (Level 2). - צריך גוון שמזוהה עם רכיב מסוים (צלחמת חיפוש, טאב מסוים) → טוקן רכיב (Level 3) + Overrides.
Inline styles ב‑HTML/JS: צרו מחלקה ב‑CSS שמפנה ל‑
var(). אם חייבים Inject דינמי (למשל Sticky Notes) – חשבו צבעים דרך טוקנים קיימים (–text-on-primary, –danger-bg).color-mix() (אופציונלי): עדיף על שקיפות ידנית כאשר צריך לשלב צבעים קיימים.
[data-theme="..."]הוא הסלקטור היחיד לשינוי Theme. אין להשתמש שוב ב‑prefers-color-schemeמלבד בקוד Legacy שכבר קיים ב‑markdown-enhanced.css(TODO לעדכן).
חשוב
Whitelist חיוני לכל ערכה — אישית וציבורית כאחת
ALLOWED_VARIABLES_WHITELIST (ב-services/theme_parser_service.py) מסנן את הטוקנים בכל המסלולים: ייבוא ערכה אישית, יצירה ועדכון של ערכה קיימת, ופרסום ערכה ציבורית. טוקן שאינו ברשימה נזרק. אזהרה בלוג נרשמת רק כשהסינון עובר דרך validate_and_sanitize_theme_variables: ייבוא קובץ (import_theme ב-webapp/themes_api.py, בשני הפורמטים) והוספת ערכה מוכנה (apply_preset_to_user). בלולאות שבודקות מול הרשימה ישירות הטוקן נזרק בלי לוג: create_theme, update_theme ו-save_custom_theme ב-webapp/themes_api.py, ופרסום ועדכון של ערכה ציבורית (SharedThemeService._filter_and_validate_colors).
אם מוסיפים טוקן חדש שערכה אמורה להיות מסוגלת לקבוע — מספיק לעדכן את ה-whitelist: הרשימה ב-ערכות נושא מותאמות אישית – מדריך מקיף נמשכת ממנו בכל בנייה.
דוגמת קוד – לא תקין לעומת תקין
/* ❌ לא תקין – צבעים קשיחים */
.global-search-card {
background: #ffffff;
color: #1c1c1c;
box-shadow: 0 30px 60px rgba(7, 7, 31, 0.35);
}
/* ✅ תקין – מסתמך על טוקנים */
.global-search-card {
background: var(--card-bg);
color: var(--text-primary);
box-shadow: var(--search-card-shadow, 0 20px 40px rgba(0,0,0,0.25));
}
Component Tokens ו‑Theme Builder
הערה
המפרט הרשמי של Theme Builder מתועד ב‑Issue #2097 ובמדריכים שבתיקיית GUIDES/.
חלק ב« מוסיף תמיכה בריבוי ערכות (Multi-Theme) למשתמש מחובר.
מטרות ה‑Builder: - בונה ערכה ב‑
/settings/theme-builderעם Live Preview מבודד שמצרוךvar(--token)בלבד ולא משפיע על שאר ה‑UI עד לשמירה. - מעבר ממבנה ערכה אחת ל‑מערך ערכות:users.custom_themes(עד 10 ערכות למשתמש). - רק ערכה אחת יכולה להיות פעילה בכל רגע (is_active=True). - הזרקה אוטומטית של הערכה הפעילה דרך<style id="user-custom-theme">ב‑base.htmlכאשרdata-theme="custom". - תאימות לאחור: פונקצייתget_custom_themeבודקת קודםcustom_themes(מבנה חדש), ואז fallback ל‑custom_theme(מבנה ישן).API (Multi-Theme): -
GET /api/themes– רשימת הערכות של המשתמש ללאvariablesכבדים -POST /api/themes– יצירת ערכה חדשה (כולל מגבלת 10) -GET /api/themes/<id>– פרטי ערכה כוללvariablesלעריכה -PUT /api/themes/<id>– עדכון ערכה -POST /api/themes/<id>/activate– הפעלת ערכה (מכבה את השאר + מעדכןui_prefs.theme="custom") -POST /api/themes/deactivate– ביטול כל הערכות וחזרה ל‑Classic -DELETE /api/themes/<id>– מחיקת ערכה (אם הייתה פעילה: חוזרים ל‑Classic)UI: - Sidebar ”הערכות שלי“ עם רשימה, אינדיקציה לערכה פעילה/נבחרת, וכפתור ”ערכה חדשה“.
כאשר מוסיפים טוקן חדש: 1. הוסיפו ערך ברירת מחדל ל‑
:rootבתוך בלוק ה‑<style>שב‑webapp/templates/base.html. 2. הוסיפו Overrides בבלוקים של כל Theme שדורש התאמה. 3. אם הטוקן שייך לרכיב ספציפי, הגדירו אותו גם בקובץ הרכיב (למשלsplit-view.css) כדי לא לאבד הקשר.Theme Builder (או Override ידני) נעשה באמצעות
<style id="user-custom-theme">שמוזרק בסוף ה‑<head>. כך ניתן לאפשר Overrides בטוחים:<style id="user-custom-theme"> :root[data-theme="custom"] { --primary: #ff6f61; --bg-primary: #0f1117; --text-primary: #f5f5f5; --btn-primary-bg: rgba(255,255,255,0.92); } </style>
כאשר מבצעים Override לתמה קיימת (בידיים היום או דרך Theme Builder בעתיד), כתבו את הטוקנים בתוך
:root[data-theme="ocean"]באותו <style> כך שהערכים הדינמיים יגברו על ברירת המחדל.טוקנים חובה ל‑Theme מותאם אישית (גם בעתיד כשה‑Builder יהיה פעיל): –primary, –secondary, –bg-primary, –bg-secondary, –text-primary, –text-secondary, –btn-primary-bg, –btn-primary-color, –glass, –md-surface, –md-text.
בדיקות חובה לפני Merge
מעבר ידני על כל 8 הערכות דרך Theme Wizard + בדיקה מהירה של localStorage.
בדיקת Split View + Markdown Preview (כולל לחצן ”רקע לבן“, מצבי Reader).
בדיקת Live Preview / Sticky Notes / Login alert / RTL. הגלילה החלקה כבויה כברירת מחדל (ראו Smooth Scrolling (WebApp) — מדריך תמציתי לסוכני AI); לבדיקה נקודתית שלה מוסיפים
?smooth_debug=1לכתובת.בדיקת Collections, Bookmarks, אוספים משותפים וה‑Glass badges.
בדיקת נגישות ב‑High Contrast (יחס ניגודיות 4.5:1, focus outline, קישורים).
עוגנים לטסטי דפדפן: אלמנט שטסט צריך לזהות מקבל
data-testidשמתאר את המצב שרונדר (למשלagg-time-not-measured), לא את הניסוח. הטסט נתלה בו ולא במחרוזת UI בעברית — שינוי ניסוח לא מפיל טסט, רינדור של הענף הלא נכון כן.data-testidאינו hook ל‑CSS ואין לעצב לפיו. כשלאלמנט כבר יש חוזה סמנטי יציב (href,id,name) — משתמשים בו ולא מוסיפיםdata-testid. תקדים:webapp/templates/profiler_dashboard.html.בדיקת שאין HEX קשיחים בקבצים שנגעתם בהם (rg ”#[0-9a-fA-F]{3,6}“ webapp/static/css/<file>.css).
בדיקת WCAG ל‑Markdown Viewer (
bg-sepiaועוד) + ווידוא ש‑–md-surface לא הוחלף בטעות.מעבר בין Themes בזמן Live Preview כדי לוודא שאין FOUC (שימרו על setAttribute מוקדם).
שימושים נוספים וחריגים
אזהרה
⚠️ שים לב: Sticky Notes, Reader Modes (md_preview.html) והקובץ theme_preview.html נשארים Hardcoded בכוונה לצורכי Preset/Brand. אין להמיר אותם ל‑var() עד שתתועד חלופה רשמית, אחרת נשבור תצוגות קיימות.
Collections (webapp/static/css/collections.css) עדיין מכיל צבעים קשיחים ישנים – כל שינוי חייב להמיר ל‑var() לפי טבלת הטוקנים.
וו דריסה לערכה בודדת (Collections). שם הקובץ בכרטיס אוסף הוא
<a>, ולכןdark-mode.cssצובע אותו ב-var(--primary)דרך[data-theme="custom"] a— ספציפיות שגוברת על כלל המחלקה שב-collections.css. כרטיס האוסף נשאר לבן גם בערכה כהה, כך שערכה שה---primaryשלה בהיר מקבלת שם קובץ בלתי קריא. הפתרון אינו דריסה גורפת אלא וו בהצטרפות מרצון: שני כללים על.collection-card__linkועל.workspace-card__link— שני המסכים שמציגים שמות קבצים — קוראיםvar(--collections-link-override, <הערך שנצבע היום>)—--primaryבמצב רגיל,--primary-darkב-:hover. הטוקן חייב להישאר ללא ערך ברירת מחדל בשום מקום, אחרת ה-fallback לא נכנס לפעולה וכל ערכה מושפעת. זה בדיוק מה שקרה בניסיון הראשון: ברירת מחדל שנקבעה ב-:root[data-theme-type="custom"]שינתה את ה-:hoverגם בערכות שלא הצהירו, והורידה אותן מניגודיות 4.81 ל-1.00. ל-:hoverנדרש כלל נפרד כי[data-theme="custom"] a:hoverספציפי יותר. ראו דריסת טוקן שאין לו מקבילה ב-VS Code.וו דריסה לערכה בודדת (הצעות החיפוש הגלובלי). אותו שורש, ברכיב אחר: ההצעות מרונדרות ב-
global_search.jsכאלמנטי<a>, ורקע התיבה הוא--solid-surface-bgשנשאר לבן בכל ערכה — ולכן[data-theme="custom"] aצובע טקסט בצבע המותג של הערכה על רקע שאינו שלה. נמדד בדפדפן על הדף המרונדר: ערכה שה---primaryשלה לבן מקבלת ניגודיות 1.00, כלומר טקסט בלתי נראה עד שמעבירים עליו עכבר. הווו נבנה באותה צורה בדיוק —var(--search-suggestion-text-override, <הערך שנצבע היום>)— אבל כאן שלושה כללים ולא שניים, כי ל-:focus-visibleיש ערך משלו:.search-suggestion:focus-visibleהוא (0,2,0) ומנצח כבר היום את כלל ה-<a>שהוא (0,1,1), ולכן נצבע ב---suggestions-textולא ב---primary. סדר הכללים אינו שרירותי::hoverו-:focus-visibleשווים בספציפיות (0,3,0), ולכן כלל ה-:hoverנכתב אחרון — כך המצב המשולב נשאר--primary-dark, מה שנצבע שם היום.tests/services/test_theme_variables_search_suggestion_hook.pyנועל את הסדר הזה. ראו הצעות ההשלמה בחיפוש הגלובלי.וו דריסה לערכה בודדת (בלוקי הקוד בדפדפן הריפו). בערכה מיובאת,
markdown-preview.cssצובע את המעטפת של תצוגת ה-Markdown ב---bg-tertiary, את בלוק הקוד ב---code-bgואת הגבול שלו ב---border-color(דרך--md-preview-border, ראו בהמשך). כל אחד מהם נגזר ממפתח אחר של VS Code, וכשהשלושה יוצאים באותו צבע — כמו ב-Cobalt Next — הבלוק נבלע בטקסט שסביבו.--code-bgעצמו לא נדרס, כי הוא צובע גם רכיבי קוד אחרים; במקומו שני טוקנים חדשים,--repo-md-code-block-bg-overrideו---repo-md-code-block-border-override. הם נקראים בכלל הקיים[data-theme="custom"] .markdown-preview-content pre(ו-shared:), ולא בכלל חדש עם[data-theme-type="custom"]: זה הכלל שצובע היום את הבלוק בערכה מיובאת, (0,2,1) מול (0,1,1) של הכלל הכללי, ובורר זהה פירושו מפל זהה לערכה שאינה מצהירה. הגבול נקבע ב-border-colorולא ב-border, והעובי והסגנון נשארים של הכלל הכללי. ראו בלוקי הקוד בתצוגת ה-Markdown של דפדפן הריפו.וו דריסה לערכה בודדת (הטקסט בכפתורי primary). כפתור primary שהוא
<a>נצבע בערכה מיובאת דרך[data-theme="custom"] aשב-dark-mode.css, אותו שורש של ווי האוספים והחיפוש שמעל. בנוסף,.file-primary-actionב-view_file.htmlצובע ב---primaryאת ”ערוך“ ו“העתק קוד“, ובלוקprimary-btn-states-custom-typeב-base.htmlצובע בו, ב-!important, את מצבי הפוקוס, הלחיצה וההשבתה של כל כפתור primary, ואת כל כפתורי ה-primary בערכה משותפת.--btn-primary-text-overrideנקרא בכל אחד מהם, עם fallback לערך שהוא צבע עד היום. בכללים הקיימים הטוקן נקרא בלי לשנות את הבורר. לקישורים נוספו ב-dark-mode.cssשני כללים, רגיל ו-:hover, והבוררים שלהם הם הבוררים של כללי הקישורים עצמם עם:where(.btn-primary).:where()אינו מוסיף ספציפיות, והכללים כתובים מיד אחרי כללי הקישורים, ולכן הם חלים בדיוק במקום שבו כללי הקישורים צובעים היום, וכלל ספציפי יותר ממשיך לנצח. לא[data-theme-type="custom"], בכוונה: סנכרון הערכה בין טאבים (initThemeCrossTabSyncב-base.html) מחליף אתdata-themeלערכה מובנית שנבחרה בטאב אחר ומשאיר אתdata-theme-type, וכלל שנשען עליו היה ממשיך לחול בטאב הזה על הערכה המובנית.tests/services/test_theme_variables_btn_primary_text_hook.pyנועל את החוזה. ראו הטקסט בכפתורי primary.ווי דריסה לערכה בודדת (ערכה מיובאת בהירה). כל ערכה מיובאת מקבלת את העיצוב של הערכות הכהות, וזה נשאר כך בכוונה: אין סימון של ”ערכה מיובאת בהירה“, ואין כללים בהירים שחלים עליה. כמה רכיבים צבועים שם בצבעים קבועים לרקע כהה, ובערכה מיובאת בהירה הם לא נראים:
.form-fieldב-file-editor.css(השדות בעמודי העריכה וההעלאה), שדות הסינון ב-files.html(צבועים רק ב-styleשבתגית, ולכן הווו נקרא שם),.timeline-item,.timeline-group,.timeline-badge-*ו-.status-*בבלוק ה-<style>שלdashboard.html, הגבול של.md-search-capsuleב-md_preview.html,.workspace-btnב-base.html,.btn-switch-editorו-.btn-editor-clipב-codemirror-custom.css,.md-toolbar-triggerב-markdown-toolbar.css, ו-.editor-toolbar,.search-capsule,.icon-btn,.search-count,.divider,.fullscreen-btnו-.meta-itemב-view_file.html. כל אחד מהם קורא וו דריסה בכלל שצובע אותו היום, עם fallback לערך שנצבע בו, ובלי לשנות את הבורר — כך ערכה שאינה מצהירה, והתצוגה המקדימה של ערכה מובנית, זהות למה שהיו, והכללים של Rose Pine Dawn לאותם רכיבים ממשיכים לגבור בספציפיות. חריג אחד בצורה, לא בעיקרון: ל-.workspace-btnאין גבול (border: none), ווו שמקבל רק צבע אינו יכול להוסיף כזה בלי להגדיל את הכפתור בכל ערכה. לכן המסגרת שלו היאbox-shadowשקורא משתנה ביניים בלי fallback,--workspace-btn-ring: כשהווו אינו מוגדר, המשתנה לא תקף ו-box-shadowנופל ל-none(W3C css-variables-1, סעיף 3.1; ההערה מעל הכלל ב-base.html). משתנה הביניים אינו ברשימה הלבנה, בכוונה.tests/services/test_theme_variables_light_import_hooks.pyנועל את החוזה. ראו ערכה מיובאת בהירה: שדות טופס, הדשבורד, שורת החיפוש, הכפתורים שמעל העורך ותצוגת הקוד.ווי דריסה לערכה בודדת (צבעי המסמך). בתצוגת ה-Markdown ובתצוגה החיה ערכה מיובאת מבדילה בין חלקי המסמך רק ב-
--text-primaryוב---text-secondary, ולתצוגה המרונדרת של VS Code אין מפתח לכותרות ולהדגשה — גם שם הן ב-editor.foreground.--md-heading-color-override,--md-subheading-color-override,--md-strong-color-override,--md-inline-code-color-overrideו---md-blockquote-border-overrideנותנים לערכה בודדת לבחור צבעים בבלוקvariables. הקוד בשורה והציטוט קוראים את הווו בכלל שצובע אותם היום ב-md-content-colors.css. לכותרות ולהדגשה אין כלל כזה במסמך. הכותרות נצבעות בכלל ה-Typography שלdark-mode.css, שחל על כל כותרת באתר, ולכן נוסף להן כלל שחל רק בתוך#md-contentבערכה מיובאת או משותפת, (1,1,1) מול (0,1,1), עם fallback ל---text-primaryשל אותו כלל — כותרות הממשק לא זזות. ההדגשה יורשת היום את צבע הטקסט שסביבה, ולכן גם לה נוסף כלל באותם בוררים, שקורא את הווו עם fallback ל-inherit.tests/services/test_theme_variables_md_document_colors_hook.pyנועל את החוזה, ו-tests/test_md_document_colors_hook_browser.pyמודד את שתי התצוגות. ראו צבעי המסמך: כותרות, הדגשה, קוד בשורה וציטוט.ווי דריסה לערכה בודדת (שם הקובץ ותיאורו). בכרטיס הקובץ בעמוד הקבצים ובראש תצוגת הקוד, ה-Markdown וה-HTML, ערכה מיובאת צובעת את שם הקובץ בכלל הכותרות של
dark-mode.cssואת התיאור בכלל הפסקאות שם, והשורות, הגודל והתאריכים בכרטיס יורשים את צבע הטקסט.--file-name-color-override,--file-description-color-overrideו---file-card-meta-color-overrideנקראים בכללים חדשים ב-dark-mode.css, מיד אחרי כללי ה-Typography, על class שנוסף לאלמנט בכל תבנית:.file-name-text,.file-description-textו-.file-card-meta. בכרטיס האלמנטים זוהו עד היום רק ב-data-testid, שאינו hook ל-CSS, ולכן נוסף להם class. בתצוגת ה-HTML השם הוא חלק מכותרת עם תחילית, וה-class נמצא עלspanשעוטף רק אותו. השם עצמו הוא<bdi>בתוך האלמנט (הפילטרfile_name, כיוון של קוד בשורה ותאי טבלה), והצבע עובר אליו בירושה. הבורר (0,2,0) גובר על כללי ה-Typography (0,1,1), וה-fallback הוא הצבע שהם נותנים:--text-primaryלשם,--text-secondaryלתיאור, ו-inheritלמטא.tests/services/test_theme_variables_file_name_hook.pyנועל את החוזה, ו-tests/test_file_name_colors_hook_browser.pyמודד את ארבעת העמודים. ראו שם הקובץ ותיאורו: כרטיס הקובץ ותצוגות הקובץ.הקובץ המשותף של תצוגת ה-Markdown, וטוקני הרכיב שלו.
markdown-preview.cssנטען בדפדפן הקוד וגם בעמוד הקבצים לאדמין, בכרטיסי החיפוש בתיעוד (תיעוד). כל עמוד שטוען אותו יורש מ-base.html, אבל רק דפדפן הקוד טוען אתrepo-browser.css, ורק שם מוגדרים--border-colorו---accent-blue, בפלטה שב-:rootשלו. כלל משותף שקרא אותם ישירות נראה תקין בדפדפן הקוד בלבד: בעמוד הקבצים הקישורים יצאו בצבע הטקסט והגבולות ב-currentColor(נמדד בדפדפן). לכן הקובץ מצהיר על.markdown-preview-containerעל טוקנים של הרכיב,--md-preview-borderו---md-preview-accent, שקוראים את השניים עם fallback של אותה פלטה, והכללים המשותפים קוראים רק אותם. ההכרעה היא ירושה, כמו בתקדים שלsticky-md-render.cssשבהמשך:--border-colorשל ערכה מיובאת גובר בכל עמוד, ובעמוד שלא מגדיר אותו נכנסת הפלטה של דפדפן הקוד. זה חריג מתועד לאיסור על HEX בקבצי רכיבים: ה-fallback הוא עותק של הפלטה, ו-tests/test_markdown_preview_tokens.pyשומר שהוא שווה לערך שב-:rootשלrepo-browser.css, ושכל טוקן שכלל משותף קורא מוגדר בכל עמוד שטוען את הקובץ — ב-base.htmlאו בקובץ עצמו. וו דריסה (--*-override) אינו מוגדר בשום מקום בכוונה, ולכן נקרא תמיד עם fallback. מה נמדד ב-7.10.2026: בדפדפן הקוד אין אף הבדל לפני ואחרי, בכל הערכות; ובערכה מיובאת אמיתית הכרטיס זהה לדפדפן הקוד, גם בדגימת פיקסל של המשטח.Split View ו‑Markdown Enhanced משתמשים ב‑
--split-*ו‑--md-*בהתאמה – הוסיפו טוקן לפני שמוסיפים Class חדש.Sticky Notes, Reader Modes (md_preview.html) וה‑
theme_preview.htmlהם חריגים שנשארים Hardcoded כדי לשמור על תצוגת Preset.הכיוון ההפוך, וזה מה שהסעיף הזה לא אמר עד היום: משטח קשיח לא רק נמנע מ-
var()— הוא חייב לספק ערך לכל טוקן שכל רכיב שמוצג בתוכו קורא. האיסור למעלה מכסה את מה שהמשטח עצמו מצהיר, ולא את מה שיושב בתוכו. רכיב משותף שמרונדר על משטח קשיח ממשיך לקרוא טוקני ערכה — והם נבחרו לרקע אחר לגמרי, כלומר צבע שגוי בדיוק במידה שהרקע לא השתנה. קובץ CSS משותף אינו מספיק כאן, וההיסק ”זה אותו קוד ולכן זה נראה אותו דבר“ נכון למבנה ולמידות ושגוי לצבע.התקדים:
sticky-md-render.css(העיצוב של מנוע הפתק, שעבר מ-sticky-notes.cssבנובמבר 2026, העיצוב כקובץ משותף: sticky-md-render.css) מצהיר על--sticky-mark-bg/--sticky-mark-lineעבור.sticky-md-mark, ועל ששת הטוקנים של הבלוק המתקפל —--details-bg,--details-border,--details-hover,--summary-bg,--summary-color,--summary-arrow-color— שכולם בבעלותmarkdown-enhanced.css. ההצהרות יושבות על.sticky-note, וההכרעה היא ירושה ולא ספציפיות: הצהרת הערכה יושבת על<html>, ולכן האב הקרוב מנצח בתת-העץ ואין צורך ב-!important. (``.sticky-md-mark`` כן צריך אותו, אבל מסיבה אחרת לגמרי — שם קיימים כללי ערכה שמכוונים ל-markכאלמנט.)ומה שנמדד, כי בלי מדידה זה נראה תקין: לפני התיקון יצא הטקסט בגוף הבלוק בניגוד של 1.09:1 בערכה מיובאת כהה, והחץ 2.09:1 גם בערכה בהירה. ``–summary-bg`` הוא גרדיאנט, ולכן הוא נוחת ב-
background-imageו-background-colorנשארtransparent— כלומר בדיקה שמודדת רקbackground-colorעוברת גם על הקוד השבור. צבע על משטח כזה נמדד בדגימת פיקסל.ומקרה שני של כללי ערכה שמכוונים לאלמנט — הקישור, ושם
!importantלבדו אינו מספיק. קישור בפתק (.sticky-md-link) צבוע ב---note-link, שמוצהר על.sticky-noteכמו הדיו. היריבים הם[data-theme="…"] aו-a:hoverב-dark-mode.css, ו-[data-theme="high-contrast"] a,a:hoverו-a:focusב-high-contrast.css— והאחרונים הם!importantבעצמם. בין שתי הצהרות!importantמאותו מקור מכריעה הספציפיות (CSS Cascade 5, סעיף 6.1), ולכן הפתרון של.sticky-md-mark—!importantעל מחלקה אחת, (0,1,0) — מנצח את כלליdark-mode.cssומפסיד ל-(0,1,1) של High Contrast: בבדיקה חד-פעמית ב-12.10.2026 נקראgetComputedStyleשל קישור כזה בכרומיום 141, והוא נשאר צהוב. לכן הכלל בפתק כותב.sticky-noteלפני המחלקה, ול-:hoverול-:focusיש בורר משלהם, כדי לעלות על (0,2,1) ממש, ולא בשוויון:note_board.htmlו-repo/base_repo.htmlטוענים אתsticky-md-render.css(שבו כללי הקישור, צמוד לפניsticky-notes.css) לפני קבצי הערכות, ו-md_preview.htmlאחריהם, כך שבספציפיות שווה התוצאה הייתה תלויה במשטח. באותה בדיקה עלו גם שתי דליפות של מצב הריחוף שאינןcolor:a:hoverשלdark-mode.cssמוריד את ה-opacity, ו-text-decorationשל High Contrast הוא קיצור!importantשמאפס גם אתtext-decoration-thickness— ולכן הקו המתעבה בריחוף צריך!importantמשלו.tests/test_sticky_notes_link_color.pyגוזר את כללי ה-aמקבצי הערכות ודורש שכל אחד מהם יפסיד בפתק, בחשיבות ובספציפיות.מלכודת ספציפיות ב-
transition, שכל רכיב חדש נתקל בה.dark-mode.cssמגדירtransitionעל[data-theme="dark"] *(וכןdim,nebula,customו-shared:). הספציפיות של[attr] *שווה לזו של מחלקה יחידה, והקובץ נטען אחרי בלוקextra_cssשבתבנית — ולכן כללtransitionשנכתב על מחלקה אחת בקובץ רכיב נדרס בשקט בכל הערכות הכהות, וההנפשה פשוט לא רצה. הכשל שקט לחלוטין: אין שגיאה, ובדיקה בערכה בהירה עוברת. הפתרון שבשימוש ב-toast.cssהוא חזרה על שם המחלקה (.ck-toast.ck-toast), שמעלה את הספציפיות בלי!important. אותו טיפול נדרש גם לכלל ה-prefers-reduced-motionשל הרכיב, שאחרת נדרס באותה דרך.מלכודת קופסת גלילה ב-
overflow-x: hidden, שמשביתה כל אלמנט צמוד. למניעת גלילה לרוחב כותביםoverflow-x: clip, ולאhidden. לפי CSS Overflow 3,hiddenבציר אחד הופך את הציר השני ל-auto, ולכן המיכל נעשה קופסת גלילה גם כשהוא אף פעם לא גולל, כי הגובה שלו הוא גובה התוכן. לפי CSS Position 3,position: stickyנצמד לקופסת הגלילה הקרובה, ולכן אלמנט צמוד בתוך מיכל כזה נגלל עם העמוד ולא נצמד — בלי שום שגיאה.clipחותך לרוחב בדיוק אותו דבר בלי להפוך את המיכל לקופסת גלילה, ואתhiddenכותבים לפניו כנפילה-לאחור לדפדפן שאינו מכירclip. כך היו שבורים הסרגלים הצמודים בתצוגת קובץ, בתצוגת Markdown ובבונה הערכות, בגלל.main-content, .containerב-base.html; ומאותה סיבהglobal_search.cssכותבclipב-.search-and-filters .filters-row. ושני דברים שבאים עם אלמנט שבאמת נצמד: יעד שגוללים אליו עםblock: 'start'— עוגן, תוכן עניינים — צריךscroll-margin-topבגובה הסרגל בזמן שהסרגל צמוד, אחרת הוא נוחת מתחתיו (ב-md_preview.htmlהגובה נמדד ומפורסם כ---md-toolbar-h, כי בטלפון הסרגל נשבר לכמה שורות, והרווח חל רק באותו תנאי שבו הסרגל נצמד — ראו בהמשך, הצמדה רק בזמן חיפוש); ופריט grid צמוד נע — נמדד בכרומיום — בתוך כל מיכל ה-grid ולא רק בתוך התא שלו, ולכן כשהעמודות נערמות הוא עלול לגלוש על הפריט שמתחתיו (ב-theme_builder.htmlההצמדה מבוטלת ב-@mediaשבו הפריסה נערמת). ואת העמוד עצמו גוללbodyולא החלון, וקוד שמניח אחרת לא עושה כלום — ראו Issue #3534. והמעבר ל-clipמשחרר גם את מה שהמיכל חתך עד אז, ולא רק אלמנטים צמודים: החלוניות של התפריטים בסרגל העליון נחתכו עד אז בתוך.navbar > .container, ואחרי המעבר יצאו מתחת לסרגל אל מעל התוכן — ונפלו לשכבה שמתחת לתוכן (ראו בהמשך,z-indexעל אלמנט שאינו ממוקם). לכן אחרי שינוי כזה בודקים גם רכיבים צפים שבתוך המיכל, לא רק את מה שצמוד.z-indexעל אלמנט שאינו ממוקם — מת; והורה שיוצר הקשר ערימה כולא בתוכו את ה-z-indexשל הילדים. לפי MDN,z-indexחל על אלמנט ממוקם (positionשאינוstatic) ועל פריטי flex ו-grid, ו-transformאוbackdrop-filterשאינםnoneיוצרים הקשר ערימה, שרק בתוכו יש משמעות ל-z-indexשל הצאצאים..navbarשילב את שלושתם: ה-z-indexנשאר עליו מהימים שבהם היה צמוד (#559 הסיר את ההצמדה), ומאז שהואstaticהערך מת; וה-transformוה-backdrop-filterשלו כלאו בתוכו את חלוניות הקיצורים והאפקטים..main-contentממוקם עםz-indexמשלו ולכן מצויר מעל הסרגל, וכל חלק של חלונית שיצא מתחת לסרגל נראה — אבל הנגיעה בו הלכה לתוכן. הפתרון אינו להרים את הסרגל לתמיד: כפתורים וחלונות צפים שבתוך.main-content—#toggleBookmarksBtnבתצוגת קובץ, וחלונות שנפתחים על כל המסך — נשענים על כך שהסרגל מתחתם, ונמדד שהרמה קבועה מסתירה אותם בראש העמוד. במקום זה הסרגל עולה רק בזמן שאחד התפריטים שלו פתוח (.navbar:has(...)ב-base.html), והמצב נקרא מה-.activeשמציג את התפריט ולא מדגל נפרד. תפריט צף חדש בסרגל נכנס לרשימה שם, ו-tests/test_navbar_and_search_bars_css.pyשומר עליה. ובאותו תיקון: חלונית האפקטים מעוגנת ב-leftולא ב-inset-inline-end, כי ל-.fun-mode-dropdownישdirection: ltrמשלו, וצד לוגי מתורגם לפי הכיוון של האלמנט עצמו — כלומר ל-right, שפתח אותה אל מחוץ למסך.הצמדה רק בזמן חיפוש. הכלי הוא
:has()עם:placeholder-shown. סרגל חיפוש שצמוד תמיד מסתיר את ראש התוכן לאורך כל הגלילה, וחיפוש אינו שכיח מספיק כדי להצדיק את זה. לכן.editor-toolbarנצמד רק תחת.editor-toolbar:has(#codeSearchInput:not(:placeholder-shown))(ב-view_file.html), ו-.md-editor-toolbarבאותה צורה עם#mdSearchInput(ב-md_preview.html) — כלומר רק כשיש טקסט בתיבה — ובלי חיפוש הם נגללים עם העמוד. שני דברים שהתנאי נשען עליהם: לתיבה חייב להיותplaceholder, כי בלעדיו:placeholder-shownלעולם לא מתקיים והסרגל היה נצמד תמיד; ו-:placeholder-shownמתעדכן גם כשהקוד מרוקן את התיבה (input.value = '') — נמדד, ולכן ✕ משחרר את הסרגל בשתי התצוגות. דפדפן שאינו מכיר:has()מדלג על הכלל כולו, והסרגל פשוט לא נצמד.toast.cssמגדיר את משפחת--ck-toast-*(Level 3), ונטען רק בעמודים שמציגים טוסט (window.ckToastמ-toast.js) — ולא ב-base.html. מרחב השמות שלו נפרד מ-.notificationבכוונה:bookmarks.cssו-multi-select.cssמגדירים את הסלקטור ההוא בשניהם, עם ערכים סותרים. את ערכי הרקע והטקסט הוא מעתיק מ-bookmarks.cssבמקום לגזור אותם מ---bg-secondary; הגזירה נבדקה ונפסלה כי ב-Classic היא יורדת מתחת ליחס הניגודיות הנדרש.global_search.css הינו דוגמה מצוינת לרכיב Component Tokens – כאשר מוסיפים תכונה חדשה (למשל badge נוסף) המשיכו את התבנית שם.
Collections / Split View / Markdown Enhanced מוזכרים בדף זה כדי שמפתחים ידעו להצליב בין הרכיבים ולזהות אילו טוקנים משותפים.
קישורים ונספחים
ראה גם
webapp/FEATURE_SUGGESTIONS/css_refactor_plan.md– רשימות טוקנים מלאות לפי קובץ.FEATURE_SUGGESTIONS/css_refactor_plan.md– תקציר עסקי ובדיקות QA.FEATURE_SUGGESTIONS/theme_matrix.md– טבלת כיסוי טוקנים מקוצרת.webapp/FEATURE_SUGGESTIONS/webapp_theme_palettes.md– פירוט צבעים וערכי Markdown.webapp/templates/base.html– בלוק ה‑<style>: מקור כל ה‑Primitives ו‑:root[data-theme], קביעתdata-themeמוקדמת, וה‑Theme Wizard.webapp/static/css/dark-mode.css– שימוש בטוקנים עבור רכיבי Dark/Dim/Nebula.webapp/static/css/high-contrast.css– טוקני הבסיס של High Contrast, ובנוסף התאמות פוקוס/Outline. שאר הטוקנים שלה מושלמים ברמת הרכיב.webapp/static/css/global_search.css,split-view.css,bookmarks.css,collections.css,toast.css– דוגמאות מעשיות לטוקנים.Issue #2097 – מפרט Theme Builder (טוקנים במיקוד, UI/Backend/API, נגישות ו‑Reset flow).
לשאלות תיעוד/Testing יש לפנות לערוץ Frontend או לפתוח Issue חדש עם קישור לדף זה. הקפידו לעיין גם ב‑FEATURE_SUGGESTIONS/css_refactor_plan.md לפני שינויים רוחביים בקוד.