Skip to content

UI Themes

A UI theme is a complete look for the interface: neutral surfaces, shapes, type and density, plus its own markup in a few named places. Each account picks one theme. The theme is independent of the six color schemes and of light or dark mode, which keep working with every theme. This page describes how themes are built and how a new one is added.

Overview

Piece Where Purpose
Registry src/config/ui_themes.py Theme ids, availability, slot names, locale keys, preview and stylesheet paths
Setting User.ui_theme (VARCHAR(32), null = default) The account's theme; the column is added at startup in src/init_db.py
Save endpoint POST /api/user/preferences with ui_theme An available theme id or null is saved; anything else is answered with 400 invalid_ui_theme
Account copy templates/includes/theme_account.html window.speakrThemeDefaults for a browser with nothing saved, and a copy of the account's theme in localStorage.uiTheme, made before the theme is read; changes are saved with window.speakrSaveTheme('uiTheme')
New accounts new_user_theme(), new_user_color_scheme(), apply_new_user_defaults(user) in src/config/ui_themes.py The look written on every account when it is created, from the System Settings default_ui_theme and default_color_scheme (.env: DEFAULT_UI_THEME, DEFAULT_COLOR_SCHEME; defaults cards and emerald)
Pre-paint script templates/includes/ui_theme.html <html data-ui-theme="<id>"> and the theme stylesheet, set before the first paint; window.speakrApplyUiTheme(id) for switching
Theme stylesheet static/css/themes/<id>.css The theme's CSS, scoped under html[data-ui-theme="<id>"]; none for the default
Slots templates/themes/slot.html, templates/themes/<id>/<slot>.html Markup a theme replaces
Reactive value uiTheme in the main app (static/js/modules/composables/ui-theme.js), in the Inquire app (templates/inquire.html) and on the public share page (static/js/share-page.js) The value the slot branches switch on, without a reload
Picker templates/includes/ui_theme_picker.html Theme cards in Account > Preferences > Appearance and in the color scheme dialogs
Previews static/img/themes/<id>.webp Card images
Guard test tests/test_ui_theme_slots.py Check that overrides keep every behaviour of the default markup

The registered ids are default (the standard look), classic, workspace, focus, desk and cards. All six are available. A theme that is registered but not available has reserved locale keys and a reserved folder name, and it is neither offered in the picker nor accepted by the endpoint.

The picker appears only while two or more themes are available, so with the default alone no page shows it.

How a theme is applied

  1. In includes/theme_account.html (first in <head> on every page), window.speakrThemeDefaults is set to the color scheme and theme used when localStorage has none: the defaults for new accounts on a signed-out page, and blue and default for a signed-in account. For a signed-in account, a saved color scheme, theme or light or dark mode is then written into localStorage. Without a saved value, the browser keeps its own choice, for example one made before themes were saved with the account. A browser with no choice stored shows blue and default, not the defaults for new accounts. Signed-out pages write nothing to localStorage, and applying a stored or default color scheme stores nothing either: only a theme or color scheme that someone picks is stored. A value in localStorage is therefore always a real choice, and the look of the sign-in page never stays after sign-in.
  2. includes/ui_theme.html is included right after the compiled tailwind.css link on every page with a <head> (the main app, Inquire, account, admin, group management, shared recordings and the sign-in pages). In its script, localStorage.uiTheme is read, an id that is not in the list of available themes is replaced by default, data-ui-theme is set on <html>, and for a theme with a stylesheet <link id="speakr-ui-theme-css" rel="stylesheet" blocking="render"> is appended to <head>, after every other stylesheet. All of this happens before the body is parsed, so the first paint already has the theme.
  3. In each slot, the active theme's partial is rendered through a v-if chain on the reactive uiTheme.

Switching is done with window.speakrApplyUiTheme(id). With that call, the attribute is updated, the stylesheet link is replaced or removed, the aria-pressed state of the theme cards outside Vue is updated, localStorage.uiTheme is written, the choice is saved to the account, and the window event speakr:ui-theme is dispatched with detail.id. On that event uiTheme is updated in the Vue apps, so the slot branches switch without a reload. Other tabs of the same browser are switched through the storage event, without saving again.

Signed-out pages (sign-in, registration, password reset, public share pages) have no account value. On them, the theme and color scheme saved in that browser are shown, or, with nothing saved, the defaults for new accounts. Nothing is written to localStorage on a signed-out page until the visitor changes the theme.

apply_new_user_defaults(user) is called wherever an account is created: registration (src/api/auth.py), POST /admin/users (src/api/admin.py), the first SSO sign-in (src/auth/sso.py), and scripts/create_admin.py and scripts/docker_create_admin.py. The audio player position for new accounts (default_audio_player_position) is written on the account in the same call. apply_new_user_theme is the earlier name of the same function. In tests/test_new_user_theme.py, every file in src/ and scripts/ that constructs a User is checked for the call. Accounts are never updated afterwards, so a NULL ui_theme or theme_color_scheme still means the browser's own choice, or default and blue without one.

Colors: the contract between themes and color schemes

The color scheme and light/dark mode are classes on <html>: dark, and theme-light-<scheme> or theme-dark-<scheme> for every scheme except blue (static/css/styles.css). A theme's rules are scoped under html[data-ui-theme="<id>"], which is more specific than those classes, so a variable set by the theme on html wins over the scheme's value. That is why the variables are split in two groups.

From the color scheme (a theme must not set these):

Variable Use
--bg-accent, --bg-accent-hover Tinted accent surfaces: the selected row, active filters
--bg-button, --bg-button-hover Filled primary controls
--text-accent Accent text and icons
--border-accent Accent borders
--border-focus, --ring-focus Focus outline and ring

Any other accent shade is derived from these, for example color-mix(in srgb, var(--bg-button) 12%, transparent), so it follows every scheme.

From the theme (a theme must define these for light and for dark):

Variable Use
--bg-primary, --bg-secondary, --bg-tertiary, --bg-input, --bg-audio-player Page, panels, insets, inputs
--text-primary, --text-secondary, --text-muted, --text-light Text levels
--border-primary, --border-secondary Dividers and control borders
--scrollbar-track, --scrollbar-thumb, --scrollbar-thumb-hover Scrollbars

Light values go under html[data-ui-theme="<id>"], dark values under html[data-ui-theme="<id>"].dark. The schemes also tint the neutrals slightly. When a theme sets the neutral variables, that tint is replaced by the theme's neutrals, and the accent still follows the scheme.

Optional for a theme: the shape and type tokens of static/css/primitives.css (--radius-*, --shadow-*, --sp-*, --fs-*, --lh-*) and the status colors (--bg-danger*, --text-danger*, --tint-* and the other semantic colors). The status colors keep their meaning in every theme; adjust their tone for contrast only.

A theme can define its own tokens on top of these (for example --surface or --radius-card), as long as they are declared inside its scope.

Slots

A slot is a named place in the markup that a theme can replace. The default markup of each slot lives in templates/themes/default/<slot>.html and was moved there unchanged from the templates below. The place in the page is a line such as:

{% with ui_slot = 'sidebar-row' %}{% include 'themes/slot.html' %}{% endwith %}

With no available theme overriding a slot, the output of themes/slot.html is the default partial alone, so the page is identical to the page without slots. When available themes override it, the output is:

<template v-if="uiTheme === 'classic'">...templates/themes/classic/sidebar-row.html...</template>
<template v-else-if="uiTheme === 'cards'">...templates/themes/cards/sidebar-row.html...</template>
<template v-else>...templates/themes/default/sidebar-row.html...</template>

Only one branch is rendered at a time, so an id or a ref that appears in two branches does not clash. A theme folder holds only the slots it overrides; every other slot uses the default partial. An override may include the default partial ({% include 'themes/default/<slot>.html' %}) and add markup around it.

Slot Template it came from Why it is a slot
sidebar-nav components/sidebar.html, sidebar header The folder selector, New and Select buttons, filter panel, sort and view toggles. This area was rebuilt in every design (a navigation rail, a tree with counts, a column header, pill toggles).
sidebar-row components/sidebar.html, row of the recordings list One recording in the list. Its structure changed in four designs: a time column, a single-line row, a table row with columns, a card with an avatar footer.
header-actions components/header.html The recording's action buttons in the top header on desktop. In one design most of them were moved into an overflow menu, in another into a toolbar above the recording.
detail-meta components/detail-view.html The folder, tag and metadata strip above a recording on desktop. The chips carry their color in inline styles, which were replaced in three designs; in one design the recording toolbar is added here.
transcript-turn components/detail/desktop-transcription-panel.html One speaker turn of the simple transcript on desktop. A timestamp and speaker column or an avatar is added in two designs. Also rendered, read-only, by the public share page (see below).
transcript-turn-mobile components/detail/mobile-transcript-panel.html The same on phones, inside the shared phone layout (see below).
inquire-filters inquire.html, the filter column The Inquire page's left column. Its groups were restyled in every design (disclosures, compact rows with counts, chips, the sidebar's navigation style).
status-area index.html, after the upload dialog The parts of the processing queue that lie over the page: the panel under the top bar while the recording list is collapsed, and the sheet of the phone layout. In one design a status bar is added, with the indicator of the queue in it. The markup of the indicator, the panel and the rows is shared (templates/components/queue/_queue.html) and is not part of the slot.

The raised layer: toasts and the processing queue

Toasts and the processing queue have one structure and one stylesheet for every theme (static/css/styles.css under "Toasts", static/css/queue.css). Their surface is not a theme surface. It is defined once, as tokens on :root and .dark in styles.css, and mixed from the variables of the color contract above, so a theme has nothing to style:

Token Sets Value
--pop-bg The surface of a toast, of the indicator and of the panel Light: --bg-secondary mixed 15% into white. Dark: --text-primary mixed 12% into --bg-secondary, which is lighter than every page surface
--pop-line, --pop-hairline The border of the indicator and the panel, the lines between rows --text-primary mixed into the surface
--pop-bar, --pop-track Progress bars, the spinner and the hairline of the indicator, and their track --bg-button (light), --text-accent (dark)
--pop-shadow, --pop-shadow-up The shadow of a toast and of the panel over the page, and the upward shadow of the docked panel
--pop-radius, --pop-radius-sm The corners of cards and of buttons and marks --radius-lg, --radius-md
--type-info, --type-success, --type-warning, --type-error The badge and the border of a toast, the mark of a failed row Blue, green, amber and red, the same in every theme and color scheme
--type-*-fg Text and icons of a type on the surface A value for light and a value for dark, each 4.5:1 or more on the surface

Rules for a theme:

  • The type colors are not changed, and --pop-bg is not set to a page color. A message has to stand out from the page in every theme.
  • The shape follows the radius tokens. A rule on a .queue-* or .toast-* class is added only where the layout of the theme requires it, as in the Workspace theme, where the docked panel is placed in the grid of the sidebar.
  • The docked panel is a child of .sidebar-content-wrapper, after the recording list. In a theme where that wrapper is not a column flexbox, the theme places .queue-dock itself and caps the height of .queue-dock.is-open.
  • The marks of the rows use --bg-info-light, --bg-processing-light, --bg-success-light and --bg-tertiary with their text colors.

The phone layout

Below 768 px the recording page and the recording list have one structure for every theme. It is not a slot: the markup is in templates/components/phone/ (the top bar of a recording, the details block, the sheets, the top bar, filter chips and sheets of the list) and in the phone parts of templates/components/detail/ (the four tab panes, the player strip, the tab bar). A theme does not copy this markup. It sets tokens and, where a token is not enough, adds a rule on a .ph-* class, in a section named "Phone layout" of its stylesheet. The base is static/css/phone.css, which every theme gets, built from the variables of the color contract above. The rows of the list are still the theme's sidebar-row, and a speaker turn is still its transcript-turn-mobile.

Token Sets Base value
--ph-page, --ph-bar, --ph-surface, --ph-surface-2, --ph-surface-3 The page behind the text, the bars (top bar, details block, pinned transcript bar), sheets and strips, and the two inset fills --bg-primary, --bg-secondary, --bg-secondary, --bg-tertiary, --bg-tertiary
--ph-text, --ph-text-2, --ph-text-3 Text, secondary text, muted text and icons --text-primary, --text-secondary, --text-muted
--ph-divider, --ph-line Lines between regions, outlines of fields and chips --border-primary, --border-secondary
--ph-accent, --ph-on-accent The New recording button, the play button of the player sheet, the progress line --bg-button, --text-button
--ph-accent-c, --ph-on-accent-c Pressed chips and toggles, the selected speed --bg-accent, --text-accent
--ph-link, --ph-danger, --ph-warn, --ph-star Text buttons, delete rows, reset rows, the star --text-accent, --text-danger, an amber, a gold
--ph-tab-pill, --ph-tab-on, --ph-tab-off The fill behind the icon of the open tab and the colors of the tab labels --ph-accent-c, --ph-on-accent-c, --ph-text-3
--ph-font-title, --ph-font-read, --ph-fs-title, --ph-fs-read, --ph-lh-read The faces and sizes of titles and of reading text inherited, 16px, 15px, 1.6
--ph-r-ctl, --ph-r-field, --ph-r-seg, --ph-r-chip, --ph-r-md, --ph-r-sheet, --ph-r-fab, --ph-r-composer The corner radii of icon buttons, the search field, the Transcription / Translation switch, chips, rows and tiles, sheets, the New recording button and the composer pills, 12px, 20px, 18px, 22px
--ph-scrim, --ph-shadow, --ph-shadow-1 The veil behind a sheet, the shadow of sheets and of the New recording button, the small shadow of the selected switch option

Rules for a theme's section:

  • Controls keep a touch target of 44 px or more. A theme may make a bar or a row denser, but not a button smaller than that.
  • The transcript's pinned bar (.ph-tbar) is position: sticky in the recording's one scrolling area (.ph-scroll). The themes' own sticky speaker labels (.speaker-run > .speaker-tablet) pin under it through --ph-tbar-h. A theme must not give .ph-scroll or an element between it and .ph-tbar an overflow value, which would end the pinning.
  • No :has() on <html> or <body>. The state of the page is on <body> as classes (queue-open, queue-minimized) and on the elements (aria-pressed, aria-current).
  • The recording list is the sidebar element at full width (aside.sidebar.ph-list), under the dialogs. phone.css sets its width with a selector that outweighs a theme's own sidebar width.

The public share page (templates/share.html) shows the transcript in the visitor's theme, so it includes the transcript-turn slot a second time, with transcript_read_only set. Its Vue app (static/js/share-page.js) is not the main app and provides only transcriptView, currentPlayingSegmentIndex, seekAudioFromEvent, showTimestampsSimpleView (always false), formatTimestamp, t and uiTheme. A transcript-turn partial therefore reads nothing else, and puts what belongs to the owner alone (the double click that opens the editor and its tooltip) inside {% if not transcript_read_only %} ... {% endif %}. The guard test checks both.

Changes that only add a class or adjust an inline style on shared chrome (the header bar, the account tab strip, the sign-in body) are made in the theme's CSS against the existing selectors instead of in a slot. A JavaScript default that differs per theme (for example where the indicator of the processing queue is shown) is read from uiTheme in static/js/app.modular.js. A formatting helper needed by a theme partial is added to the main app's returned scope, where it is available to every theme.

Shared hooks a theme can use

Two pieces of shared markup are prepared for themes and need no slot.

Hook Where How a theme uses it
Back link <a class="page-header__back"> in templates/components/page-header.html, the header of the Account, Admin and group management pages. It holds an arrow icon and the label nav.backToRecordings, and links to the recordings. It is display: none in static/css/primitives.css, so no theme shows it by default. A theme shows it with html[data-ui-theme="<id>"] .page-header__back { display: inline-flex; } and styles it like the other header buttons of the theme (workspace and desk do this).
Close on outside click <details data-close-outside> static/js/modules/utils/close-outside.js, installed in the main app and in the header app, closes every open menu of this kind when a click lands outside it and when Escape is pressed. A theme menu built on <details> (for example the overflow menu of the Focus header) adds the attribute and keeps any handlers it already has.

The floating chat button (.floating-chat-fab) is 44px and see-through (opacity: 0.6) until it is hovered or focused. A theme that overrides it keeps a target of at least 44px and does not set opacity; a transition override includes opacity so the change is smooth.

The guard test

In tests/test_ui_theme_slots.py, every override, templates/themes/<id>/<slot>.html, is compared with the default partial of the same slot. An override may add behaviour and change markup and classes freely, but it must keep everything in this list that the default has:

Kind What is compared
Handlers @event and v-on:event attributes, by their handler expression (whitespace-normalized; the event name and modifiers may change)
v-model The bound target, with any modifiers
Refs ref and :ref values
Ids id and :id values, used to look elements up in scripts and tests
Data attributes The names of all data-* attributes, static or bound (for example data-header-more-menu, used by the outside-click handler, and :data-start-time, read by the player); for data-i18n* attributes the translation key counts as well
Accessibility labels The translation keys in t('...') inside aria-label, title, alt and placeholder, static or bound

A justified difference goes into ALLOWED in the test, keyed by (theme, slot) and kind, with a comment that gives the reason. When a theme moves markup from one slot to another, MOVED lists the slots whose overrides together must keep what the default slot had; for example, a theme that moves the header actions into a toolbar in detail-meta declares ('<id>', 'header-actions'): ('detail-meta',).

Further checks in the same file: every slot has a default partial and is placed exactly once (the transcript turn a second time on the public share page, whose names it is checked against), theme folders hold only registered themes and slots, every registered theme has a name and description in all seven locales, every available theme has a WebP preview, and every rule of static/css/themes/<id>.css is scoped under html[data-ui-theme="<id>"]. The setting, the endpoint, the pre-paint markup, the picker and the slot branches are tested in tests/test_ui_themes.py, and the pre-paint script is run against a stub browser in static/js/modules/composables/ui-theme.test.js.

Adding a theme

  1. Registry. The theme is already listed in UI_THEMES in src/config/ui_themes.py if it is one of the five designs; otherwise add a UiTheme('<id>', available=False) entry. Keep available=False until the steps below are done.
  2. Locale keys. Add uiTheme.themes.<id>.name and .description (one line) to all seven files in static/locales/, with real translations.
  3. Stylesheet. Create static/css/themes/<id>.css. Start every selector with html[data-ui-theme="<id>"], including the ones inside @media. Define the neutral variables for light and dark (see the color contract) and leave the accent variables to the scheme. The file is served as it is; no build step is needed. The stylesheet is loaded after tailwind.css, and with the scope each rule is more specific than a single Tailwind utility, so !important is rarely needed. A theme that needs a font face bundles it as Focus does with Source Serif 4: woff2 files and the licence are listed with their SHA-256 in scripts/download_offline_deps.py, land in static/vendor/fonts/<name>/, and are declared with @font-face (font-display: swap) in the theme's own stylesheet, so a browser fetches them only while the theme is active.
  4. Slots. For each slot the design changes, create templates/themes/<id>/<slot>.html, starting from a copy of templates/themes/default/<slot>.html. Keep the Vue bindings; add and restyle around them. Tailwind classes used in the partial are compiled because tailwind.config.js scans templates/**/*.html; run scripts/build_css.sh after adding new ones.
  5. Guard test. Run tests/test_ui_theme_slots.py. Every dropped behaviour is listed; restore it, or add it to ALLOWED or MOVED with the reason.
  6. Preview. Save a screenshot of the theme with the fictional demo data as static/img/themes/<id>.webp, 480 by 300 pixels (16:10), light mode, blue scheme. Never use real recordings.
  7. Make it available. Set available=True. The theme's card then appears in the picker, the id is accepted by the endpoint, and the slot branches are rendered.
  8. Screenshots. Start a demo instance with the fictional seed, choose the theme from Account > Preferences > Appearance as the demo user, and take the fixed screenshot set in light and dark mode. Compare with the default theme's set to check that nothing outside the design changed, and check every color scheme in both modes.

Testing a theme switch by hand

In the browser console of any signed-in page:

window.speakrApplyUiTheme('<id>');   // attribute, stylesheet, slots, saved to the account
document.documentElement.dataset.uiTheme;
window.speakrApplyUiTheme('default');