Theme reference

Every field, name and code a theme can use, in one place. The guide explains how the pieces fit together; this page is for looking things up.

Manifest

Every theme has one required file, theme.json. It names the theme, lists the capabilities it uses, and points at its preview images.

FieldTypeRequiredRule
schemaVersionnumberNoMust be 2. Left out, it is 2.
themeApistringNoMust start with "2.". Left out, it is "2.0".
idstringYes[a-z0-9][a-z0-9._-]{2,63}: 3 to 64 characters, lowercase. Must match the folder name. builtin. is reserved; local. marks a theme the launcher owns.
namestringYes1 to 48 characters.
authorstringYes1 to 48 characters.
versionstringYesSemver, all three parts: 1.0.0.
minimumLauncherVersionstringYesSemver. Import is refused when it is newer than the launcher doing the import.
descriptionstringNoUp to 280 characters.
capabilitiesstring[]NoNames from Capabilities. Each one must match the files you ship.
previewsobject[]NoUp to 5. Each is { "file": "previews/card.png", "caption": "…" }, with a caption up to 80 characters; file must be a file under previews/. The first is the theme card's image.
licensestring or nullNoFree text. Not checked.
homepagestring or nullNoAn https: URL with a host.
tagsstring[]NoUp to 8, each up to 24 characters.
previewstringNoThe older single-preview field, from the v1 format. Used only when previews is empty.
tierstringNoAlso from v1, kept for display. No rule reads it.

A field marked required fails when it is left out: the missing field falls back to an empty value, which breaks the rule in the last column.

A key the launcher does not know is ignored, not refused. If you misspell capabilities, the manifest still loads, that field stays empty, and the error you get later names the empty default rather than the typo.

theme.json
{
  "schemaVersion": 2,
  "themeApi": "2.0",
  "id": "midnight-ops",
  "name": "Midnight Ops",
  "author": "you",
  "version": "1.0.0",
  "minimumLauncherVersion": "2.6.0",
  "description": "A cold palette and a dense server list.",
  "capabilities": ["tokens", "css"],
  "previews": [{ "file": "previews/card.png", "caption": "The server list" }],
  "license": "MIT",
  "homepage": "https://example.com/midnight-ops",
  "tags": ["dark", "dense"]
}

Capabilities

A capability is a claim that you ship the files it covers. The check is exact, file for file: declaring one without its file fails the import, and shipping the file without declaring it fails too.

CapabilityCovers
tokenstokens.json
cssstyles.css
fontsEverything under fonts/
imagesEverything under images/
layoutEverything under layout/
settingssettings.schema.json

Three things need no capability: theme.json, README.md, and anything under previews/.

The theme card in Settings shows one label, derived from what you declared:

LabelWhen
Custom layoutlayout is declared.
StyledNo layout, but css or fonts is declared.
ColoursAnything else, including tokens on its own.

The card reads v1.0.0 · Custom layout: the version from the manifest, then this label.

Package files and limits

A theme is a folder named after its id. Only theme.json is required. Every other file is optional, and a layout file you leave out keeps Neutral's version of that screen.

A theme package
<theme-id>/
  theme.json                  manifest (required)
  tokens.json                 colours, scales and roles
  styles.css                  theme stylesheet
  settings.schema.json        theme settings
  README.md                   author's notes
  layout/
    shell.json
    settings.json
    views/browser.json
    views/mods.json
    modals/serverInfo.json
    modals/modFilter.json
    modals/update.json
    lists/servers.json
    lists/mods.json
    lists/modFilterResults.json
    lists/serverMods.json
    lists/modServers.json
    popups/<popup-id>.json
  fonts/<name>.woff2|woff|ttf|otf
  images/<name>.png|webp|jpg|jpeg|svg
  previews/<name>.png|webp|jpg|jpeg

Those layout paths are the whole set. A popup id is one of mapFilter, modsUnique, modsUnsubscribe, modsVerify, regionFilter, serverActions, serverLoad, sort or tagsFilter. A path or an extension outside this list is refused at import.

WhereAllowed extensions
Anywhere in the packagejson, css, png, webp, jpg, jpeg, svg, woff2, woff, ttf, otf, md
fonts/woff2, woff, ttf, otf
images/png, webp, jpg, jpeg, svg
previews/png, webp, jpg, jpeg

A file must be what its extension claims: an image is decoded as the format it names, a font must carry a real font header, and a stylesheet must be valid UTF-8 and pass the CSS checks. An SVG is rendered as an image and never inlined. It must not carry script, event handlers, embedded web content (foreignObject) or links to other files, including url(…) and @import in its CSS; its CSS may not use escapes. Links inside the SVG (#id) and embedded PNG, JPEG, WebP or GIF data are fine.

LimitValue
Files per package64
Package size, uncompressed8 MB
Path depth3 segments
Image size4096 × 4096
styles.css256 KB
Nodes per layout file2,000
Node depth24
Text node120 characters
Free label40 characters
Column label24 characters
Variants per file4
Settings combinations64
Previews5
Preview caption80 characters
Theme classes per file200

Tokens

tokens.json sets colours, scales and roles. Every key is optional: anything you leave out keeps Neutral's value, so you can change one thing at a time. Only the names in the tables below are read; anything else in the file is ignored.

KeyTypeDefaultWhat it does
schemaVersionnumber2Must be 2.
colors.dark, colors.lightobjectNeutral's paletteThe twelve colours, one object per scheme.
bloomnumber0.9How far the glow spreads.
glowstringselectedalways, selected or never. Governs the launcher's own glowing surfaces; the glow's look is shadow.glow.
scalesobjectNeutral's stepsReplaces one step of a named scale.
rolesobjectNeutral's valuesPoints a role at a step name or a literal value.

Colours

Twelve per scheme, as #rrggbb strings.

TokenDarkLightUsed for
Surfaces
bg#0d0f13#f3f4f6The window background.
surface#12151b#ffffffPanels and cards.
surface2#1a1e26#e9ebefRaised surfaces: inputs, headers, popups.
border#262b34#d2d6dcLines and dividers.
Text
text#e7ebf0#181b20Primary text and headings.
muted#7a8494#5d6570Captions, labels and hints.
muted2#98a2b2#8a919dBody text.
Accents
accent#8fa3bd#3e5f7dThe primary action colour.
accent2#b0976a#8a6d34The secondary accent.
Semantic
success#4d9a75#287a4fReady and online states.
warn#c19a55#9a7b3aWarnings.
danger#b3564d#a94a42Errors and destructive actions.

Each colour becomes a CSS variable with the same name: --bg, --surface, --accent and so on. From them the launcher derives --border-weak, --muted-soft, --accent-soft, --accent-line, --accent2-soft, --accent2-line, --success-soft, --success-line, --warn-soft, --warn-line, --danger-soft, --danger-line, --row-hover, --row-selected and --glow. Those are read-only; they follow your colours.

Colours are per scheme, colour roles are not. colors.dark.accent and colors.light.accent are separate values, but roles.color.onAccent is a single value used on top of both. Check it against each scheme, or it may be unreadable in the one you did not test.

Scales

A scale step is redefined with scales.<scale>.<step>, and the rest of that scale keeps its defaults. Each step becomes a variable named --t-<scale>-<step>: --t-radius-md, --t-space-6, --t-type-size-xl, --t-type-family-ui, --t-shadow-lg, --t-motion-duration-fast. There is no --radius-*, --space-* or --font-ui.

ScaleSteps
radiusnone 0, xs 2px, sm 4px, md 6px, lg 8px, full 9999px
space0 to 48 in 2px steps, named by their pixel value: space.6 is 6px
type.size3xs 7px, 2xs 8px, xs 9px, sm 10px, md 11px, lg 12px, xl 13px, 2xl 14px, 3xl 22px
type.weightnormal 400, medium 500, semibold 600, bold 700, extrabold 800
type.trackingnone 0, tight -0.025em, wide 0.025em, wider 0.05em, widest 0.1em
type.leadingnone 1, tight 1.25, snug 1.375, normal 1.5, relaxed 1.625
type.familyui the bundled Inter stack, data the bundled JetBrains Mono stack
bordernone 0, hairline 1px, thick 2px
shadownone, sm 0 8px 24px rgba(0,0,0,0.4), md 0 10px 28px rgba(0,0,0,0.5), lg 0 12px 40px rgba(0,0,0,0.5), xl 0 24px 60px rgba(0,0,0,0.6), glow the launcher's glow
motion.durationfast 150ms, normal 200ms, slow 300ms
motion.easingstandard cubic-bezier(0.4, 0, 0.2, 1), linear

Roles

A role is a name the interface reads. A role value may be a scale step ("md") or a literal ("7px"). Each role is published as --t-<family>-<role>; the roles that carry several fields are published one variable per field.

Radius roles

RoleDefaultCSS variable
radius.windowlg (8px)--t-radius-window
radius.panel9px--t-radius-panel
radius.cardlg (8px)--t-radius-card
radius.modal10px--t-radius-modal
radius.modalLarge12px--t-radius-modalLarge
radius.popup7px--t-radius-popup
radius.popupItem5px--t-radius-popupItem
radius.rowlg (8px)--t-radius-row
radius.controlmd (6px)--t-radius-control
radius.controlSmallsm (4px)--t-radius-controlSmall
radius.controlCompact5px--t-radius-controlCompact
radius.inputmd (6px)--t-radius-input
radius.chipsm (4px)--t-radius-chip
radius.badge3px--t-radius-badge
radius.thumb7px--t-radius-thumb
radius.trackxs (2px)--t-radius-track
radius.pillfull (9999px)--t-radius-pill
radius.sidebarItem7px--t-radius-sidebarItem
radius.confirmlg (8px)--t-radius-confirm
radius.readinessRow5px--t-radius-readinessRow

Space roles

A default written as a bare number names a space step and resolves to that step's value, so 12 becomes 12px. A value with a unit is used as written.

RoleDefaultCSS variable
space.windowPad0--t-space-windowPad
space.panelPad16--t-space-panelPad
space.modalPad14--t-space-modalPad
space.popupPad4--t-space-popupPad
space.rowX12--t-space-rowX
space.rowY8--t-space-rowY
space.controlX12--t-space-controlX
space.controlY6--t-space-controlY
space.chipX4--t-space-chipX
space.chipY1px--t-space-chipY
space.stackGap12--t-space-stackGap
space.inlineGap6--t-space-inlineGap
space.sectionGap14--t-space-sectionGap
space.listGap6--t-space-listGap
space.controlCompactX8--t-space-controlCompactX
space.controlCompactY5px--t-space-controlCompactY
space.controlSmallX10--t-space-controlSmallX
space.controlSmallY2--t-space-controlSmallY
space.sidebarPad8--t-space-sidebarPad
space.sidebarSettingsPad10--t-space-sidebarSettingsPad
space.sidebarLogoY14--t-space-sidebarLogoY
space.sidebarListGap3px--t-space-sidebarListGap
space.sidebarItemGap10--t-space-sidebarItemGap
space.inlineGapWide8--t-space-inlineGapWide
space.inlineGapSmall4--t-space-inlineGapSmall
space.popupFilterPad5px--t-space-popupFilterPad
space.popupOffset5px--t-space-popupOffset
space.popupClearGap7px--t-space-popupClearGap
space.separatorX2--t-space-separatorX
space.separatorY4--t-space-separatorY
space.footerX14--t-space-footerX
space.footerY7px--t-space-footerY
space.footerGap14--t-space-footerGap
space.stateChipY3px--t-space-stateChipY
space.windowControlWidth40--t-space-windowControlWidth
space.windowControlHeight28--t-space-windowControlHeight
space.sidebarWidth176px--t-space-sidebarWidth
space.sidebarCollapsedWidth52px--t-space-sidebarCollapsedWidth
space.sidebarToggleOffset96px--t-space-sidebarToggleOffset
space.sidebarToggleHeight46--t-space-sidebarToggleHeight
space.searchMinWidth140px--t-space-searchMinWidth
space.popupMinWidth190px--t-space-popupMinWidth
space.popupMaxHeight320px--t-space-popupMaxHeight
space.scaleTrackWidth120px--t-space-scaleTrackWidth
space.scaleKnobSize7px--t-space-scaleKnobSize
space.sliderHeight3px--t-space-sliderHeight
space.stateDotSize5px--t-space-stateDotSize
space.pingTrackWidth56px--t-space-pingTrackWidth
space.dataWidth36--t-space-dataWidth
space.iconTiny11px--t-space-iconTiny
space.iconSmall12--t-space-iconSmall
space.iconChevron13px--t-space-iconChevron
space.iconMedium14--t-space-iconMedium
space.iconLarge18--t-space-iconLarge
space.iconBox22--t-space-iconBox

Type roles

Every type role carries five fields, and each one becomes a variable of its own: roles.type.body.size is --t-type-body-size, and the same pattern gives --t-type-body-family, --t-type-body-weight, --t-type-body-tracking and --t-type-body-leading.

RoleFamilySizeWeightTrackingLeading
displaydata3xl (22px)extrabold (800)none (0)none (1)
headingui2xl (14px)bold (700)none (0)snug (1.375)
subheadinguilg (12px)semibold (600)none (0)normal (1.5)
bodyuimd (11px)normal (400)none (0)normal (1.5)
labeluism (10px)semibold (600)none (0)normal (1.5)
captionuixs (9px)normal (400)none (0)1.4
microui2xs (8px)normal (400)none (0)normal (1.5)
buttonuism (10px)bold (700)wider (0.05em)normal (1.5)
chipui2xs (8px)bold (700)0.04em1.3
datadatasm (10px)normal (400)none (0)normal (1.5)
rowNameuilg (12px)semibold (600)none (0)normal (1.5)
rowMetauixs (9px)normal (400)none (0)normal (1.5)
statValuedataxl (13px)bold (700)none (0)none (1)
statCaptionui3xs (7px)bold (700)0.07emnormal (1.5)
branduixl (13px)bold (700)0.06emnormal (1.5)
compactMicroui8.5pxnormal (400)none (0)normal (1.5)
compactCaptionui9.5pxnormal (400)none (0)normal (1.5)
compactBodyui10.5pxnormal (400)none (0)normal (1.5)
compactHeadingui13.5pxnormal (400)none (0)normal (1.5)
compactSubheadingui11.5pxnormal (400)none (0)normal (1.5)
compactTitleui12.5pxnormal (400)none (0)normal (1.5)

Colour roles

RoleDefaultCSS variable
color.onAccent#10131a--t-color-onAccent
color.onAccent2#10131a--t-color-onAccent2
color.onDanger#10131a--t-color-onDanger
color.onSuccess#10131a--t-color-onSuccess
color.focusRingvar(--accent-line)--t-color-focusRing
color.scrimrgba(5,8,13,0.7)--t-color-scrim
color.scrimBlockingrgba(0,0,0,0.9)--t-color-scrimBlocking
color.rowHovervar(--row-hover)--t-color-rowHover
color.rowSelectedvar(--row-selected)--t-color-rowSelected

Border roles

RoleDefaultCSS variable
border.hairlinehairline (1px)--t-border-hairline
border.controlhairline (1px)--t-border-control
border.focusthick (2px)--t-border-focus

Shadow roles

RoleDefaultCSS variable
shadow.panelnone--t-shadow-panel
shadow.modallg (0 12px 40px rgba(0,0,0,0.5))--t-shadow-modal
shadow.popupsm (0 8px 24px rgba(0,0,0,0.4))--t-shadow-popup
shadow.popupFiltermd (0 10px 28px rgba(0,0,0,0.5))--t-shadow-popupFilter
shadow.drawer-10px 0 26px rgba(0,0,0,0.4)--t-shadow-drawer
shadow.glowglow (the launcher's glow)--t-shadow-glow
shadow.confirm0 25px 50px -12px rgb(0 0 0 / 0.25)--t-shadow-confirm
shadow.update0 25px 50px -12px rgb(0 0 0 / 0.5)--t-shadow-update
shadow.inspector0 8px 24px rgba(0,0,0,0.5)--t-shadow-inspector
shadow.statusDot0 0 4px currentColor--t-shadow-statusDot
shadow.stateWarning0 0 4px var(--warn)--t-shadow-stateWarning
shadow.readinessWarning0 0 5px rgba(193,154,85,0.6)--t-shadow-readinessWarning
shadow.readinessSuccess0 0 5px rgba(77,154,117,0.6)--t-shadow-readinessSuccess

Motion roles

RoleFieldDefaultCSS variable
motion.hoverdurationfast (150ms)--t-motion-hover-duration
motion.hovereasingstandard--t-motion-hover-easing
motion.expanddurationnormal (200ms)--t-motion-expand-duration
motion.expandeasingstandard--t-motion-expand-easing
motion.overlayduration0ms--t-motion-overlay-duration
motion.overlayeasingstandard--t-motion-overlay-easing
tokens.json
{
  "schemaVersion": 2,
  "colors": {
    "dark":  { "bg": "#0e1016", "accent": "#7c9cff", "text": "#e5e9f5" },
    "light": { "bg": "#f2f3fa", "accent": "#3a4fbf", "text": "#171a2b" }
  },
  "glow": "selected",
  "scales": { "radius": { "md": "8px" } },
  "roles":  { "color": { "onAccent": "#0e1016" } }
}

Layout nodes

With the layout capability, each screen is one JSON file: a tree of containers holding the launcher's elements. A file carries either one root or a variants array, never both. Variants are whole alternative roots chosen by the window's width: two to four entries, ordered by ascending minWidth, the first being 0. The launcher renders the last entry whose minWidth is at or below the current width.

layout/views/browser.json
{
  "schemaVersion": 2,
  "variants": [
    { "minWidth": 0,   "root": { "type": "stack", "direction": "column", "children": [] } },
    { "minWidth": 900, "root": { "type": "stack", "direction": "row", "children": [] } }
  ]
}

Containers

Every container takes children, plus the common props below.

TypeIts own propsValues
stackdirection, align, justify, wrap, gap, tagdirection row or column; align start, center, end, stretch, baseline; justify the same plus spaceBetween and spaceAround; gap a space token or role; tag div (default) or span
gridcolumns, rows, areas, gap, columnGap, rowGap, alignItems, justifyItems, tagtag as for stack. Track lists hold lengths, fr values, auto, min-content and max-content; areas is a rectangular array of area names that children name with area
boxNoneA plain wrapper with no layout of its own
scrollaxisy or x, default y. The only way to get a scrolling area
tabstabs, orientationEach tab is { "id": "info", "label": <node>, "content": <node> }; ids match [a-z0-9-]+ and are unique in the container; orientation is horizontal (default) or vertical
accordionsections, mode, initialEach section is { "id": "game", "header": <node>, "body": <node> }; mode is single or multiple; initial is none or first. Both are required

Leaves

LeafShape
Element{ "element": "server.join", "options": { … } }, optionally with label and glow. The name must be one the launcher knows
Surface{ "surface": "surface.filterBar" }, a launcher-composed group placed whole
Text{ "type": "text", "value": "REQUIRED MODS", "role": "label" }, where role is one of display, heading, subheading, body, label, caption, micro, button, chip or data
Image{ "type": "image", "src": "images/logo.png", "fit": "contain" }, or { "type": "image", "icon": "globe" }. fit is cover or contain
Outlet{ "type": "outlet", "name": "view" } or "modals". Shell only, once each

Text is plain, up to 120 characters, with no markup, links or data. An image from the package must be a file under images/; an icon takes a name from Icons. Images are decorative: they render as <img alt=""> and are hidden from screen readers. The view outlet holds the current view; the modals outlet is where modals and popups render.

Common props

PropValues
idA region id, r-[a-z0-9-]+, unique within the theme. Only needed when something refers to the node
classOne or more class names, each matching t-[a-z0-9-]+
padding, paddingX, paddingY, paddingTop, paddingRight, paddingBottom, paddingLeft, gapA space token or a space role. Never a raw length. There are no margins
width, height, minWidth, maxWidth, minHeight, maxHeight<n>px, <n>%, auto, min-content, max-content or a space token; grid tracks also take <n>fr
grow, shrink, basisFlex behaviour inside a stack
areaA grid area name, inside a grid that declares areas
position{ "anchor": "topRight", "x": "8px", "y": "8px" }. Anchors are topLeft, top, topRight, left, center, right, bottomLeft, bottom, bottomRight; offsets move the node inward from the anchor
hiddentrue, or { "setting": "compactRows", "equals": true }, or "not" in place of "equals". The setting must be a boolean or choice field
landmarknavigation, main, complementary, banner or contentinfo. At most one each of main, banner, contentinfo and navigation per composition; complementary may repeat. The launcher supplies the accessible name
glowElement nodes only: always, selected or never. selected glows while the element's state is current, selected, on, active, checked or open
contextselection, modSelection or modFilterPreview, with an optional empty subtree shown when there is no subject. Contexts do not nest
collapsible{ "default": "expanded", "collapseBelow": "720px", "collapsed": <node> }. The collapsed subtree replaces children, and a required element inside the region must appear in both. collapseBelow is an optional positive px length: while the window is narrower than it the region collapses whatever the saved choice, and the saved choice applies again once the window is at least that wide.
resizable{ "edge": "right", "min": "160px", "max": "420px" }. The handle is focusable; the arrow keys move it in 8px steps and Home and End jump to the limits
columnA column id. Only on a direct child of a list row's root, and only when the list file declares columns

Any other prop on a node is an error, so a typo cannot pass silently.

What every composition must keep

A few elements have to be somewhere in each composition: the window controls, the drag region, navigation to every view and Settings, and, wherever server.join sits outside a list row (modals, popups, panels), server.actionNotice beside it. The launcher checks that the element is placed anywhere in the composition, not in a fixed slot, and it checks every variant and every settings combination a user can reach.

A missing required element fails the file that should contain it. Validation refuses that one layout file, and only that file falls back to Neutral's version of the screen. Your tokens and CSS stay in effect. A FALLBACK notice says it happened once per theme per launcher version, and Dev Mode names the file, the element and the reason.

Launcher messages, join warnings and launch refusals among them, show as toasts in the top-right corner, which the launcher owns. A notice.* placement renders nothing; the elements stay registered so older layouts still validate. List rows never show server.actionNotice, so a row's join result appears as a toast naming the server.

Tab order is file order: keyboard users move through the screen in the order you declared the nodes. Stacking also follows declaration order — the launcher owns the layers, and no z-index is involved. A list element owns its own scrolling, so it cannot sit inside a scroll container.

List files

One file per list, under layout/lists/. A list file has a row template and, optionally, columns; it never has root or variants, so a list adapts through its columns, its wrapping and overflowX.

KeyTypeDefaultRule
schemaVersionnumber—Must be 2.
columnsarray—Column definitions. Optional
rownode—The row template. Its root node is the row; the launcher adds no wrapper
emptynode—Replaces the launcher's wording when the list is empty
headerbooleantruefalse hides the header
overflowXstringclipclip or scroll. With scroll the header sticks inside the scroller, rows stay at least as wide as the fixed columns, a trailing fr column absorbs the surplus, and the list scrolls sideways with Shift+wheel or the wheel over the header
estimatedRowHeightstringPer listA pixel length. It seeds the measurement; real heights are measured
Column fieldRule
id[a-z0-9-]+, unique in the file
labelUp to 24 characters. Only on a column with no sort, which takes the launcher's wording instead
widthA length, <n>fr or auto. Required
minWidth, maxWidthLengths
alignstart, center or end
sortA sort key from that list's set. An unknown key is an error
resizableBoolean, default true. Only a column with a pixel width resizes; fr and auto columns never do
headerElementAn element id to draw in the header cell instead of a label. Only where the element is allowed to appear in that list

Columns are drag-resizable in every list that declares them, with a floor of minWidth (48px by default). Widths persist per theme and per list, and double-clicking the resize handle resets a column to its declared width. A sortable heading is a button: clicking it sorts by that key, and clicking again reverses the direction.

ListSort keys
list.serversplayers, ping, mods, name, map, lastPlayed
list.modsstatus, name, size, updated, subscribed
ListDefault row heightHeader
list.servers56pxShown
list.mods54pxShown
list.modFilterResults44pxShown
list.serverMods32pxHidden
list.modServers32pxHidden

list.servers, list.mods and list.modFilterResults render only the rows on screen and own their scrolling; list.serverMods and list.modServers render every row. Clicking a row selects its subject, clicking an element inside it runs that element and never changes the selection, and rows themselves are not focusable.

layout/lists/servers.json
{
  "schemaVersion": 2,
  "columns": [
    { "id": "name",    "label": "SERVER", "width": "1fr",  "align": "start", "sort": "name" },
    { "id": "players", "width": "72px", "align": "end", "sort": "players" },
    { "id": "actions", "width": "auto", "align": "end" }
  ],
  "row": {
    "type": "grid",
    "children": [
      { "element": "server.name",    "column": "name" },
      { "element": "server.players", "column": "players" },
      { "element": "server.join",    "column": "actions" }
    ]
  }
}

CSS API

One file, styles.css, capped at 256 KB. The launcher wraps it in a cascade layer, so your rules win over the launcher's defaults and Neutral's look without a specificity fight. The few launcher rules that keep required elements visible and usable sit above it and still win.

Selectors

FormExample
An element[data-el="server.join"]
A part of an element[data-el="server.players"] [data-part="caption"]
A state[data-el="server.join"][data-state~="busy"]
A context[data-context="selection"] [data-el="server.name"]
A list, a row or a column[data-list="servers"], [data-row][data-state~="selected"], [data-column="players"]
A region or a surface[data-region="r-detail"], [data-surface="surface.filterBar"]
A class of your own.t-detail-rail
Interaction:hover, :focus, :focus-visible, :active, :disabled, :checked
Structure:not(), :is(), :where(), :nth-child(An+B) (or odd / even), :first-child, :last-child
Generated boxes::before and ::after, with content: "" only
CombinatorsDescendant, >, +, ~
Scrollbars and sliders::-webkit-scrollbar, ::-webkit-scrollbar-thumb, ::-webkit-scrollbar-track, ::-webkit-scrollbar-corner, ::-webkit-slider-thumb, ::-webkit-slider-runnable-track

[data-el], [data-part], [data-state], [data-context], [data-list], [data-row], [data-column], [data-region] and [data-surface] are the element, part, list and region names the launcher publishes. The other accepted attribute selectors are [aria-selected], [aria-pressed], [aria-expanded], [aria-sort], [disabled], [data-tetra-slot] and [data-tetra-el]. Anything else, such as [href], [title] or [class], is refused.

Refused: a type selector (div), an id selector, the universal selector, any class that is not one of your own t-[a-z0-9-]+ names, any other attribute, any other pseudo-class or pseudo-element, and !important. After a space, a pseudo-class such as :hover or :not() must follow something specific ([data-el="x"] [data-part="y"]:hover, not [data-el="x"] :hover); >, + and ~ are fine. :is() and :where() may follow a space when every selector inside them starts with something specific. A nested rule without & counts as following a space.

Properties, values and at-rules

Every property is allowed except z-index and the launcher's --z-* stacking variables, because the launcher owns stacking. content is allowed only as "".

Values may not contain expression(, -moz-binding, behavior:, javascript:, vbscript: or @import. A url() may only name a file inside your own package, such as url("fonts/x.woff2") or url("images/logo.png"): a URL with a scheme (including https: and data:), a scheme-relative URL, and a path containing .. are all refused. Inside @font-face, the source must be a file under fonts/.

Three at-rules are allowed: @media with width, prefers-reduced-motion or prefers-color-scheme; @keyframes; and @font-face naming a font in your package. Everything else, including @supports, @container and @layer, is refused.

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
.box { background: url("../outside.png"); }            CSS-07

Tokens and settings in CSS

Colours keep their bare names (--bg, --accent, --row-selected); every other token is prefixed --t-, for example --t-radius-row, --t-space-6 and --t-type-body-size. A theme setting reaches CSS only as a --setting-<id> custom property on the window root; the value is never written into the stylesheet text, so it cannot smuggle a rule past validation.

styles.css
[data-el="server.name"] {
  padding-inline-start: calc(var(--setting-rowSpacing, 4) * 1px);
  color: var(--accent);
  font-family: var(--t-type-family-ui);
}

Theme settings

settings.schema.json adds your own options under your theme in Settings. A saved value reaches tokens and layout by substitution, CSS as a custom property, and can show or hide a node.

TypeNeedsRule
numbermin, max, defaultAll three are finite numbers, the minimum must not exceed the maximum, the default must lie between them, and step, if given, must be a positive number
booleandefaulttrue or false
choiceoptions, defaultAt least two options, each { "value": "side", "label": "Side" } with a value matching [a-z0-9-]+ and a label of 1 to 40 characters. The default must match one of the values
colordefault#rrggbb

Every field needs id, type and label. An id matches [a-z][a-zA-Z0-9]{0,31} and is unique; a label is 1 to 40 characters. A malformed field is dropped with an issue in Dev Mode, and the rest still load.

A value reachesHow
tokens.json and layout files{{id}} substitution. A string that is exactly one placeholder takes the value's own type, so a number field can drive a numeric token; a placeholder inside a longer string is plain text
CSSOnly as --setting-<id> on the window root
Layout structureA boolean or choice field can drive a node's hidden

The launcher expands every combination of your boolean and choice fields — at most 64 — and checks the required-element rules against each one, so a combination that hides a required element fails at import rather than at runtime. number and color fields change nothing structural, so they are not expanded. Tuned values are stored next to the package and are skipped on export.

settings.schema.json
{
  "schemaVersion": 2,
  "fields": [
    { "id": "rowSpacing", "type": "number", "label": "Row name indent",
      "min": 0, "max": 16, "step": 1, "default": 4 },
    { "id": "compactRows", "type": "boolean", "label": "Compact rows", "default": false },
    { "id": "accentStyle", "type": "choice", "label": "Accent style",
      "options": [ { "value": "solid", "label": "Solid" },
                   { "value": "soft",  "label": "Soft" } ],
      "default": "solid" },
    { "id": "highlight", "type": "color", "label": "Highlight", "default": "#8fa3bd" }
  ]
}

Validation rules

Every refusal carries a stable code. The code, together with the file it came from and a pointer to the exact node, is what Dev Mode and the import preview report. An error blocks an import; at load, the file it belongs to falls back to Neutral's version of that screen while the rest of your theme stays in effect.

CodeWhat it means
LAY-01The file's outer shape is wrong: not a JSON object, a version other than 2, both root and variants or neither, a list template that carries a root, a malformed column entry, a bad overflow setting, or a bad tabs orientation
LAY-02A node's type is not a container or leaf the launcher knows
LAY-03A property is not allowed on that node, or its value has the wrong shape — including glow on a node that is not an element, and a hidden condition naming a setting that is not a boolean or choice field, or a text role that is not one of the text roles
LAY-04A size is wrong: a width, height or basis that is not a length, a keyword or a space token; a bad grid track; an estimated row height that is not a pixel length; a resize bound that is not a size, or a collapseBelow that is not a positive pixel length
LAY-05Spacing is wrong: a margin was used, or a padding or gap is not a space token or space role
LAY-06Positioning is wrong: position is not an object, the anchor is unknown, or an offset is not a length or space token
LAY-07A region id does not match r-[a-z0-9-]+
LAY-08A region id is used twice, inside one root or in another file
LAY-09Something refers to a region id that does not exist
LAY-10The variant list is wrong: not an array, fewer than two or more than four entries, widths that do not start at 0 and rise, or an entry with no root
LAY-11A tabs node is wrong: no tabs, a missing, invalid or duplicated tab id, or a tab without its label or content node
LAY-12An accordion node is wrong: a bad mode or initial value, no sections, a missing, invalid or duplicated section id, or a section without its header or body node
ELE-01An element, surface or header element the launcher does not know
ELE-02That element or surface cannot be placed here: the wrong file, the wrong subject, or a list header it is not allowed in
ELE-03A context is unknown, nested, or unavailable in that file; or the element needs a subject the context does not provide
ELE-04An element is placed more than once where only one is allowed
ELE-05An option the element does not have
ELE-06An option value is invalid, options is not an object, or a free label is not plain text
ELE-07A free label was given for an element that takes none
ELE-08A free label is longer than 40 characters
LST-01A list file that is not one of the known lists, or a reference to a list that does not exist
LST-02Two columns share an id
LST-03A column width is missing, or is not a length, an fr value or auto
LST-04A column sort key that list does not support
LST-05A column property outside a direct child of a row template that declares columns
LST-06A list element placed inside a scrolling container
REQ-01A required element is missing from a view
REQ-02A required element is missing from Settings
REQ-03A required element is missing from a modal
REQ-04A required element is missing from a popup
REQ-05A required element is missing from a list row template
REQ-06A required element is placed but a state a user can reach hides it: a settings combination, a variant, one side of a collapsible region, or the visible Join context
LIM-01More than 2,000 nodes in one layout file
LIM-02Nodes nested deeper than 24 levels
LIM-03A text node longer than 120 characters, or a column label longer than 24
LIM-04More than four variants in one file
LIM-05More than 200 different theme classes in one file
SET-01The settings schema is malformed: not an object, a version other than 2, no fields list, a field that is not an object or is missing its id, type or label, a label that is empty or over 40 characters, or an unknown field type
SET-02A setting id does not match [a-z][a-zA-Z0-9]{0,31}, or is used twice
SET-03A number field's bounds are wrong: a bound or default that is not a finite number, a minimum above the maximum, a default outside the bounds, or a step that is not a positive number
SET-04A boolean, choice or colour field is wrong: a default that is not a boolean, fewer than two options, a missing, duplicated or malformed option value, an option label that is empty or over 40 characters, a default that matches no option, or a colour default that is not #rrggbb
SET-05The fields expand to more than 64 combinations
CSS-01A refused selector or declaration: a type selector, an id selector, the universal selector, a class that is not your own t- name, an attribute, pseudo-class or pseudo-element that is not allowed, a pseudo-class right after a space, an :nth-child() argument that is not An+B, or !important
CSS-03A malformed theme class name — in particular one that is not t- followed by lowercase letters, digits and hyphens
CSS-04z-index and --z-* are refused
CSS-05A refused value: one of the banned constructs, or content with anything other than ""
CSS-06An at-rule other than @media, @keyframes or @font-face, or a media query feature that is not allowed
CSS-07A refused URL: one that uses a scheme, a scheme-relative one, one with .. in its path, an unreadable one, or a @font-face source that is not under fonts/
CSS-08styles.css is larger than 256 KB

Icons

An image node may name one of these icons instead of a file: { "type": "image", "icon": "globe" }. They are the only names the launcher accepts.

alertTriangle appWindow arrowRight ban check checkCircle chevronDown chevronLeft chevronRight chevronsLeft chevronsRight clock copy download externalLink fileArchive fileOutput filter folder folderOpen gamepad globe inbox info listTree loader minus moon moreHorizontal package palette play plus refresh rotateCcw search settings square star sun thumbsUp trash upload users x