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.
| Field | Type | Required | Rule |
|---|---|---|---|
schemaVersion | number | No | Must be 2. Left out, it is 2. |
themeApi | string | No | Must start with "2.". Left out, it is "2.0". |
id | string | Yes | [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. |
name | string | Yes | 1 to 48 characters. |
author | string | Yes | 1 to 48 characters. |
version | string | Yes | Semver, all three parts: 1.0.0. |
minimumLauncherVersion | string | Yes | Semver. Import is refused when it is newer than the launcher doing the import. |
description | string | No | Up to 280 characters. |
capabilities | string[] | No | Names from Capabilities. Each one must match the files you ship. |
previews | object[] | No | Up 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. |
license | string or null | No | Free text. Not checked. |
homepage | string or null | No | An https: URL with a host. |
tags | string[] | No | Up to 8, each up to 24 characters. |
preview | string | No | The older single-preview field, from the v1 format. Used only when previews is empty. |
tier | string | No | Also 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.
{
"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.
| Capability | Covers |
|---|---|
tokens | tokens.json |
css | styles.css |
fonts | Everything under fonts/ |
images | Everything under images/ |
layout | Everything under layout/ |
settings | settings.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:
| Label | When |
|---|---|
| Custom layout | layout is declared. |
| Styled | No layout, but css or fonts is declared. |
| Colours | Anything 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.
<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.
| Where | Allowed extensions |
|---|---|
| Anywhere in the package | json, 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.
| Limit | Value |
|---|---|
| Files per package | 64 |
| Package size, uncompressed | 8 MB |
| Path depth | 3 segments |
| Image size | 4096 × 4096 |
styles.css | 256 KB |
| Nodes per layout file | 2,000 |
| Node depth | 24 |
| Text node | 120 characters |
| Free label | 40 characters |
| Column label | 24 characters |
| Variants per file | 4 |
| Settings combinations | 64 |
| Previews | 5 |
| Preview caption | 80 characters |
| Theme classes per file | 200 |
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.
| Key | Type | Default | What it does |
|---|---|---|---|
schemaVersion | number | 2 | Must be 2. |
colors.dark, colors.light | object | Neutral's palette | The twelve colours, one object per scheme. |
bloom | number | 0.9 | How far the glow spreads. |
glow | string | selected | always, selected or never. Governs the launcher's own glowing surfaces; the glow's look is shadow.glow. |
scales | object | Neutral's steps | Replaces one step of a named scale. |
roles | object | Neutral's values | Points a role at a step name or a literal value. |
Colours
Twelve per scheme, as #rrggbb strings.
| Token | Dark | Light | Used for |
|---|---|---|---|
| Surfaces | |||
bg | #0d0f13 | #f3f4f6 | The window background. |
surface | #12151b | #ffffff | Panels and cards. |
surface2 | #1a1e26 | #e9ebef | Raised surfaces: inputs, headers, popups. |
border | #262b34 | #d2d6dc | Lines and dividers. |
| Text | |||
text | #e7ebf0 | #181b20 | Primary text and headings. |
muted | #7a8494 | #5d6570 | Captions, labels and hints. |
muted2 | #98a2b2 | #8a919d | Body text. |
| Accents | |||
accent | #8fa3bd | #3e5f7d | The primary action colour. |
accent2 | #b0976a | #8a6d34 | The secondary accent. |
| Semantic | |||
success | #4d9a75 | #287a4f | Ready and online states. |
warn | #c19a55 | #9a7b3a | Warnings. |
danger | #b3564d | #a94a42 | Errors 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.
| Scale | Steps |
|---|---|
radius | none 0, xs 2px, sm 4px, md 6px, lg 8px, full 9999px |
space | 0 to 48 in 2px steps, named by their pixel value: space.6 is 6px |
type.size | 3xs 7px, 2xs 8px, xs 9px, sm 10px, md 11px, lg 12px, xl 13px, 2xl 14px, 3xl 22px |
type.weight | normal 400, medium 500, semibold 600, bold 700, extrabold 800 |
type.tracking | none 0, tight -0.025em, wide 0.025em, wider 0.05em, widest 0.1em |
type.leading | none 1, tight 1.25, snug 1.375, normal 1.5, relaxed 1.625 |
type.family | ui the bundled Inter stack, data the bundled JetBrains Mono stack |
border | none 0, hairline 1px, thick 2px |
shadow | none, 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.duration | fast 150ms, normal 200ms, slow 300ms |
motion.easing | standard 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
| Role | Default | CSS variable |
|---|---|---|
radius.window | lg (8px) | --t-radius-window |
radius.panel | 9px | --t-radius-panel |
radius.card | lg (8px) | --t-radius-card |
radius.modal | 10px | --t-radius-modal |
radius.modalLarge | 12px | --t-radius-modalLarge |
radius.popup | 7px | --t-radius-popup |
radius.popupItem | 5px | --t-radius-popupItem |
radius.row | lg (8px) | --t-radius-row |
radius.control | md (6px) | --t-radius-control |
radius.controlSmall | sm (4px) | --t-radius-controlSmall |
radius.controlCompact | 5px | --t-radius-controlCompact |
radius.input | md (6px) | --t-radius-input |
radius.chip | sm (4px) | --t-radius-chip |
radius.badge | 3px | --t-radius-badge |
radius.thumb | 7px | --t-radius-thumb |
radius.track | xs (2px) | --t-radius-track |
radius.pill | full (9999px) | --t-radius-pill |
radius.sidebarItem | 7px | --t-radius-sidebarItem |
radius.confirm | lg (8px) | --t-radius-confirm |
radius.readinessRow | 5px | --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.
| Role | Default | CSS variable |
|---|---|---|
space.windowPad | 0 | --t-space-windowPad |
space.panelPad | 16 | --t-space-panelPad |
space.modalPad | 14 | --t-space-modalPad |
space.popupPad | 4 | --t-space-popupPad |
space.rowX | 12 | --t-space-rowX |
space.rowY | 8 | --t-space-rowY |
space.controlX | 12 | --t-space-controlX |
space.controlY | 6 | --t-space-controlY |
space.chipX | 4 | --t-space-chipX |
space.chipY | 1px | --t-space-chipY |
space.stackGap | 12 | --t-space-stackGap |
space.inlineGap | 6 | --t-space-inlineGap |
space.sectionGap | 14 | --t-space-sectionGap |
space.listGap | 6 | --t-space-listGap |
space.controlCompactX | 8 | --t-space-controlCompactX |
space.controlCompactY | 5px | --t-space-controlCompactY |
space.controlSmallX | 10 | --t-space-controlSmallX |
space.controlSmallY | 2 | --t-space-controlSmallY |
space.sidebarPad | 8 | --t-space-sidebarPad |
space.sidebarSettingsPad | 10 | --t-space-sidebarSettingsPad |
space.sidebarLogoY | 14 | --t-space-sidebarLogoY |
space.sidebarListGap | 3px | --t-space-sidebarListGap |
space.sidebarItemGap | 10 | --t-space-sidebarItemGap |
space.inlineGapWide | 8 | --t-space-inlineGapWide |
space.inlineGapSmall | 4 | --t-space-inlineGapSmall |
space.popupFilterPad | 5px | --t-space-popupFilterPad |
space.popupOffset | 5px | --t-space-popupOffset |
space.popupClearGap | 7px | --t-space-popupClearGap |
space.separatorX | 2 | --t-space-separatorX |
space.separatorY | 4 | --t-space-separatorY |
space.footerX | 14 | --t-space-footerX |
space.footerY | 7px | --t-space-footerY |
space.footerGap | 14 | --t-space-footerGap |
space.stateChipY | 3px | --t-space-stateChipY |
space.windowControlWidth | 40 | --t-space-windowControlWidth |
space.windowControlHeight | 28 | --t-space-windowControlHeight |
space.sidebarWidth | 176px | --t-space-sidebarWidth |
space.sidebarCollapsedWidth | 52px | --t-space-sidebarCollapsedWidth |
space.sidebarToggleOffset | 96px | --t-space-sidebarToggleOffset |
space.sidebarToggleHeight | 46 | --t-space-sidebarToggleHeight |
space.searchMinWidth | 140px | --t-space-searchMinWidth |
space.popupMinWidth | 190px | --t-space-popupMinWidth |
space.popupMaxHeight | 320px | --t-space-popupMaxHeight |
space.scaleTrackWidth | 120px | --t-space-scaleTrackWidth |
space.scaleKnobSize | 7px | --t-space-scaleKnobSize |
space.sliderHeight | 3px | --t-space-sliderHeight |
space.stateDotSize | 5px | --t-space-stateDotSize |
space.pingTrackWidth | 56px | --t-space-pingTrackWidth |
space.dataWidth | 36 | --t-space-dataWidth |
space.iconTiny | 11px | --t-space-iconTiny |
space.iconSmall | 12 | --t-space-iconSmall |
space.iconChevron | 13px | --t-space-iconChevron |
space.iconMedium | 14 | --t-space-iconMedium |
space.iconLarge | 18 | --t-space-iconLarge |
space.iconBox | 22 | --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.
| Role | Family | Size | Weight | Tracking | Leading |
|---|---|---|---|---|---|
display | data | 3xl (22px) | extrabold (800) | none (0) | none (1) |
heading | ui | 2xl (14px) | bold (700) | none (0) | snug (1.375) |
subheading | ui | lg (12px) | semibold (600) | none (0) | normal (1.5) |
body | ui | md (11px) | normal (400) | none (0) | normal (1.5) |
label | ui | sm (10px) | semibold (600) | none (0) | normal (1.5) |
caption | ui | xs (9px) | normal (400) | none (0) | 1.4 |
micro | ui | 2xs (8px) | normal (400) | none (0) | normal (1.5) |
button | ui | sm (10px) | bold (700) | wider (0.05em) | normal (1.5) |
chip | ui | 2xs (8px) | bold (700) | 0.04em | 1.3 |
data | data | sm (10px) | normal (400) | none (0) | normal (1.5) |
rowName | ui | lg (12px) | semibold (600) | none (0) | normal (1.5) |
rowMeta | ui | xs (9px) | normal (400) | none (0) | normal (1.5) |
statValue | data | xl (13px) | bold (700) | none (0) | none (1) |
statCaption | ui | 3xs (7px) | bold (700) | 0.07em | normal (1.5) |
brand | ui | xl (13px) | bold (700) | 0.06em | normal (1.5) |
compactMicro | ui | 8.5px | normal (400) | none (0) | normal (1.5) |
compactCaption | ui | 9.5px | normal (400) | none (0) | normal (1.5) |
compactBody | ui | 10.5px | normal (400) | none (0) | normal (1.5) |
compactHeading | ui | 13.5px | normal (400) | none (0) | normal (1.5) |
compactSubheading | ui | 11.5px | normal (400) | none (0) | normal (1.5) |
compactTitle | ui | 12.5px | normal (400) | none (0) | normal (1.5) |
Colour roles
| Role | Default | CSS 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.focusRing | var(--accent-line) | --t-color-focusRing |
color.scrim | rgba(5,8,13,0.7) | --t-color-scrim |
color.scrimBlocking | rgba(0,0,0,0.9) | --t-color-scrimBlocking |
color.rowHover | var(--row-hover) | --t-color-rowHover |
color.rowSelected | var(--row-selected) | --t-color-rowSelected |
Border roles
| Role | Default | CSS variable |
|---|---|---|
border.hairline | hairline (1px) | --t-border-hairline |
border.control | hairline (1px) | --t-border-control |
border.focus | thick (2px) | --t-border-focus |
Shadow roles
| Role | Default | CSS variable |
|---|---|---|
shadow.panel | none | --t-shadow-panel |
shadow.modal | lg (0 12px 40px rgba(0,0,0,0.5)) | --t-shadow-modal |
shadow.popup | sm (0 8px 24px rgba(0,0,0,0.4)) | --t-shadow-popup |
shadow.popupFilter | md (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.glow | glow (the launcher's glow) | --t-shadow-glow |
shadow.confirm | 0 25px 50px -12px rgb(0 0 0 / 0.25) | --t-shadow-confirm |
shadow.update | 0 25px 50px -12px rgb(0 0 0 / 0.5) | --t-shadow-update |
shadow.inspector | 0 8px 24px rgba(0,0,0,0.5) | --t-shadow-inspector |
shadow.statusDot | 0 0 4px currentColor | --t-shadow-statusDot |
shadow.stateWarning | 0 0 4px var(--warn) | --t-shadow-stateWarning |
shadow.readinessWarning | 0 0 5px rgba(193,154,85,0.6) | --t-shadow-readinessWarning |
shadow.readinessSuccess | 0 0 5px rgba(77,154,117,0.6) | --t-shadow-readinessSuccess |
Motion roles
| Role | Field | Default | CSS variable |
|---|---|---|---|
motion.hover | duration | fast (150ms) | --t-motion-hover-duration |
motion.hover | easing | standard | --t-motion-hover-easing |
motion.expand | duration | normal (200ms) | --t-motion-expand-duration |
motion.expand | easing | standard | --t-motion-expand-easing |
motion.overlay | duration | 0ms | --t-motion-overlay-duration |
motion.overlay | easing | standard | --t-motion-overlay-easing |
{
"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.
{
"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.
| Type | Its own props | Values |
|---|---|---|
stack | direction, align, justify, wrap, gap, tag | direction 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 |
grid | columns, rows, areas, gap, columnGap, rowGap, alignItems, justifyItems, tag | tag 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 |
box | None | A plain wrapper with no layout of its own |
scroll | axis | y or x, default y. The only way to get a scrolling area |
tabs | tabs, orientation | Each 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 |
accordion | sections, mode, initial | Each section is { "id": "game", "header": <node>, "body": <node> }; mode is single or multiple; initial is none or first. Both are required |
Leaves
| Leaf | Shape |
|---|---|
| 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
| Prop | Values |
|---|---|
id | A region id, r-[a-z0-9-]+, unique within the theme. Only needed when something refers to the node |
class | One or more class names, each matching t-[a-z0-9-]+ |
padding, paddingX, paddingY, paddingTop, paddingRight, paddingBottom, paddingLeft, gap | A 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, basis | Flex behaviour inside a stack |
area | A 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 |
hidden | true, or { "setting": "compactRows", "equals": true }, or "not" in place of "equals". The setting must be a boolean or choice field |
landmark | navigation, 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 |
glow | Element nodes only: always, selected or never. selected glows while the element's state is current, selected, on, active, checked or open |
context | selection, 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 |
column | A 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.
| Key | Type | Default | Rule |
|---|---|---|---|
schemaVersion | number | — | Must be 2. |
columns | array | — | Column definitions. Optional |
row | node | — | The row template. Its root node is the row; the launcher adds no wrapper |
empty | node | — | Replaces the launcher's wording when the list is empty |
header | boolean | true | false hides the header |
overflowX | string | clip | clip 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 |
estimatedRowHeight | string | Per list | A pixel length. It seeds the measurement; real heights are measured |
| Column field | Rule |
|---|---|
id | [a-z0-9-]+, unique in the file |
label | Up to 24 characters. Only on a column with no sort, which takes the launcher's wording instead |
width | A length, <n>fr or auto. Required |
minWidth, maxWidth | Lengths |
align | start, center or end |
sort | A sort key from that list's set. An unknown key is an error |
resizable | Boolean, default true. Only a column with a pixel width resizes; fr and auto columns never do |
headerElement | An 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.
| List | Sort keys |
|---|---|
list.servers | players, ping, mods, name, map, lastPlayed |
list.mods | status, name, size, updated, subscribed |
| List | Default row height | Header |
|---|---|---|
list.servers | 56px | Shown |
list.mods | 54px | Shown |
list.modFilterResults | 44px | Shown |
list.serverMods | 32px | Hidden |
list.modServers | 32px | Hidden |
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.
{
"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
| Form | Example |
|---|---|
| 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 |
| Combinators | Descendant, >, +, ~ |
| 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.
[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.
[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.
| Type | Needs | Rule |
|---|---|---|
number | min, max, default | All 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 |
boolean | default | true or false |
choice | options, default | At 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 |
color | default | #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 reaches | How |
|---|---|
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 |
| CSS | Only as --setting-<id> on the window root |
| Layout structure | A 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.
{
"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.
| Code | What it means |
|---|---|
LAY-01 | The 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-02 | A node's type is not a container or leaf the launcher knows |
LAY-03 | A 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-04 | A 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-05 | Spacing is wrong: a margin was used, or a padding or gap is not a space token or space role |
LAY-06 | Positioning is wrong: position is not an object, the anchor is unknown, or an offset is not a length or space token |
LAY-07 | A region id does not match r-[a-z0-9-]+ |
LAY-08 | A region id is used twice, inside one root or in another file |
LAY-09 | Something refers to a region id that does not exist |
LAY-10 | The 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-11 | A tabs node is wrong: no tabs, a missing, invalid or duplicated tab id, or a tab without its label or content node |
LAY-12 | An 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-01 | An element, surface or header element the launcher does not know |
ELE-02 | That element or surface cannot be placed here: the wrong file, the wrong subject, or a list header it is not allowed in |
ELE-03 | A context is unknown, nested, or unavailable in that file; or the element needs a subject the context does not provide |
ELE-04 | An element is placed more than once where only one is allowed |
ELE-05 | An option the element does not have |
ELE-06 | An option value is invalid, options is not an object, or a free label is not plain text |
ELE-07 | A free label was given for an element that takes none |
ELE-08 | A free label is longer than 40 characters |
LST-01 | A list file that is not one of the known lists, or a reference to a list that does not exist |
LST-02 | Two columns share an id |
LST-03 | A column width is missing, or is not a length, an fr value or auto |
LST-04 | A column sort key that list does not support |
LST-05 | A column property outside a direct child of a row template that declares columns |
LST-06 | A list element placed inside a scrolling container |
REQ-01 | A required element is missing from a view |
REQ-02 | A required element is missing from Settings |
REQ-03 | A required element is missing from a modal |
REQ-04 | A required element is missing from a popup |
REQ-05 | A required element is missing from a list row template |
REQ-06 | A 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-01 | More than 2,000 nodes in one layout file |
LIM-02 | Nodes nested deeper than 24 levels |
LIM-03 | A text node longer than 120 characters, or a column label longer than 24 |
LIM-04 | More than four variants in one file |
LIM-05 | More than 200 different theme classes in one file |
SET-01 | The 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-02 | A setting id does not match [a-z][a-zA-Z0-9]{0,31}, or is used twice |
SET-03 | A 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-04 | A 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-05 | The fields expand to more than 64 combinations |
CSS-01 | A 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-03 | A malformed theme class name — in particular one that is not t- followed by lowercase letters, digits and hyphens |
CSS-04 | z-index and --z-* are refused |
CSS-05 | A refused value: one of the banned constructs, or content with anything other than "" |
CSS-06 | An at-rule other than @media, @keyframes or @font-face, or a media query feature that is not allowed |
CSS-07 | A 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-08 | styles.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