Custom themes in Typhon

All themes live in Settings → Appearance. That is also where you will find:

• theme picker — click a card. "System" switches between the built-in Light and Dark themes to follow your system setting;
• import — the "Import" button loads a theme file from disk (a .typhontheme or .json file);
• editor — opens under the selected theme: the name, the token values with a color picker for colors, and the "Custom CSS" field under the "Advanced" button. A live preview sits next to it;
• export — saves the selected theme to a .typhontheme file so you can move it to another computer or share it;
• delete — custom themes only. The built-in "Dark", "Light" and "High contrast" themes can be neither deleted nor overwritten: if you edit a built-in theme, your changes are saved as a new theme next to it.

Custom themes are stored in themes.json in the Typhon data folder: %APPDATA%\Typhon\ on Windows and ~/Library/Application Support/Typhon/ on macOS. There is no need to edit it by hand — use import and export to move themes around.

Save the text below as dusk.typhontheme (a .json extension works too), then open Settings → Appearance → Import in the launcher and pick that file. The theme appears in the list with a "custom" tag — click it to apply.

{
  "version": 1,
  "theme": {
    "id": "dusk",
    "name": "Dusk",
    "base": "dark",
    "tokens": {
      "--bg": "#0d1117",
      "--bg-sidebar": "#0b0e13",
      "--surface": "#131922",
      "--surface-2": "#18202b",
      "--surface-3": "#202a37",
      "--surface-4": "#293444",
      "--border": "rgba(255, 255, 255, 0.08)",
      "--border-strong": "rgba(255, 255, 255, 0.14)",
      "--hover": "rgba(255, 255, 255, 0.05)",
      "--hover-strong": "rgba(255, 255, 255, 0.08)",
      "--text": "#e8edf3",
      "--text-2": "#a0abb8",
      "--text-3": "#6b7785",
      "--accent": "#2fb3a3",
      "--accent-hover": "#3cc4b3",
      "--accent-subtle": "rgba(47, 179, 163, 0.15)",
      "--accent-text": "#6fd6c8",
      "--accent-ring": "rgba(47, 179, 163, 0.5)",
      "--radius-md": "1rem",
      "--radius-lg": "1.4rem"
    },
    "css": ".sidebar { border-right: 1px solid var(--border); }"
  }
}

From here it is easiest to fine-tune the theme in the launcher's own editor: select it, change the values, check the preview and click "Save".

A theme file is JSON with two top-level fields: version (currently always 1) and theme. Any extra field is an import error, so a typo in a field name does not slip through unnoticed.

The whole file must be no larger than 256 KiB. The builtIn and updatedAt fields that appear in an exported file are accepted on import, but the launcher sets them itself.

Importing again. If a custom theme with the same id already exists, the import replaces it, which makes it easy to update a theme you edit in an external editor. If the id matches a built-in theme (dark, light, contrast), the theme is saved under a new identifier such as dark-2 and the built-in one stays as it was.

What base does. The launcher uses it to tell whether the theme is light or dark and to pick shades of the personal accent to match. base does not fill in missing colors: a token the theme does not define is taken from the built-in dark palette. A light theme therefore has to define every color from the tables, or part of the interface will stay dark.

A token is a CSS variable the interface is built on. A theme may set any number of them; the rest keep their built-in values. Sizes are given in rem: with the interface size at 100% (Settings → General → Interface size), 1rem equals 11 pixels, and everything defined in rem scales together with that setting.

Colors

Radii and spacing

Layout

Text

Fonts come only from those installed on the system: a theme cannot load its own font file. Write font names in --font-sans without quotes, separated by commas: Segoe UI, sans-serif.

Animations and shadows

--ui-scale is not part of a theme: the interface size is controlled by a separate setting, and a theme cannot override it.

Allowed values

A token value is 1 to 120 characters from this set: Latin letters, digits, the space and # . , % ( ) / + * -. That is enough for colors (#1a2b3c, rgb(26 43 60 / 80%), hsl(210 40% 16%), color-mix(in srgb, #fff 8%, transparent)), sizes, calc(...), clamp(...) and references to other tokens via var(--accent).

Not allowed: quotes, semicolons, curly braces, !important, url(, expression( and /*.

Tokens cover almost everything, but sometimes you want to change something that has no variable. For that a theme has the css field, shown in the editor as "Custom CSS" under the "Advanced" button. The launcher adds this CSS to the page on top of the built-in styles for as long as the theme is active.

Limits:

• no more than 32 KiB;
• @import, url(, expression(, javascript:, behavior:, -moz-binding and </style are forbidden — a theme cannot load anything from the network or from disk, so there are no images or custom fonts through CSS either. The launcher's editor checks the CSS together with its comments, so do not write these words there either;
• --ui-scale is forbidden in CSS for the same reason as in tokens;
• curly braces must be balanced and nested no deeper than four levels. @media and @keyframes work.

Specificity. The launcher's component styles are scoped to the components themselves, so a rule such as .sidebar { background: ... } loses to the built-in one if it changes the same property. Properties a component does not set apply as written; to override one that is set, add !important.

Class names are not a contract. The tokens in the tables above are the stable interface for themes. Class names in the markup are internal to the launcher: they can change in any version, and CSS that relies on them may stop working after an update.

An example for a light theme: the scrollbar in the built-in styles is designed for a dark background and is barely visible on a light one.

::-webkit-scrollbar-thumb {
  background: rgba(0, 0, 0, 0.14);
  background-clip: padding-box;
}

::-webkit-scrollbar-thumb:hover {
  background: rgba(0, 0, 0, 0.24);
  background-clip: padding-box;
}

In a JSON file the CSS is written as a single line with line breaks as \n. It is easier to paste it into the "Custom CSS" field in the editor and then export the theme — the launcher writes it out correctly.

The Appearance section also has "Personal accent" — a color applied on top of any theme that adjusts its shades for readability. While one is selected, the theme's accent tokens (--accent, --accent-hover, --accent-subtle, --accent-text, --accent-ring) are not visible. To see the theme's own accent, choose "Theme color" in the personal accent. The personal accent is your local setting and is not included in an exported theme file.

Bad CSS can hide or cover the interface so that you cannot reach the settings. There are three ways to restore the default appearance:

1. The "Reset appearance" button in the bottom right corner of the window. It is always visible while a custom theme, or a theme with custom CSS, is active, and the theme's CSS does not style it.
2. The Ctrl+Shift+Alt+T shortcut in the launcher window.
3. Settings → Appearance → Reset, if you can still reach the settings: the "Reset" button there asks for confirmation.

In addition, a new theme counts as a trial for its first five seconds. If the launcher closes or crashes during that time, it returns to the previous theme on the next start.

Reset deletes all custom themes, along with the personal accent and the icon tint, and restores the built-in Dark theme. The corner button and the shortcut act immediately, without asking. So export the theme you are working on to a file from time to time — after a reset you can import it back and fix whatever broke the window.

If the launcher says "Could not complete the theme action", the file most often does not parse as JSON or has an extra field. Check the commas, the quotes around field names and the names of the top-level fields.