Creator docs

Theme Sideload Format (.fvtheme.json)

Updated · 2026-07-07Public document

One .fvtheme.json file is a complete theme. Put the file in thethemes/ folder inside app data (in the Agent workspace, that is /foreverse/themes/<id>.fvtheme.json, or just ask the in-app Agent to write it for you). It will appear next to built-in themes under "Settings -> Appearance", and tapping it applies it globally.

Top-level fields

Field	Required	Notes
`id`	Yes	Globally unique English id, such as `forest`; repeated ids overwrite the old theme with the same id
`name`	Recommended	Display name in the theme picker
`description`	Recommended	Picker subtitle
`isDark`	Yes	Whether this is a dark theme; affects status bar icon color and immersive handling
`palette`	Yes	Semantic color table; missing keys fall back to the built-in PaperWhite color with the same name

palette semantic color keys

Two-layer structure: base layer (bg / surface / line) + semantic layer (ink text, accent primary emphasis, ai intelligence emphasis).

Key	Meaning
`bg` / `bgTint`	Main page background / secondary background layer
`surface` / `surface2` / `surfaceSink`	Card surface / secondary surface / recessed surface (input background)
`line` / `lineStrong`	Weak divider / strong divider and stroke
`ink` / `inkSoft` / `inkMute` / `inkSoft2`	Main text / secondary / placeholder disabled / tertiary text
`accent` / `accentSoft` / `accentBg`	Primary emphasis (buttons, selected state) / softened emphasis / background fill (usually translucent)
`ai` / `aiSoft` / `aiBg`	Three levels of AI element emphasis, with hue kept distinct from accent
`hlYellow`	Highlight / underline yellow
`success` / `danger`	Success state / destructive delete state

Color syntax

#RRGGBB: 6 digits, treated as opaque.
#AARRGGBB: 8 digits, with the first two digits as alpha (ARGB order). accentBg / aiBg / line commonly use translucency, such as #1F6B5A35.
Invalid colors are ignored and fall back to built-in colors with the same key; they won't make the whole theme fail.

Design rules

Body text contrast: ink against bg / surface should meet accessible body-text contrast. Don't make ink gray in dark themes.
Layer separation: surface should visibly lift from bg.
Restrained emphasis: reserve accent for key actions; use low-opacity accentBg fills for larger areas.
Keep ai hue distinct from accent, so AI elements and brand actions don't blur together.
Dark themes must set isDark: true, or status bar icon color will be wrong.

Full example

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

Don't want to write it by hand? In the app's Agent tab, say "Make me a dark eye-care theme", and Agent will write the file directly into/foreverse/themes/. Refresh Appearance and you can select it.