Theme Studio - MailTrixy Documentation

Where to find it

Admin panel → left sidebar → Theme Studio (under the System section, right after Settings). Direct URL: /admin/theme-studio.

What it controls

13 colour tokens, each independently configurable for light mode and dark mode (26 pickers total). These tokens flow through every CSS rule in the platform via CSS custom properties.

Brand Colors group

Primary — main brand color. Used for primary buttons, links, focused inputs, brand mark, progress bars.
Primary Strong (hover) — hover / pressed / emphasis variant. Typically the primary darkened ~10%.
Secondary — secondary brand color for badges, subtle accents.
Accent — highlights, gradients, decorative elements.

Status Colors group

Success — green confirmations, “Connected” / “Active” pills, save toasts.
Warning — amber warnings, “Edited” / “Pending” pills.
Danger — red destructive actions, errors, “Failed” pills, Refund button.
Info — blue informational banners.

Surface & Text group

Surface — main page background.
Surface 2 (cards) — panel / card background (one layer up from page bg).
Ink (body text) — primary text color, headings, body copy.
Muted (labels) — secondary text color for labels, captions, helper text.
Border / Divider — subtle outlines around cards, table rows, inputs.

How to use it

Open /admin/theme-studio.
The page lands on whichever mode is currently active (light or dark) based on your admin display preference.
Click the Light Mode or Dark Mode toggle at the top to switch which mode you're editing.
Pick any colour swatch — either use the native colour picker or type a hex value directly. Both inputs are two-way synced.
The Live Preview card on the right updates in real time, showing buttons, badges, links, headings, and status pills with your new colours.
Switch to the other mode and repeat (both modes are saved together).
Click Save Theme in the preview card. Refresh any page to see the new colours applied site-wide.

Reset buttons

Reset Mode to Defaults — revert only the colors in the currently displayed mode (light OR dark). Doesn't save automatically — click Save Theme after if you want it persisted.
Full Reset — reverts BOTH light and dark to MailTrixy defaults AND saves immediately. Confirmation dialog before it runs.

How it works under the hood

Your saved colours live as a single JSON blob in the system_settings table under key theme_config. On every page load, ThemeHelper::renderCss() emits a tiny <style> block with CSS custom properties on :root (light mode) and .dark, [data-theme="dark"] (dark mode). This block is injected into the <head> of every layout in the platform:

Frontend marketing site
Admin panel
User dashboard
Inbox
Login & onboarding

Because every CSS rule in app.css uses var(--color-brand), var(--color-surface), etc. instead of hardcoded hex values, your custom colors take effect everywhere instantly. Cached for 1 hour with automatic invalidation on save.

Dark mode toggle (end-users)

Each end-user can toggle between light and dark mode via the moon/sun icon in the top header. Their choice is persisted in localStorage so it survives page reloads. Theme Studio defines what dark mode looks like; users decide whether to use it.

Best practices

Test in both modes. A colour that looks great in light mode often looks too bright in dark mode. Always switch tabs and check.
Pick a primary first, then derive primary-strong. Use a colour-tool like coolors.co to get a shade ~10% darker for the hover state.
Keep status colours close to their conventional hues. Users expect green = success, red = danger, amber = warning. Drifting too far causes confusion.
Contrast matters. Make sure your ink text is readable on the surface background. A common dark-mode mistake is too-dark ink on a not-quite-black surface.
Try the Full Reset if you make a mistake and want to start over. Defaults are tasteful indigo + slate.