Themes

Themes let you change the structural appearance of your forum — layout, typography, spacing, component shape, custom fonts, and anything else CSS can express. They are installed from GitHub releases and managed from Admin → Themes.

How themes work

A theme is a GitHub repository containing a theme.json manifest, a theme.css stylesheet, and an optional theme.js script. When a theme is activated for a mode, Nexus injects theme.css as a stylesheet and, if present, theme.js as a script tag into every page.

Colors are not controlled by themes. The forum’s accent color and surface tints are always set by the admin from Admin → Appearance and apply on top of everything else. This means a theme looks correct regardless of which color scheme the admin has chosen — themes and colors are independent.

Themes are assigned per mode — you can set one theme for dark mode and a different one for light mode, or assign the same theme to both.

What themes can change

Themes work through theme.css — a stylesheet injected into every page. There are no restrictions on what it can contain:

Layout — sidebar width, topbar height, feed column width, right panel position
Typography — custom fonts via @import, font sizes, line heights, letter spacing
Spacing and shape — border radius, padding, card sizes
Component styling — post cards, reply threads, composer, navigation, modals
Animations and transitions — hover effects, page transitions, focus states
Mode-specific rules — using [data-theme="dark"] and [data-theme="light"] selectors
CSS variable overrides — override any of Nexus’s design tokens via the variables and modes manifest keys

Themes can also include a theme.js file for behavioural customisation — dynamic effects, font injection, DOM manipulation, and anything else that requires JavaScript. See the Theme Development Guide for details.

What themes cannot do:

Override the admin’s accent color or surface tints — those always apply last
Run server-side code

CSS variable overrides

In addition to theme.css, themes can declare CSS variable overrides directly in theme.json. These take effect without any CSS required and are validated at install time — unknown variable names cause the install to fail.

{
  "variables": {
    "--av-radius": "4px",
    "--fs-body": "14px"
  },
  "modes": {
    "dark": {
      "variables": {
        "--bg": "#0d0d0d"
      }
    },
    "light": {
      "variables": {
        "--bg": "#fafafa"
      }
    }
  }
}

Key	When applied
`variables`	Applied in both dark and light mode
`modes.dark.variables`	Applied in dark mode only
`modes.light.variables`	Applied in light mode only

Only the following variable names are accepted. Any other key causes the install to fail with a validation error:

--bg  --s1  --s2  --s3
--b1  --b2  --b3
--t1  --t2  --t3  --t4  --t5
--ac  --ac-on  --ac-bg  --ac-border  --ac-text
--green  --red  --amber  --blue  --pink
--fs-ui  --fs-body  --fs-title  --fs-feed-title  --fs-content  --fs-code
--av-radius

Targeting a specific theme in CSS

Nexus sets data-theme-slug on <html> to the active theme’s slug. Use this to scope rules to your theme only, preventing conflicts when multiple themes are installed:

[data-theme-slug="my-theme"] .post-card {
  border-left: 3px solid var(--ac);
}

/* Combine with mode targeting */
[data-theme-slug="my-theme"][data-theme="light"] .sidebar-left {
  background: var(--s2);
}

The theme store

Admin → Themes shows the theme store — themes listed in the shared Nexus registry. The store is fetched live from GitHub each time you open the panel.

Store entries show a banner image, the theme’s logo, name, author, version, and description. A green Installed badge appears on themes you’ve already installed.

Use the search field to filter by name or description. If categories are defined in the registry, category filter pills appear above the grid.

Installing a theme

From the store

Click Install on any theme card. Nexus downloads the latest release from GitHub, validates theme.json, copies theme.css and theme.js (if present), and adds the theme to your installed list.

From a URL

Click the Install from URL tab, paste a GitHub repository URL, and click Install:

https://github.com/someone/my-nexus-theme

Activating a theme

After installation, the theme card shows Dark and Light mode buttons. Click either to assign the theme to that mode. Clicking an already-active button deactivates the theme for that mode, returning to the default Nexus appearance.

Only one theme can be active per mode at a time. Changes take effect immediately.

Theme settings

Some themes declare configurable settings — font choices, spacing options, layout variants. When a theme has settings, they appear on the theme card below the mode buttons. Save after changing any settings.

Updating a theme

When a newer release exists on GitHub, an Update button appears on the theme card. The theme’s mode assignments are preserved after an update.

Uninstalling a theme

Click Uninstall on the theme card. If the theme was active for either mode, the forum reverts to the default appearance for that mode immediately.

Tarball cache

Like extensions, themes cache their downloaded release tarballs. After the first install, the theme loads from the local cache on server restarts — no GitHub request needed. The cache is cleared on uninstall.