Skip to content
Arbitex Docs

Theme Configuration

Theme Configuration

Section titled “Theme Configuration”

Arbitex ships with 22 brand themes that change the application’s color palette, typography accents, and component styling without affecting functionality. Themes are stored in localStorage so each user’s preference persists across sessions. Admins can also define custom themes by providing a JSON file conforming to the theme schema.

Selecting a Theme (Users)

Section titled “Selecting a Theme (Users)”
  1. Click your user avatar or open Settings in the sidebar.
  2. Navigate to Appearance.
  3. Choose a theme from the theme switcher grid. The change applies immediately — no page reload required.

Your selection is stored in localStorage under the key arbitex-theme.

localStorage key: arbitex-theme
Format:           theme identifier string (e.g. "ocean-blue", "forest-green")

Available Themes

Section titled “Available Themes”

Arbitex includes 22 built-in brand themes:

Theme name Description
default Standard Arbitex palette (blue/slate)
ocean-blue Deep oceanic blues and teals
forest-green Earthy greens and warm neutrals
sunset-orange Warm oranges and amber accents
midnight-purple Deep purples and indigo tones
rose-gold Rose pinks with metallic gold accents
arctic-white Clean whites with cool grey borders
volcanic-red High-contrast reds and charcoal
sand-dune Warm beiges and dusty browns
electric-cyan Vivid cyan and electric blue
lavender-mist Soft lavender and light purples
charcoal-noir Near-black with muted cool accents
spring-mint Fresh greens and off-white
copper-bronze Rich coppers and warm browns
sapphire-navy Deep navy with sapphire highlights
cherry-blossom Soft pinks and light neutrals
terracotta Earthy reds and clay tones
glacier Cool greys and icy whites
amethyst Rich purples and violet accents
goldenrod Deep yellows and warm oranges
slate-blue Muted blue-greys and cool tones
obsidian High-contrast blacks and silver

Note: The full theme grid is rendered in Settings → Appearance with live preview swatches.

Light and Dark Mode Interaction

Section titled “Light and Dark Mode Interaction”

Themes work in concert with the light/dark mode toggle:

  • Light mode — Uses the :root CSS custom properties defined for each theme.
  • Dark mode — Uses the [data-theme="dark"] overrides defined in each theme file, applying darkened backgrounds and adjusted foreground colors while preserving the theme’s signature accent palette.
  • System — Follows prefers-color-scheme. The application tracks OS changes in real time via a MediaQueryList listener.

The light/dark preference is stored separately from the theme:

localStorage key:   profile_settings.theme (synced to backend on save)
Theme class:        Tailwind `dark` class on <html>
Data attribute:     data-theme="dark" on <html>

Changing a theme while in dark mode applies the dark variant of the new theme immediately.

CSS Custom Properties

Section titled “CSS Custom Properties”

Each theme overrides a set of CSS custom properties on :root. These properties control all themeable surfaces in the UI:

/* Example: ocean-blue theme (light variant) */
:root {
  --color-primary:        #0077b6;
  --color-primary-hover:  #005f8d;
  --color-accent:         #00b4d8;
  --color-background:     #f0f8ff;
  --color-surface:        #ffffff;
  --color-surface-raised: #e8f4fd;
  --color-border:         #cce3f0;
  --color-text-primary:   #03045e;
  --color-text-secondary: #023e8a;
  --color-text-muted:     #48cae4;
}

Dark variant properties follow the same names under [data-theme="dark"]. Components in the codebase reference these variables via Tailwind’s [--color-primary] syntax or directly as var(--color-primary) in CSS modules.

Reserved Properties

Section titled “Reserved Properties”

The following properties must always be present in a valid theme:

Property Purpose
--color-primary Primary interactive color (buttons, links)
--color-primary-hover Hover state for primary elements
--color-accent Accent highlights and badges
--color-background Page background
--color-surface Card and panel background
--color-surface-raised Elevated surfaces (dropdowns, modals)
--color-border Default border color
--color-text-primary Body text
--color-text-secondary Secondary labels
--color-text-muted Placeholders and disabled text

Adding Custom Themes (Admins)

Section titled “Adding Custom Themes (Admins)”

Admins can define additional themes by providing a JSON file that conforms to theme-schema.json. Custom themes are available to all users in the organisation.

theme-schema.json format

Section titled “theme-schema.json format”
{
  "id": "my-brand-theme",
  "name": "My Brand Theme",
  "description": "Corporate palette matching brand guidelines",
  "light": {
    "--color-primary":        "#1a2e4a",
    "--color-primary-hover":  "#0f1e31",
    "--color-accent":         "#e85d04",
    "--color-background":     "#f5f5f0",
    "--color-surface":        "#ffffff",
    "--color-surface-raised": "#ececec",
    "--color-border":         "#d0cfc8",
    "--color-text-primary":   "#111111",
    "--color-text-secondary": "#444444",
    "--color-text-muted":     "#888888"
  },
  "dark": {
    "--color-primary":        "#4a90d9",
    "--color-primary-hover":  "#357ab8",
    "--color-accent":         "#e85d04",
    "--color-background":     "#0d0f14",
    "--color-surface":        "#161b24",
    "--color-surface-raised": "#1e2535",
    "--color-border":         "#2a3245",
    "--color-text-primary":   "#e8e8e8",
    "--color-text-secondary": "#a0a8b8",
    "--color-text-muted":     "#5a6278"
  }
}

Schema requirements

Section titled “Schema requirements”
Field Required Type Notes
id Yes string Unique identifier, lowercase, hyphens allowed, no spaces
name Yes string Display name shown in the theme switcher
description No string Short description for admin reference
light Yes object All 10 reserved CSS custom properties
dark Yes object All 10 reserved CSS custom properties for dark variant

All 10 reserved properties listed in the Reserved Properties section above must be present in both light and dark objects.

Installing a custom theme

Section titled “Installing a custom theme”
  1. Prepare your theme JSON file following the schema above.
  2. In the admin console, navigate to Settings → Appearance → Custom Themes.
  3. Click Upload Theme and select your JSON file.
  4. The theme is validated against theme-schema.json on upload. Validation errors are returned inline.
  5. Once uploaded, the theme appears immediately in the theme switcher for all users in your organisation.

Custom themes are org-scoped. They are not visible to users in other organisations.

Removing or Replacing a Custom Theme

Section titled “Removing or Replacing a Custom Theme”
  1. Navigate to Settings → Appearance → Custom Themes.
  2. Locate the theme and click Delete.
  3. Users who had that theme selected will be silently migrated to the default theme on their next page load (their localStorage value no longer matches a valid theme).

Troubleshooting

Section titled “Troubleshooting”

Theme switcher shows no themes / page is unstyled

The arbitex-theme localStorage entry may contain a stale or invalid theme ID. Clear it in the browser console:

localStorage.removeItem('arbitex-theme');

Then reload the page. The application will fall back to the default theme.

Custom theme not appearing for users

Custom themes are fetched from the server on application bootstrap. Ask affected users to perform a hard refresh (Ctrl+Shift+R / Cmd+Shift+R) to bypass any cached asset bundles.

Dark mode accent colors look wrong

Ensure your custom theme’s dark object overrides the accent properly. The --color-primary value used in dark mode should be a lightened variant of the brand color (sufficient contrast against dark backgrounds) rather than the same value used in light mode.

Section titled “Related Pages”