主题

主题配置指南

本指南介绍如何自定义 Tentarc 的视觉主题。

概述

Tentarc 使用 6 色主题系统。你可以覆盖特定颜色，或安装包含完整视觉样式的预设主题。

主题覆盖: ~/.tentarc/theme.json - 覆盖特定颜色
预设主题: ~/.tentarc/themes/{name}.json - 完整主题包

两者都是可选的——应用程序有合理的内置默认值。

6 色系统

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

颜色格式

支持任何有效的 CSS 颜色格式：

Hex: #8b5cf6, #8b5cf6cc（带透明度）
RGB: rgb(139, 92, 246), rgba(139, 92, 246, 0.8)
HSL: hsl(262, 83%, 58%)
OKLCH: oklch(0.58 0.22 293)（推荐）
命名颜色: purple, rebeccapurple

推荐: 使用 OKLCH 以获得感知均匀的颜色，在浅色/深色模式下表现一致。

主题覆盖文件

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

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

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

深色模式

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

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

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

预设主题

预设主题是存储在 ~/.tentarc/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`	原始主题的 URL
`supportedModes`	包含 `"light"`、`"dark"` 或两者的数组
`shikiTheme`	语法高亮主题（浅色/深色变体）

安装预设主题

下载或创建主题 JSON 文件
保存到 ~/.tentarc/themes/{name}.json
在设置 → 外观中选择主题

风景模式

风景模式显示全窗口背景图片，配合玻璃风格面板。这创造了视觉沉浸式体验。

启用风景模式

{
  "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

玻璃面板的表面颜色

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

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

注意: 风景主题会自动强制使用深色模式，以便与背景图片形成更好的对比。

默认主题

内置默认主题使用针对无障碍优化的 OKLCH 颜色：

浅色模式:

Background: oklch(0.98 0.003 265) - 带轻微紫色调的极浅灰
Foreground: oklch(0.185 0.01 270) - 接近黑色以获得高对比度
Accent: oklch(0.58 0.22 293) - 鲜艳紫色
Info: oklch(0.75 0.16 70) - 温暖琥珀色
Success: oklch(0.55 0.17 145) - 清晰绿色
Destructive: oklch(0.58 0.24 28) - 警示红色

深色模式:

Background: oklch(0.145 0.015 270) - 带紫色调的深暗色
Foreground: oklch(0.95 0.01 270) - 接近白色
Accent/Info/Success/Destructive: 略微更亮的版本以提高可见性

示例

最小化：仅更改强调色

{
  "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 后 UI 会自动更新。

创建主题

创建 ~/.tentarc/theme.json 用于覆盖，或 ~/.tentarc/themes/{name}.json 用于预设
只添加你想自定义的颜色
可选地添加 dark 覆盖用于深色模式

提示:

从 accent 开始可以快速个性化
使用 OKLCH 获得可预测的颜色行为
在浅色和深色模式下都进行测试
保持无障碍的对比度（前景色与背景色）

故障排除

主题未生效:

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

深色模式下颜色看起来不对:

添加明确的 dark 覆盖
OKLCH 颜色在深色模式下可能需要更高的亮度值
检查预设的 supportedModes 是否排除了你当前的模式

背景图片不显示:

确保 mode 设置为 "scenic"
检查图片路径是相对于主题文件的还是有效的 URL
验证图片文件存在且可读

OKLCH 颜色参考

OKLCH 格式: oklch(lightness chroma hue)

Lightness（亮度）: 0-1（0 = 黑色，1 = 白色）
Chroma（色度）: 0-0.4（0 = 灰色，越高越饱和）
Hue（色相）: 0-360（色轮角度）

常见色相：

红色: ~25
橙色: ~70
黄色: ~100
绿色: ~145
青色: ~195
蓝色: ~250
紫色: ~293
粉色: ~330