Theming#
Every OSPREY browser interface — the terminal and all of its panels — draws its colors and fonts from one shared design system. Pick a theme once and everything matches automatically, in light or dark. You can also design your own.
Choosing a theme#
Themes come in families. OSPREY ships four:
main — the default look, in light and dark.
desy — the DESY corporate palette, in light and dark.
high-contrast — a stronger-contrast family for accessibility, also in light and dark.
retro — a navy-and-teal family, in light and dark, for teams who prefer that look.
In the terminal, click ☰ More at the bottom of the sidebar. It holds the light/dark switch and the theme family picker, as pictured below. Every panel opened as its own page (the Logbook, the workspace, Channel Finder, the the knowledge panel) has a sliders button in its own header. It opens the display menu, which has the same display controls.
A pick made on any of those pages is remembered by your browser and becomes your preference for every OSPREY page served from the same address — set a theme in the Logbook and the terminal comes up in it the next time you load it. Until you pick Light or Dark, pages follow your operating system’s light/dark preference.
Panels shown inside the terminal are a separate case. The terminal hands each one its theme in the page address, and an address outranks the remembered preference, so an embedded panel always matches the terminal around it. The JUPYTER panel matches the light or dark side only, in JupyterLab’s own JupyterLab Dark and JupyterLab Light themes (How the tab is themed).
The terminal’s ☰ More menu, light and dark. Captured with OSPREY v2026.9.0b3.post6981+gce771a4c5.d20261111.
To set the theme a deployment starts in, use web.theme in config.yml:
web:
theme: main # a family, or a specific theme like high-contrast-light
Name a family to start visitors in that family (light or dark then follows their operating-system preference), or name a specific theme to pin an exact look — including whether the deployment starts light or dark. Whatever you pick in the browser always wins over this and sticks across reloads.
Note
web.theme (the browser interfaces) is separate from cli.theme (the
colors of OSPREY’s plain terminal output). They never affect each other.
Giving each user their own default#
In a multi-user deployment every user gets their own terminal, but they all run
the same image — so they all read the same web.theme. To start a particular
user somewhere else, add theme to their entry in the user list. The snippet
shows only the keys this section is about; the deployment also carries
default_tier and each user’s tier from the multi-user page (see the
worked example in Pull the terminal images from a registry). Merge its keys into the
modules.web_terminals: entry under config: in profile.yml; a second
copy of that key silently replaces the first.
config:
modules.web_terminals:
users:
- alice
- name: bob
index: 1
theme: desy-light
The value takes the same two forms as web.theme: a family, or a specific
theme to also pin light or dark. It overrides web.theme for that user’s
terminal only, and their own pick in the terminal’s ☰ More menu or a panel’s
display menu still wins over it.
The landing page that lists everyone’s terminals uses the deployment-wide
web.theme, and so does the sign-in page a user reaches from it, which also
shows the facility’s name above the OSPREY wordmark. That name is the one the
build’s facility identity records, or the project name when it records none.
Both are shown before anyone has said who they are, so there is no personal setting
to apply yet.
Propose a theme#
Have a color of your own in mind? Run:
osprey theme-lab
That opens the Theme Lab in your browser. Pick an accent color and the dark and light mock-ups of the terminal re-skin as you go, while the contrast badges tell you at a glance whether text stays readable against it — the same check every shipped theme has to pass. When you are happy, give the theme a name, copy the export block, and paste it into a GitHub issue. The lab doesn’t create the theme itself; the export spells out exactly what needs to change to make it real.
A theme has two accents: the main one, and a second used for highlights and warnings. Switch between them with the Accent / Second accent buttons above the color wheel — one set of controls edits whichever is selected, and both previews update either way. The second accent gets a contrast badge of its own, because the build holds it to the stricter body-text standard: it is used for readable text, where the main accent mostly is not. If that badge goes red, drag the lightness slider for the mode it failed in until it clears.
Going deeper — the design system
The colors above aren’t hand-written CSS scattered across each interface — they come from one small, machine-checked token system. You only need this if you are adding a theme or a new interface; the steps below and the design system’s source are the real reference. The tabs are the rough idea.
A theme is a single JSON document listing named colors — backgrounds, text, accents, status colors, the terminal palette. Every theme defines the same set of names, so they are interchangeable, and a build step checks each one’s contrast automatically — more strictly for the high-contrast family. A theme that reads fine but fails the check does not ship until its colors are nudged; the gate is never loosened.
Copy an existing theme’s JSON as a starting point, adjust its color values (and its name/family label), then run the generator:
python -m osprey.interfaces.design_system.generator.build
It validates the whole set and rewrites the compiled CSS/JS. If a color is missing, a name doesn’t match its siblings, or a contrast gate fails, the build stops and tells you exactly where. Fix and re-run until clean, then commit the regenerated files alongside your theme.
Themes are authored as JSON and compiled into the CSS and JavaScript every interface loads. The compiled files are checked in, not built on deploy, so you regenerate and commit them whenever you change a color. A new interface opts in by loading those files and following the same theme boot every OSPREY page uses.
See also
- Panels
Panels use these same tokens, so they theme themselves for free.