xiantong 文档
自定义

主题

使用 6 色主题系统自定义视觉外观

xiantong 使用 6 色主题系统，允许你自定义视觉外观。你可以覆盖特定颜色，或安装具有完整视觉样式的预设主题。

主题层级#

主题按以下优先级应用：

  1. 工作区覆盖：设置 → 外观 → 工作区主题 中的每个工作区主题
  2. 应用默认值：设置 → 外观 → 默认主题 中选择的主题
  3. 主题覆盖文件：~/.xiantong/theme.json - 覆盖特定颜色
  4. 预设主题：~/.xiantong/themes/{name}.json - 完整主题包

没有自定义主题的工作区会继承应用默认主题。

工作区主题#

每个工作区可以拥有自己的颜色主题，覆盖应用默认设置。这可帮助你在不同项目或场景间实现视觉区分。

配置工作区主题#

  1. 打开 设置 → 外观
  2. 在 默认主题 部分，设置全局默认
  3. 在 工作区主题 部分，为每个工作区选择主题：
  • 使用默认 - 继承应用默认主题
  • 自定义主题 - 选择特定预设

主题更改会立即在所有窗口中生效。如果你在同一工作区打开多个窗口，它们会实时同步更新。

存储位置#

工作区主题偏好存储在工作区配置中：

~/.xiantong/workspaces/{id}/config.json

{
"id": "ws_abc123",
"name": "My Project",
"defaults": {
"colorTheme": "nord"
}
}

当 colorTheme 被省略或未定义时，工作区会继承应用默认主题。

这是 工作区特定的默认主题。它会覆盖该工作区中新旧会话的应用默认主题。

6 色系统#

颜色用途使用场景
background表面/页面背景明/暗表面颜色
foreground文本和图标主文本颜色
accent品牌色、执行模式高亮、激活状态、紫色 UI 元素
info警示、问答模式琥珀色指示、注意状态
success已连接状态绿色勾、成功状态
destructive错误、删除操作红色警报、失败状态

主题覆盖文件#

创建 ~/.xiantong/theme.json 来覆盖特定颜色：

{
"accent": "oklch(0.58 0.22 293)",
"dark": {
"accent": "oklch(0.65 0.22 293)"
}
}

所有字段都是可选的。只需指定你想覆盖的颜色。

暗黑模式支持#

dark 对象提供可选的暗黑模式覆盖。当用户系统处于暗黑模式时：

  1. 基础颜色（顶层）作为默认值
  2. dark 中定义的任何颜色会覆盖基础颜色

这允许部分暗黑模式自定义 —— 只需覆盖需要不同的部分。

预设主题#

预设主题是完整的主题包，存储于 ~/.xiantong/themes/。每个预设是带有主题颜色和元数据的 JSON 文件。

预设主题架构#

{
"name": "Dracula",
"description": "A dark theme with vibrant colors",
"author": "Zeno Rocha",
"license": "MIT",
"source": "https://draculatheme.com",
"supportedModes": ["dark"],

"background": "oklch(0.22 0.02 280)",
"foreground": "oklch(0.95 0.01 270)",
"accent": "oklch(0.70 0.20 320)",
"info": "oklch(0.78 0.14 70)",
"success": "oklch(0.72 0.18 145)",
"destructive": "oklch(0.65 0.22 28)",

"shikiTheme": {
"light": "github-light",
"dark": "dracula"
}
}

预设元数据字段#

字段描述
name主题显示名称
description简短描述
author主题作者
license许可证类型（MIT 等）
source主题原始网址
supportedModes包含 "light"、"dark" 或两者的数组
shikiTheme语法高亮主题（亮/暗模式变体）

安装预设主题#

  1. 下载或创建主题 JSON 文件
  2. 将其保存到 ~/.xiantong/themes/{name}.json
  3. 在 设置 → 外观 中选择该主题

风景模式#

风景模式会显示全窗口背景图，并使用玻璃样式面板，营造更具沉浸感的视觉体验。

启用风景模式#

{
"mode": "scenic",
"backgroundImage": "mountains.jpg",

"background": "oklch(0.15 0.02 270 / 0.8)",
"paper": "oklch(0.18 0.02 270 / 0.6)",
"navigator": "oklch(0.12 0.02 270 / 0.7)",
"popoverSolid": "oklch(0.18 0.02 270)"
}

风景模式属性#

属性描述
mode设置为 "scenic"（默认是 "solid"）
backgroundImage图像文件名（相对主题文件）或 URL

玻璃面板的表面颜色#

风景模式适合使用半透明表面颜色：

颜色用途
paperAI 消息、卡片、浮层内容
navigator左侧侧边栏背景
input输入字段背景
popover下拉、模态、上下文菜单
popoverSolid保证 100% 不透明的弹出背景

风景主题会自动强制暗黑模式，以便与背景图形成更强的对比。

颜色格式#

支持任意有效 CSS 颜色格式：

格式示例
Hex#8b5cf6、#8b5cf6cc（带透明度）
RGBrgb(139, 92, 246)、rgba(139, 92, 246, 0.8)
HSLhsl(262, 83%, 58%)
OKLCHoklch(0.58 0.22 293)
命名purple、rebeccapurple

推荐：使用 OKLCH 来获得在亮/暗模式下都显得一致的感知均匀颜色。

OKLCH 参考#

OKLCH 格式：oklch(lightness chroma hue)

组成范围描述
明度0-10 = 黑，1 = 白
饱和度0-0.40 = 灰色，数值越大越饱和
色相0-360颜色轮角度

常见色相：

  • 红色：约 25
  • 橙色：约 70
  • 黄色：约 100
  • 绿色：约 145
  • 青色：约 195
  • 蓝色：约 250
  • 紫色：约 293
  • 粉色：约 330

示例#

最简：仅更改强调色#

{
"accent": "#3b82f6"
}

自定义品牌色#

{
"accent": "oklch(0.55 0.25 250)",
"info": "oklch(0.70 0.15 200)",
"dark": {
"accent": "oklch(0.65 0.25 250)",
"info": "oklch(0.75 0.12 200)"
}
}

高对比主题#

{
"background": "#ffffff",
"foreground": "#000000",
"dark": {
"background": "#000000",
"foreground": "#ffffff"
}
}

实时更新#

主题更改会立即生效 —— 无需重启。编辑 theme.json，界面会自动更新。

故障排除#

主题未生效

  • 确认 JSON 语法有效
  • 检查文件位置是否正确（覆盖文件为 ~/.xiantong/theme.json，预设为 ~/.xiantong/themes/）
  • 确保颜色值是有效的 CSS 颜色

暗黑模式下颜色显示异常

  • 添加明确的 dark 覆盖
  • OKLCH 颜色在暗黑模式下可能需要更高的明度
  • 检查预设的 supportedModes 是否包含当前模式

背景图未显示

  • 确保 mode 设置为 "scenic"
  • 检查图片路径是相对于主题文件的正确路径或有效 URL
  • 确认图片文件存在且可读取

贴士#

只从强调色开始

仅更改强调色是最快的个性化方式。

使用 OKLCH 以获得可预测性

OKLCH 颜色在亮/暗模式下比 Hex 或 RGB 更稳定。

在两种模式下测试

务必在亮/暗模式下都检查你的主题，以保证可读性。

保持对比可访问

确保前景与背景之间有足够的对比度。

上一页Lark / Feishu