Making a theme

A theme can recolour Tetra Launcher, restyle any part of it, or rearrange the whole window. It's a folder of JSON and CSS, and the launcher checks every file, so a mistake shows up as a clear error instead of a broken window.

Tetra Launcher in the default Neutral theme: a sidebar on the left and card-style server rows
Neutral, the default
The same server list in the Tactical theme: tabs across the top, a dense table and a detail panel on the right
Tactical, built-in: same launcher, new layout

What a theme can change

Themes come in three levels, from a new palette alone to a custom layout. A copy of Neutral starts at colours only. To go further, add a styles.css (and a settings.schema.json for settings) and list "css" (and "settings") under capabilities in theme.json; until they are listed, the launcher ignores the CSS and won't export the theme. A copy of Tactical has all three levels to edit.

Colours only

A new palette for dark and light mode. Nothing else to learn.

tokens

Styled

Your own CSS for any element, plus settings users can tune.

tokenscsssettings

Custom layout

Move things around: panels, columns, navigation, window controls.

tokenscsssettingslayout

Recolour without code

To change colours only, you don't need to touch any files. This works on Neutral, Tactical or any theme you've installed:

  1. Open Settings → Theme and activate the theme you want to recolour.
  2. Press Customize tokens. Pick colours for dark and light mode, and adjust glow, corner roundness and fonts if you like.
  3. Type a name and press Save theme.

Your theme keeps the original's layout and styling with your colours, and shows up in the theme list. Later edits save with Save changes, and Export shares it.

Your first theme

  1. Open Settings → Theme and press New theme, then Copy Neutral or Copy Tactical. The launcher makes a copy of your own and switches to it. You can also open a theme card's ⋯ menu and pick Duplicate as new theme.
  2. In Settings → Launcher, press Open next to Data folder. Your theme is in themes/<your-theme-id>/.
  3. Turn on Dev Mode in Settings → Theme. It reloads your theme every time you save a file and lists anything the launcher rejected.
  4. Edit, save, look. When you're happy, use Export to share it.
Settings, Theme tab: installed themes, New theme and Import buttons, and the active theme's Customize tokens, Theme settings and Dev Mode buttons
Settings → Theme. New theme, Import and Dev Mode all live here.

The package

A theme is a folder named after its id. Only theme.json is required. A layout file you leave out keeps Neutral's version of that screen. Each file below needs the capability next to it declared in theme.json.

theme.json

theme.json
{
  "schemaVersion": 2,
  "themeApi": "2.0",
  "id": "midnight-ops",
  "name": "Midnight Ops",
  "author": "you",
  "version": "1.0.0",
  "minimumLauncherVersion": "2.6.0",
  "capabilities": ["tokens", "css"]
}

Capabilities must match your files exactly. Declaring css without a styles.css, or shipping one without declaring it, is an import error. The id must match the folder name, and ids starting builtin. are reserved.

Colours and tokens

tokens.json holds your palette and, optionally, sizes and fonts. Every key is optional. Anything you leave out keeps Neutral's value, so you can change one thing at a time.

tokens.json
{
  "schemaVersion": 2,
  "colors": {
    "dark":  { "bg": "#0e1016", "surface": "#151824", "accent": "#7c9cff", "text": "#e5e9f5" },
    "light": { "bg": "#f2f3fa", "surface": "#ffffff", "accent": "#3a4fbf", "text": "#171a2b" }
  },
  "scales": { "radius": { "md": "8px" } },
  "roles":  { "color": { "onAccent": "#0e1016" } }
}

Colours are per mode, roles are not. onAccent is used on top of both your dark and your light accent. Check it against both, or it may be unreadable in the mode you didn't test.

Styling with CSS

Every part of the launcher carries a stable data-el name, and those names are what your CSS targets. Your rules always win over the launcher's defaults, so you never need !important (it's refused anyway).

styles.css
/* An element */
[data-el="server.join"] { border-radius: var(--t-radius-control); }

/* A part inside it, and a state */
[data-el="server.players"] [data-part="caption"] { color: var(--muted); }
[data-el="server.join"][data-state~="busy"] { opacity: 0.6; }

/* Only the copy in the selected-server panel */
[data-context="selection"] [data-el="server.name"] { color: var(--accent); }

A few things are off limits so a theme can't break the launcher or reach the network:

styles.css — refused
[data-el="server.join"] { z-index: 5; }                 CSS-04
[data-el="server.join"] { color: red !important; }      CSS-01
@import url("other.css");                               CSS-06
.box { background: url("https://example.com/x.png"); }  CSS-07

Colours are --bg, --accent and friends; everything else is prefixed --t-, like --t-radius-row and --t-type-family-ui. The reference lists every selector, property and variable you can use.

Custom layouts

With the layout capability, each screen is one JSON file: a tree of containers (stack, grid, scroll, tabs …) holding the launcher's elements. This one puts the server details on the left of the list:

layout/views/browser.json
{
  "schemaVersion": 2,
  "root": {
    "type": "stack", "direction": "row",
    "children": [
      { "type": "stack", "context": "selection", "direction": "column",
        "children": [
          { "element": "server.name" },
          { "element": "list.serverMods" },
          { "element": "server.join" },
          { "element": "server.actionNotice" }
        ] },
      { "element": "list.servers", "grow": 1 }
    ]
  }
}

Theme settings

settings.schema.json adds your own options under your theme in Settings: numbers, on/off switches, choices and colours. A saved value reaches your CSS as --setting-<id>, and can show or hide parts of your layout.

settings.schema.json
{
  "schemaVersion": 2,
  "fields": [
    { "id": "compactRows", "type": "boolean", "label": "Compact rows", "default": false },
    { "id": "panelWidth", "type": "number", "label": "Panel width",
      "min": 240, "max": 420, "default": 300 }
  ]
}

Checking your work

Dev Mode shows what the launcher thinks of your theme while you edit it: outlines on every element, a click-to-pin inspector, contrast warnings, and a switcher to preview each window width and settings combination.

Dev Mode's validation panel over the Tactical theme, listing width and settings switchers and one contrast warning
Dev Mode on Tactical: one contrast warning, nothing fell back.

If a required element is hidden, off-screen or covered, only the file it lives in falls back to Neutral, and the panel names the element and the reason. Your colours and CSS stay in effect.

Limits

LimitValue
Files per package64
Package size, uncompressed8 MB
styles.css256 KB
Image size4096 × 4096
Nodes per layout file2,000
Width variants per file4
Preview images5