Brand & appearance | Mastria Docs

Your academy should look like it belongs next to your docs. Admin → Brand (its own row in the admin sidebar) is where you set how it looks: your logos, one brand color, your type, your corners, and whether the academy is light, dark, or follows each reader's device. A live preview sits beside the form, so you see the result before anyone else does.

You never write CSS. You give the academy a few inputs, and it works out every shade from them, readable in light and dark mode.

Match my docs

The fastest start: paste your docs address (docs.yourcompany.com) into Match my docs and press Import. The form fills in with the brand your docs already wear:

Your docs run on	What comes across
Mintlify	Brand color, a dark-mode color when your docs use a different one, dark-mode background, both logos, favicon (as the mark), fonts, default appearance
Docusaurus	Primary color for light and dark, dark-mode background, both navbar logos, favicon, fonts, corner radius
Starlight	Accent color for light and dark, dark-mode background, both site-title logos, favicon, fonts
Fern	Accent color for light and dark, dark-mode background, both logos, favicon
Anything else	The page's theme color, a logo in its header, its touch icon or favicon

Nothing is saved by an import. Read the summary under the button (it says what was found and what wasn't), check the preview, change anything you like, and press Save. Undo import puts the form back the way it was.

A few notes on how the import works:

It reads what your docs publish: Mintlify inlines its docs.json in every page, and Docusaurus, Starlight and Fern set CSS variables with known names. None of this is a documented API, so the import is best-effort. Whatever it finds is only a starting point for the form.
Mintlify has three colors: one for light-mode links, one for dark-mode links, and one for buttons. The academy uses the first as your brand. If it has no hue (black text with yellow buttons, say), the button color becomes the brand instead. The dark-mode link color comes across only when it's a different color, like a neon beside a dark teal. A lighter shade of your brand is left out, because the academy already makes dark-mode links about that light and keeps dark-mode buttons in your brand color. The summary names the shade it used.
A dark-mode background comes across only when it visibly differs from the one the academy would build anyway. A navy or near-black page does; the platforms' default greys don't. A dim grey page that's too light for every shade of a dark page is left out, and the summary says so.
An import that finds a brand color replaces the whole color set: a dark-mode color or background it doesn't bring is cleared, not kept from before.
A font comes across only when it's on the academy's font list (below). If your docs use one that isn't, the summary names it so you can pick the closest match.
Logos are linked, not copied: the academy shows the image from the address your docs use. If that address changes, update it here.

Logo

Logo for light pages: a wide logo with your name in it. It replaces the academy name in the header, and appears on certificates and the sign-in pages. Leave it empty to show the mark beside the academy name instead.
Logo for dark pages (optional): a version that reads on a dark page. Without one, dark pages show the light logo, so check the dark preview.
Mark: a square icon. It's the browser-tab icon and the image in your certificates' Open Badges data. When there's no logo, it also sits beside the academy name in the header, on certificates and on the sign-in pages.

All three are links to images on your site or CDN (https:// only). Each field shows a thumbnail, so a broken link is obvious straight away.

Color

Pick one brand color. The academy builds everything else from it:

Buttons and progress bars use your exact color. The only exception is a color that would disappear into the page (a very dark brand on a dark page); then the academy shifts it just enough to stay visible.
Links use your color's hue at a lightness that reads as text. A yellow or neon brand gets dark-gold or olive links in light mode.
Button labels are white or dark ink, whichever reads better on your color.
Greys carry a whisper of your hue, so no two academies share the same grey. Choose Pure grey if you'd rather not.

If your brand only works on dark pages (a neon green, say), tick Use a different color in dark mode and give that color separately.

If your docs' dark mode has a background color of its own, like a deep navy, tick Use your own dark-mode background and give it. Dark pages then sit on exactly that color, and cards, lines and greys are built from it. Text stays as readable as on the default dark page. A background that's too dark, too light or too vivid for every shade to hold is adjusted, and the preview notes say where it landed. The Greys choice then applies to light mode only.

Under the preview, What the engine adjusted lists every change it made in plain words, for example "Links use #a48500 in light mode so they read as text." It explains a color rather than refusing it.

Success and error colors never change: green means passed and red means failed in every academy.

Appearance

Follow the system (the default): each reader gets light or dark, whichever their device uses.
Always light or Always dark: the academy stays in one mode.
Let learners switch between light and dark: adds a switch to the header (System, Light, Dark). The browser remembers each learner's pick, and there's no flash of the wrong mode on the next visit. Turn it off to keep everyone on the appearance above.

Printed pages (certificates, the training history) always print light, dark ink on white, whatever the screen shows.

The admin keeps Mastria's own look in every academy, so states read the same everywhere; your brand shows in its previews. Staff get the header switch there whatever you pick above, and choose light or dark for themselves.

Type

Pick a heading font, a body text font and a code font from a curated list:

Text and headings: Mona Sans (the default), Inter, Geist, IBM Plex Sans, Source Sans 3, Roboto, Open Sans, Public Sans, DM Sans, Figtree, Manrope, Work Sans, Plus Jakarta Sans, Hanken Grotesk, Space Grotesk, Instrument Sans, Archivo, Albert Sans.
Code: JetBrains Mono (the default), Fira Code, Source Code Pro, Geist Mono, IBM Plex Mono, Roboto Mono, Red Hat Mono.

The code font applies to lesson code blocks and to the lab editor. Every font on the list is served by the academy itself (no request to Google), and a reader's browser downloads only the fonts your academy uses.

Corners

Soft (the default), Sharp or Round: how rounded cards, buttons and fields are across the academy. Pills and avatars stay round.

Preview and Save

The preview shows your academy as learners will see it, drawn from the form's current values: the header, a course hero, a course card, a lesson with the lab bench, the certificate and the sign-in email. It shows light and dark side by side, or just one if you've locked the appearance.

One Save applies the whole page, and learners see the new look on their next page. Until you save:

the bar at the bottom says there are unsaved changes, and Discard changes puts back what's saved;
leaving the page through the admin asks you to save or discard first.

If another admin saves the brand while you're editing, your Save doesn't overwrite theirs. The form loads their version, keeps your own edits on top, and asks you to review and save again.

Where your brand shows

every learner page: the header, cards, lessons, labs, certificates;
the sign-in pages and the sign-in email's button;
link previews (the generated course and certificate images use your colors);
the browser tab (your mark).

The admin itself keeps Mastria's own look, so buttons and status colors read the same in every academy. Your brand appears there only in previews: on this page, in course settings, and in the lesson preview.

What you can't do, on purpose

Custom CSS, HTML or JavaScript. Every learning platform that offers a CSS box ends up disclaiming it: redesigns break it, and it can't be exported. Your academy keeps working through every improvement to the platform because there's nothing custom to break.
Per-component colors or gradients. One color (plus an optional dark-mode color and background), derived consistently, is what keeps light, dark, yellow and neon brands readable. A docs site's always-dark navbar or a second button color stays behind.
Uploading your own font files. The list covers what developer-tool docs use. If your brand font isn't on it, tell us.