Theming

Use the default theme, or give StellarAdmin.UI your own look by setting a few CSS variables

The StellarAdmin.UI stylesheet includes a default theme, so the components are styled as soon as you add the stylesheet to your layout:

<link rel="stylesheet" href="/_content/StellarAdmin.UI/stellar-admin.css" asp-append-version="true"/>

The components below use the default theme:

Changing the theme

To change the theme, you set theme variables. These are CSS variables, such as --sa-accent for the accent color, --sa-radius for the corner radius and --sa-density for the spacing. StellarAdmin.UI derives every color, size and shadow of the components from them. The theme variables page lists all of them.

The card below uses the default theme:

The theme file below sets seven theme variables, which give the same card a warm, orange, square and monospaced look:

wwwroot/css/theme.css
@layer sa.theme {
  :root {
    --sa-accent: oklch(0.6725 0.1362 42);
    --sa-neutral-hue: 85;
    --sa-neutral-chroma: 0.012;
    --sa-radius: 2px;
    --sa-elevation: 0.3;
    --sa-font-sans: "JetBrains Mono", ui-monospace, monospace;
    --sa-font-mono: "JetBrains Mono", ui-monospace, monospace;
  }
}

To use a theme file, link it in your layout after the StellarAdmin.UI stylesheet:

<link rel="stylesheet" href="/_content/StellarAdmin.UI/stellar-admin.css" asp-append-version="true"/>
<link rel="stylesheet" href="~/css/theme.css" asp-append-version="true"/>

When you write a theme file:

  • Set the theme variables on :root, inside @layer sa.theme. The layer gives your values precedence over the defaults.
  • Set only the theme variables you want to change. Most themes set between four and ten.
  • Don't set values for dark mode. StellarAdmin.UI derives dark mode from the same theme variables. To use a different value in dark mode, set the theme variable's -dark version, such as --sa-accent-dark.
  • You don't need to check the contrast of the accent color. StellarAdmin.UI makes text on the accent white or near-black, and adjusts the accent's fills and text to meet the WCAG contrast ratio of 4.5:1.

Creating a theme

Using the theme builder

The theme builder displays StellarAdmin.UI components while you change the theme variables, and downloads the theme file when you're done. Besides the default theme, you can start from one of the following presets:

PresetLook
LedgerWarm paper that turns indigo in dark mode, an indigo accent, roomier controls, uppercase labels on banded table headers, outlined parts and tactile buttons. Uses the Lexend font.
OpsDense and sharp, with strong lines, a safety-orange accent, banded table headers and an offset focus ring. Uses the IBM Plex Sans font.
SoftPill-shaped controls, roomy spacing, floating surfaces and a violet accent. Uses the Figtree font.

The presets aren't included in the package. To use one, change it as you like, and download your own theme file.

Using a coding agent

The stellar-admin-theme agent skill teaches coding agents, such as Claude Code and Codex, to write a theme file from a description, your brand colors or a look you want to match. Ask your agent for the look you want:

Use the stellar-admin-theme skill to give this app a warm, editorial, dense theme with a green accent.

The agent writes the theme file, links it in your layout and loads its fonts. It also gives you a link to the theme builder, where you can preview the theme and adjust it.

Writing a theme file yourself

A theme file is plain CSS, so you can also write one yourself, using the theme variables reference. You can write colors in any CSS color syntax. We suggest oklch(), because it's the easiest to adjust.

Adding fonts

StellarAdmin.UI doesn't load any fonts. Each font theme variable is a list of fonts that ends with the system fonts, so the text uses a system font until a web font loads, or if it never does. The default theme uses Inter when it's available. To use Inter instead of the system font, load it in your layout.

To use a web font, load it in your layout before the stylesheets, either from your own files or from a service such as Google Fonts:

<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter:wght@400..700&display=swap">

A theme file you download from the theme builder can load its fonts with an @import on its first line instead. This only works when you link the theme file in your layout. Browsers ignore an @import of a remote file in a stylesheet that is itself imported.

The Google Fonts display parameter controls how text is displayed while the fonts load. You can set it to one of the following:

ParameterWhat people see
display=autoThe browser decides whether text is displayed immediately or after the fonts load. Prefer one of the other values, so that the behavior is the same in every browser.
display=blockButton labels, the navigation and the text in tables can be invisible while the fonts load, so people must wait to read the page.
display=swapText is displayed immediately in a system font, and switches to the web font when it loads. Labels and the text in tables can move when the font switches. The demos on this site use swap.
display=fallbackText is displayed after a very short wait. If the web font loads soon after, the text switches to it. Otherwise, the text keeps the system font for that page.
display=optionalText uses the web font only if it loads almost immediately, and otherwise keeps the system font, so the text never moves. Choose this when stable forms and tables matter more than the theme's fonts.

Theming part of a page

You can also set theme variables on a single element, to change the density or the look of one part of a page, such as a dense table on a roomy page or a panel in your brand colors. See density and scopes. To display part of a page in dark mode, use the dark class, as described in dark mode.

Browser support

The StellarAdmin.UI stylesheet uses CSS relative color syntax, color-mix(), cascade layers, native nesting, :has() and @scope, without fallbacks. It needs Chrome or Edge 119, Safari 18 or Firefox 146, or later. In older browsers, some parts of the components are unstyled.

On this page