Creating a Theme

Create a theme

A Serein theme is one JSON .serein-extension file. It has a version 1 manifest, no capabilities or actions, no Wasm module, and a theme object.

Minimal complete theme

Save this as my-theme.serein-extension and replace the creator details and colors:

{
  "manifest": {
    "api_version": 1,
    "id": "my-theme",
    "name": "My Theme",
    "version": "1.0.0",
    "author": "Your name",
    "license": "MIT",
    "source": "https://github.com/your-name/my-serein-theme",
    "kind": "theme",
    "capabilities": [],
    "actions": []
  },
  "theme": {
    "dark": {
      "colors": {
        "base": "#10141C",
        "sidebar": "#151B26",
        "chat": "#1A2230",
        "raised": "#222C3D",
        "hover": "#2B374A",
        "selected": "#34445C",
        "border": "#40516A",
        "text_strong": "#FFFFFF",
        "text": "#DCE5F2",
        "muted": "#98A8BC",
        "accent": "#7AA2F7",
        "accent_text": "#10141C",
        "link": "#9BB9FF"
      },
      "backdrop": ["#10141C", "#18243A"]
    },
    "light": {
      "colors": {
        "base": "#E9EEF6",
        "sidebar": "#F0F4FA",
        "chat": "#F8FAFD",
        "raised": "#FFFFFF",
        "hover": "#E1E8F2",
        "selected": "#D2DDEC",
        "border": "#BAC7D8",
        "text_strong": "#172033",
        "text": "#2E3B52",
        "muted": "#687790",
        "accent": "#315FAE",
        "accent_text": "#FFFFFF",
        "link": "#315FAE"
      }
    },
    "style": {
      "body_size": 15,
      "heading_size": 20,
      "button_size": 14,
      "small_size": 12,
      "monospace_size": 14,
      "item_spacing": [8, 8],
      "button_padding": [12, 6],
      "control_height": 32,
      "widget_radius": 4,
      "window_radius": 8,
      "menu_radius": 8
    }
  }
}

Color tokens

Colors use #RRGGBB or #RRGGBBAA. Every field is optional; omitted values inherit the selected built-in appearance.

Area	Tokens
Surfaces	base, sidebar, chat, raised, hover, selected, border
Text	text_strong, text, muted, link
Actions and states	accent, accent_text, positive, warning, danger
Mentions	mention_bg, mention_text

backdrop accepts exactly two colors for Serein's existing top-to-bottom background gradient. The user's custom accent color takes precedence over a theme's accent.

Style ranges

Distances and font sizes are whole logical pixels before the user's display scale.

Field	Default	Allowed range
body_size	15	10–28
heading_size	20	12–40
button_size	14	10–28
small_size	12	10–28
monospace_size	14	10–28
item_spacing	[8, 8]	each axis 0–24
button_padding	[12, 6]	each axis 0–24
control_height	32	24–56
widget_radius	4	0–24
window_radius	8	0–24
menu_radius	8	0–24

Unknown fields, unsupported color names, malformed colors, and out-of-range metrics are rejected before installation. Themes cannot rearrange panels, inject CSS or scripts, load fonts or images, fetch URLs, or change message data. Some fixed-size custom-painted controls retain their existing geometry.

Import the file from Settings → Themes → Import. If colors make controls difficult to read, press Ctrl+Shift+F12 to reset community appearance.

See the maintained Theme API and the complete bundled Ocean example.

Continue with Testing and Packaging.