---
title: "主题"
description: "在暗色和亮色之间切换 Peri 终端的配色方案。一条命令即时生效。"
---

> Documentation Index
> Fetch the complete documentation index at: https://konghayao.github.io/peri-cool/llms.txt
> Use this file to discover all available pages before exploring further.

# 主题

## 怎么用

```bash
/theme           # 打开主题面板（多余的参数会被忽略）
```

面板内 `Tab` 在暗色/亮色两个分类间切换，`↑/↓` 移动选择并实时预览，`Enter` 应用并保存；鼠标点击主题行同样生效，`Esc` 关闭并恢复原主题。

## 内置主题

Peri 内置两套主题，都使用暖橙色 `#D77757` 作为强调色：

### peri-dark（默认）

纯黑背景 `#000000`、白色文字 `#FFFFFF`，品牌强调色暖橙 `#D77757`。

```json
{
  "name": "peri-dark",
  "mode": "dark",
  "base": { "bg": "#000000", "fg": "#FFFFFF" },
  "brand": "#D77757"
}
```

### peri-light

暖白背景 `#FAFAFA`，文字 `#2E2E2A`。同样的暖橙强调色。

```json
{
  "name": "peri-light",
  "mode": "light",
  "base": { "bg": "#FAFAFA", "fg": "#2E2E2A" },
  "brand": "#D77757"
}
```

## 自定义主题

如果你不满意默认配色，可以自己写一个主题 JSON。放在 `~/.peri/themes/` 下。

> **Note**
>
> `extends` 字段会被忽略——自定义主题必须提供全部颜色键（`palette.*`、`semantic.*`、`component.*`），缺失任一键都会加载失败。

比如一个暗色主题，把品牌色从暖橙改成紫色（其余颜色键也需要补全，这里从略）：

```json
{
  "name": "my-purple",
  "mode": "dark",
  "palette": {
    "base": { "bg": "#000000", "fg": "#FFFFFF" },
    "brand": { "primary": "#7c3aed" }
  }
}
```

保存为 `~/.peri/themes/my-purple.json`，然后在主题面板里选中它，或 `/theme` 打开面板后加载。

> **Note**
>
> 主题 JSON 支持 `$ref` 引用：**字符串值**以 `$` 开头引用扁平化后的其他键，例如 `"fg": "$semantic.text.primary"`。引用的键必须存在，否则加载失败。

## 可定制的颜色层级

如果你要做深度定制，了解这三层：

| 层级 | 作用 | 例子 |
|------|------|------|
| `palette` | 原始色板——基础色、品牌色、灰度、语义色（成功/警告/错误）、diff 色 | 你主要改这里 |
| `semantic` | 文本色系、边框色、状态色、表面色 | 需显式定义，可用 `$` 引用 palette 里的值 |
| `component` | 具体组件的颜色——消息气泡、输入框、面板、弹窗、状态栏 | 需显式定义，可用 `$` 引用 semantic 里的值 |

三层都要提供完整键值——想改哪个键就写哪个键，其余键缺失会导致加载失败，建议先复制内置主题的完整定义再修改。

Source: https://konghayao.github.io/peri-cool/docs/features/theme/index.mdx