docs menucreating a theme

creating a theme

give named color roles a new palette, without writing code.

color roles

a theme package contains a manifest and colors for a dark variant, a light variant, or both. it assigns colors to named roles rather than widget coordinates. the adapter connects each supported role to a real color site and its stored representation in an app build. roles and color encodings are generic; mapping them onto a framework or custom renderer is target-specific. live theme mappings are demonstrated on gpui targets today; mappings for other renderers remain unproven.

how a theme role reaches the appa theme assigns a color to a named role. if the adapter maps that role, the color goes to the mapped color site. if not, the role stays a key and nothing changes.yesnotheme rolemapped by adapter?color siteno change
how a theme role reaches the appa theme assigns a color to a named role. if the adapter maps that role, the color goes to the mapped color site. if not, the role stays a key and nothing changes.yesnotheme rolemapped by adapter?color siteno change

the core vocabulary below is shared. an adapter only supports the roles it actually maps, and a theme does not create mappings for missing elements. covering every token in a theme does not guarantee that an arbitrary app can be fully restyled.

rolemeaning
backgroundthe main application background
surfacepanels and raised surfaces
sidebarnavigation and side panels
overlaymenus, popovers, and modals
borderdividers and outlines
textprimary foreground text
mutedsecondary text
accentactive and highlighted elements
accent_texttext displayed on the accent color
linklink foregrounds

colors accept #RGB, #RGBA, #RRGGBB, and #RRGGBBAA, in either case. invalid colors, missing variants, empty palettes, and packages with the wrong extension kind are rejected.

theme example

this package defines a dark palette. replace its author and source metadata with your own. a light palette uses the same shape under light.

{
  "manifest": {
    "api_version": 1,
    "id": "ocean",
    "name": "ocean",
    "version": "1.0.0",
    "author": "you",
    "license": "GPL-3.0-or-later",
    "source": "https://example.invalid/ocean",
    "kind": "theme"
  },
  "theme": {
    "dark": {
      "colors": {
        "background": "#101C28",
        "surface": "#192C3C",
        "sidebar": "#142432",
        "overlay": "#20384A",
        "border": "#3B576B",
        "text": "#E8F4F8",
        "muted": "#8FA9B8",
        "accent": "#57CEE3",
        "accent_text": "#10202B",
        "link": "#8DE6F2"
      }
    }
  }
}

loading a theme

point FPUI_THEME at the theme file when loading the agent, or include it in the wrapper’s environment. FPUI_VARIANT=light requests light mode; otherwise dark is preferred. if the preferred variant is absent, the other one is used. the package is validated before use.

the adapter supplies each color site’s encoding and location. a role such as sidebar is just a stable key until that mapping exists. see the adapter contract for those fields and development setup for loading.