#編寫 Aino 自定義主題

Aino Desktop 主題是一個本地 JSON 檔案。主題可以分別定義淺色與深色介面的背景、文字、強調色、邊框、圓角、字型、控制元件、陰影和動效，不需要安裝外掛，也不會執行 CSS 或 JavaScript。

#從現有配色開始

1. 開啟 設定 → 外觀。
2. 滾動到「建立自己的主題」，先選擇一套預設，或在下方微調顏色。
3. 在第 2 步「建立主題」中點選「複製建立主題提示詞」，把提示詞貼上給任意 AI，再補充你想要的氛圍、顏色與參考風格。提示詞已經包含當前主題 JSON。
4. 將 AI 返回的完整 JSON 儲存為 .json 檔案；如果希望手動編寫，也可以點選「匯出配色」獲得模板後直接編輯。
5. 點選「匯入配色」選擇修改後的檔案，再點選「預覽主題」，檢查淺色與深色方案的正文、側欄和控制元件。

「主題變數指南」會開啟本頁。選擇任意內建配色可以移除已匯入的語義變數覆蓋，恢復到可繼續微調的內建主題。

匯入成功後，Aino 會顯示診斷摘要：檔案是當前 v2 還是相容的舊 v1、淺色與深色方案分別識別了多少變數，以及哪些額外欄位被忽略。若識別變數為 0，說明檔案只包含基礎配色，因此介面只會發生有限的顏色變化。診斷只顯示欄位路徑，不顯示欄位內容。

未知或取值非法的主題變數不會被忽略，而會拒絕整份匯入，避免出現難以察覺的半套主題。$schema 是受支援的編輯器提示欄位，不會計入“已忽略欄位”。

#預覽主題

在第 3 步「匯入主題」中點選「預覽主題」，可以同時檢視側欄、頁籤、標題、正文、引用、程式碼、任務核取方塊、輸入框、按鈕、開關、滑動條、提示框和選單。

使用右上角的「淺色」「深色」切換預覽方案；輸入文字、點選開關或拖動滑動條，檢查互動狀態。預覽使用示例內容，不會修改筆記、當前外觀模式或個人設定。按 Escape 或點選關閉按鈕即可返回外觀設定。預覽後仍建議在日常使用的搜尋、任務和日曆檢視中檢查實際效果。

#變數參考與編輯器補全

主題變數參考列出了全部支援的變數、型別和有效示例，由應用內同一份變數定義自動生成。需要編輯器補全時，可在主題 JSON 頂層加入：

"$schema": "https://aino.md/schemas/appearance-theme.v2.zh-cn.schema.json"

也可供離線編輯器使用。Schema 檢查檔案結構、變數名、型別和基本字面量語法；顏色函式、陰影等字串中的數值範圍仍由 Aino 匯入時校驗。

Schema 的標題和取值說明支援全部 9 種介面語言。這裡使用簡體中文版；繁體中文、日語、德語、法語、西班牙語、葡萄牙語和阿拉伯語版本的檔案地址見主題變數參考。英文版保留原有預設地址，各語言版本使用相同的校驗規則。

#讓 AI 生成主題

應用內第 2 步「建立主題」中的「複製建立主題提示詞」，會把當前主題作為起點，並要求 AI 保留 Aino 的檔案格式、同時設計淺色與深色方案、只使用支援的變數，最後只返回可匯入的完整 JSON。

貼上提示詞後，把其中的風格佔位內容改成明確要求，例如：

低飽和、暖灰紙張質感；淺色模式參考日系文具，深色模式保持護眼；標題用墨綠色，連結用低飽和藍色，正文對比度優先。

如果 AI 返回了 Markdown 程式碼圍欄，請只複製圍欄內的 JSON。匯入失敗時，根據錯誤提示檢查未知變數、顏色格式、末尾逗號和缺失欄位。

#完整主題檔案

下面的檔案可以直接另存為 my-aino-theme.json 後匯入：

{
  "format": "aino-appearance-theme",
  "version": 2,
  "meta": {
    "name": "Deep Focus",
    "author": "Theme Author"
  },
  "theme": {
    "mode": "system",
    "accentColor": "#5aa7c5",
    "gradientEnabled": true,
    "accentSecondaryColor": "#7c88cf",
    "accentTertiaryColor": "#d17fa4",
    "backgroundColor": "#f4efe7",
    "editorBackgroundColor": "#fffdf9",
    "markdownBoldColor": "#1b2430"
  },
  "schemes": {
    "light": {
      "tokens": {
        "--background-primary": "#fffdf9",
        "--background-secondary": "#eee8df",
        "--interactive-accent": "#9c5f78",
        "--text-normal": "#25211d",
        "--text-secondary": "#625b53",
        "--background-modifier-border": "#d8cfc4",
        "--h1-color": "#7d3f59",
        "--h1-size": "2.1em",
        "--nav-item-color-active": "#7d3f59",
        "--tab-background-active": "#eee8df",
        "--tab-radius-active": "12px",
        "--button-background": "#fffaf5",
        "--button-background-hover": "#f4e9df",
        "--button-border-color": "#d8cfc4",
        "--button-radius": "10px",
        "--card-background": "#fffdf9",
        "--card-border-color": "#d8cfc4",
        "--card-radius": "14px",
        "--toolbar-background": "rgba(255, 253, 249, 0.86)",
        "--toolbar-backdrop-blur": "18px",
        "--toast-background": "rgba(255, 253, 249, 0.94)",
        "--modal-radius": "20px",
        "--modal-backdrop-blur": "16px",
        "--input-background": "#fffaf5",
        "--input-border-color-focus": "#9c5f78",
        "--input-radius": "10px",
        "--checkbox-color": "#7d3f59",
        "--checkbox-marker-color": "#ffffff",
        "--code-keyword": "#8b4f86",
        "--font-text-theme": "Georgia, serif",
        "--font-monospace-theme": "Menlo, monospace",
        "--font-text-size": "18px",
        "--sidebar-opacity": "0.8",
        "--sidebar-blur": "20px",
        "--menu-shadow": "0 8px 24px rgba(0, 0, 0, 0.12)",
        "--tooltip-radius": "8px",
        "--motion-duration-fast": "120ms",
        "--radius-m": "14px"
      }
    },
    "dark": {
      "tokens": {
        "--background-primary": "#10141c",
        "--background-secondary": "#171d27",
        "--interactive-normal": "#202836",
        "--text-normal": "#f3f6fa",
        "--text-secondary": "#bdc7d4",
        "--text-faint": "#8e9aaa",
        "--color-accent": "#5aa7c5",
        "--color-accent-1": "#7c88cf",
        "--color-accent-2": "#d17fa4",
        "--background-modifier-border": "#394555",
        "--h1-color": "#8ac9df",
        "--code-keyword": "#c7a0df",
        "--button-background": "#202836",
        "--button-background-hover": "#2a3546",
        "--button-border-color": "#394555",
        "--card-background": "#171d27",
        "--card-border-color": "#394555",
        "--toolbar-background": "rgba(16, 20, 28, 0.86)",
        "--toolbar-backdrop-blur": "18px",
        "--toast-background": "rgba(23, 29, 39, 0.94)",
        "--input-background": "#202836",
        "--input-border-color-focus": "#5aa7c5",
        "--font-text-theme": "Georgia, serif",
        "--font-monospace-theme": "Menlo, monospace",
        "--font-text-size": "18px",
        "--sidebar-opacity": "0.8",
        "--sidebar-blur": "20px",
        "--menu-shadow": "0 8px 24px rgba(0, 0, 0, 0.12)",
        "--tooltip-radius": "8px",
        "--motion-duration-fast": "120ms",
        "--radius-m": "14px"
      }
    }
  }
}

#頂層欄位

theme.mode 可使用 system、light 或 dark。主題變數可以提供字型、字號和排版預設值；個人在外觀設定中指定的字型、正文字號和緊湊密度優先。介面縮放和字型檔案仍由個人設定管理，不隨主題匯入匯出。

#可用主題變數

目前公開 292 個變數，可按需寫入淺色和深色方案。複製 AI 提示詞時，會一併附上最新的完整變數清單與取值約束。顏色匯入後統一儲存為小寫六位或八位十六進位制，透明度會保留。未寫的變數繼續使用基礎配色自動生成的值。

變數值按用途校驗：

顏色函式示例：rgba(20, 40, 60, 0.5)、hsl(120, 40%, 50%)。RGB 通道允許 0–255 或百分比，HSL 飽和度與亮度必須為百分比；透明度允許 0–1 或百分比。以上擴充套件格式用於 schemes.*.tokens，頂層 theme 的基礎配色仍使用十六進位制顏色。

所有變數值均為 JSON 字串，包括比率與不透明度。省略深色方案中的某個變數，會使用深色預設值，不會繼承淺色覆蓋值。

#Aino 元件變數

基礎配色負責建立整體色調；下面的 37 個元件變數用於讓主題真正覆蓋互動介面。生成主題時建議至少設計按鈕、卡片、輸入框、工具欄和彈窗，而不是隻修改背景與強調色。

這些變數是可選的。未提供時，元件繼續從基礎 Surface、邊框、圓角和陰影變數推導外觀，因此現有 v2 檔案無需遷移。

#Obsidian 主題變數相容

Aino 相容 Obsidian 的基礎變數、Markdown 編輯器變數和下列介面元件變數。同一份 JSON 可以直接使用下面的 Obsidian 變數名；它們會作用於 Aino 的應用框架、視覺化編輯器和即時預覽編輯器。變數命名與用途可對照 Obsidian 官方 CSS 變數文件。

這是一層變數相容，不是 Obsidian theme.css 載入器。Aino 不執行 CSS 選擇器、var()、color-mix()、url() 或 @import。遷移現有 Obsidian 主題時，請把最終顏色和尺寸換成上表允許的字面量，寫入 Aino JSON。

#基礎變數

其中常用基礎變數會自動對映到 Aino 介面：例如 --background-primary 對應編輯器紙面，--background-secondary 對應側欄，--interactive-accent 對應主強調色，--text-normal 對應正文。若同一組 tokens 同時寫了等價的 Aino 變數與 Obsidian 變數，Aino 變數優先。例如 --accent-primary 會覆蓋 --interactive-accent 對 Aino 主強調色的對映。

#Markdown 編輯器變數

目前不相容未列出的 Obsidian 視窗、頁籤堆疊、Ribbon、狀態列、Vault、外掛專屬變數，也不相容依賴 Obsidian DOM 選擇器的社群主題規則。匯入時出現未知變數，Aino 會指出該變數並拒絕整個檔案，避免產生半套主題。

#介面元件變數

以下 36 個變數可以寫入 schemes.light.tokens 或 schemes.dark.tokens。未設定時，各元件保留原有外觀；只設置淺色變數不會影響深色方案。複製建立主題提示詞時，應用會一併附上完整支援列表和變數型別。

導航變數作用於檔案樹和知識庫樹，包含半透明側欄。active 對應當前開啟的檔案，selected 對應多選，highlighted 對應定位提示；不會改變檔案樹行高和虛擬滾動佈局。頁籤變數作用於編輯器頁籤，--tab-font-weight 同時覆蓋普通和當前頁籤。

彈窗變數作用於通用表單彈窗和設定視窗；輸入框變數作用於通用表單、設定輸入框及檔案重新命名輸入框。任務核取方塊變數作用於視覺化編輯器和即時預覽：--checkbox-color 為已完成任務背景，--checkbox-marker-color 為勾選標記，--checkbox-border-color 為待辦任務邊框；對應的 -hover 變數控制懸停。進行中、取消和自定義任務狀態繼續使用各自的狀態顏色。

這些變數複用上方的顏色、圓角、長度、字號和字重校驗。元件字號僅控制對應元件；下方的排版變數提供主題預設值，個人外觀設定優先。參見 Obsidian 導航變數、頁籤變數和彈窗變數。

#排版與控制元件細節

以下排版、開關尺寸、滑塊和圖示命名參考 Obsidian 的排版、開關、滑塊和圖示文件。Aino 的實際作用範圍如下。

#Aino 材質、選單與動效

側欄頂部、啟動區和內容區共用一個背景繪製層。設定 --surface-sidebar 後，三處會保持同色；半透明效果由共同的背景層統一疊加。單獨給內嵌卡片配置顏色時，卡片可以與側欄背景不同。

個人正文字號會覆蓋 --font-text-size；個人字型會覆蓋介面與正文字型預設值，程式碼字型由 --font-monospace-theme 單獨控制。緊湊密度會覆蓋正文行高和間距。主題不會修改這些個人設定，選擇內建配色會清除主題提供的預設值。

#表面與編輯器

#文字、連結與強調色

修改三檔強調色時，Aino 會自動重建按鈕漸變和 --accent-primary-rgb，不需要在主題檔案中重複宣告派生變數。

#狀態、邊框與圓角

#校驗與安全限制

• 檔案必須是 UTF-8 JSON，副檔名為 .json，大小不超過 64 KB。
• JSON 不能寫註釋，也不能保留末尾逗號。
• 未知變數、無效顏色、超過範圍的圓角或缺失的必填欄位會使整個檔案匯入失敗，不會只應用一部分。
• 主題檔案不能包含 CSS、url()、@import、指令碼或網路資源。
• 匯入主題只改變介面外觀，不會讀取或修改筆記內容。

#釋出前自檢

• 淺色和深色分別檢查，不要只測試其中一種。
• 正文與背景的對比度建議至少達到 4.5:1，次要文字至少達到 3:1。
• 不要只靠紅色或綠色表達狀態，保留 Aino 原有的圖示與文字提示。
• 檢查按鈕懸停、鍵盤焦點、停用狀態、彈窗、搜尋結果和 Markdown 編輯器。
• 先匯出當前主題作為備份，再反覆匯入修改後的檔案。

Aino 的 AI 小程式會收到同一套公開語義變數，因此遵循主題變數編寫的小程式也會同步適配使用者主題。