Foreverse

创作者文档

主题侧载格式（.fvtheme.json）

Updated · 2026-07-07Public document

一个 .fvtheme.json 文件就是一套完整主题。把文件放进 App 数据目录的themes/ 文件夹（在 Agent 工作区里是 /foreverse/themes/<id>.fvtheme.json， 也可以直接让 App 内 Agent 帮你写），进「设置 → 外观」就会和内置主题一起出现，点选即全局生效。

顶层字段

字段必填说明
id是全局唯一英文 id（如 forest）；重复 id 覆盖同名旧主题
name建议主题选择器里的显示名
description建议选择器副标题
isDark是是否暗色，影响状态栏图标明暗与沉浸式处理
palette是语义色表；缺省的键回退到内置 PaperWhite 同名色

palette 语义色键

两层架构：底色层（bg / surface / line）+ 语义层（ink 文本、accent 主强调、ai 智能强调）。

键含义
bg / bgTint页面主背景 / 背景次层
surface / surface2 / surfaceSink卡片表面 / 次级表面 / 凹陷表面（输入框底）
line / lineStrong弱分隔线 / 强分隔线与描边
ink / inkSoft / inkMute / inkSoft2主文本 / 次要 / 占位禁用 / 三级文本
accent / accentSoft / accentBg主强调（按钮、选中）/ 弱化 / 背景填充（常用半透明）
ai / aiSoft / aiBgAI 智能元素强调色三档，与 accent 保持色相区分
hlYellow高亮 / 划线黄
success / danger成功态 / 危险删除态

颜色写法

  • #RRGGBB：6 位，按不透明处理。
  • #AARRGGBB：8 位，首两位是 alpha（ARGB 序）。accentBg / aiBg / line 常用半透明，如 #1F6B5A35。
  • 非法颜色会被忽略并回退到内置同名色，不会让整套主题失败。

设计准则

  • 正文对比度：ink 对 bg / surface 要达到无障碍正文级别，暗色主题别把 ink 做灰。
  • 两层不打架：surface 要能从 bg 上浮出来。
  • 强调克制：accent 只给关键动作；大面积用 accentBg 低透明度填充。
  • ai 与 accent 保持色相区分，智能元素和品牌动作不混淆。
  • 暗色主题务必 isDark: true，否则状态栏图标颜色会错。

完整示例

{
  "id": "forest",
  "name": "薄荷林间",
  "description": "晨雾山林",
  "isDark": false,
  "palette": {
    "bg": "#F4F7F4",
    "bgTint": "#EDF2ED",
    "surface": "#FFFFFF",
    "surfaceSink": "#E9EFE9",
    "line": "#DCE5DC",
    "ink": "#1F2A22",
    "inkSoft": "#54655A",
    "inkMute": "#8CA093",
    "accent": "#2F7D5C",
    "accentBg": "#1F2F7D5C",
    "ai": "#5C6BC0",
    "aiBg": "#1F5C6BC0"
  }
}

懒得手写？在 App 的智能体 tab 里说一句「帮我做一套暗色护眼主题」，Agent 会直接把文件写进/foreverse/themes/，刷新外观页即可选用。

Related pages

Foreverse 主题侧载格式 — .fvtheme.json 完整字段