#编写 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 小程序会收到同一套公开语义变量，因此遵循主题变量编写的小程序也会同步适配用户主题。