theme.json reference
Each field of the theme manifest, with its values and its default.
Full example
{
"formatVersion": 1,
"id": "my-theme",
"name": "My Theme",
"description": "One line about the theme.",
"author": "Your name",
"stylesheet": "content/theme.css",
"fonts": [
{ "family": "My Font", "src": "content/fonts/my-font.woff2",
"weight": "100 900", "style": "normal", "display": "swap" }
],
"typography": {
"fontFamily": ["My Font", "Segoe UI", "system-ui", "sans-serif"],
"headingFontFamily": ["Georgia", "serif"],
"fontSize": "0.875rem",
"headingWeight": "700",
"buttonWeight": "600",
"letterSpacing": "0.01em"
},
"layout": {
"borderRadius": "8px",
"appbarHeight": "5em",
"drawerWidth": "20em"
},
"login": {
"background": {
"image": "content/login.jpg",
"imageLight": "content/login-light.jpg",
"fit": "cover",
"position": "center",
"scrim": 0.35,
"color": "#101010"
},
"logo": "content/logo.svg",
"logoLight": "content/logo-light.svg"
},
"dark": { },
"light": { }
}
A theme needs only id and name. All other fields are optional. An omitted palette, typography or layout field keeps the default of the UI library.
Top-level fields
| Field | Content |
|---|---|
formatVersion |
The version of the manifest format. The only value is 1, which is also the default. |
id |
The ID of the theme: lower-case letters, digits and -. Two themes on one instance cannot have the same ID. |
name |
The name in the theme list of the Admin settings. |
description |
One line of text below the name. |
author |
The author of the theme. |
stylesheet |
The path of a CSS file in the package. See Fonts and stylesheet. |
fonts |
Font files in the package. See Fonts and stylesheet. |
typography |
See Typography. |
layout |
See Layout. |
login |
See Sign-in screen. |
dark, light |
The two palettes. See Palette. |
All paths are relative to the root of the package, for example content/theme.css.
Typography
| Field | Content | Default |
|---|---|---|
fontFamily |
A list of font families for body text, in order of preference. | The font of the UI library |
headingFontFamily |
A list of font families for headings. | The value of fontFamily |
fontSize |
The base font size, as a CSS length. | 0.875rem |
headingWeight |
The font weight of headings. | 700 |
buttonWeight |
The font weight of button text. | 500 |
letterSpacing |
The letter spacing of body text, as a CSS length. | None |
Write font family names without quotation marks:
"Segoe UI", not"'Segoe UI'". Solo adds the quotation marks in the CSS. A second pair makes the fullfont-familyrule invalid.
Layout
| Field | Content | Value in the default theme |
|---|---|---|
borderRadius |
The corner radius of cards, buttons and fields. | 8px |
appbarHeight |
The height of the app bar. | 5em |
drawerWidth |
The width of the sidebar. | 20em |
Sign-in screen
The background and the logo apply to the sign-in screen of the web app and to the sign-in page of the desktop app. The desktop sign-in page also uses the palette, the fonts and the corner radius of the theme. It uses the scheme of the computer, dark or light. It does not use the stylesheet of the theme.
Background
| Field | Content | Default |
|---|---|---|
image |
The path of the background image. | No image |
imageLight |
The path of a different image for the light scheme. | The value of image |
fit |
How the image fills the screen. See the table below. | cover |
position |
The position of the image, as a CSS background-position value. |
center |
scrim |
A number from 0 to 1. Solo puts a layer of the background colour on the image, with this opacity. |
0 |
color |
The colour behind the image. | The background colour of the palette |
fit |
Result |
|---|---|
cover |
The image fills the screen. Solo cuts the parts that do not fit. Use this for photographs. |
contain |
The full image is visible. Empty bands can show at two sides. |
width |
The image is as wide as the screen. The height follows the proportions. |
height |
The image is as high as the screen. The width follows the proportions. |
stretch |
The image fills the screen in the two directions. The proportions change. |
Use scrim with a detailed image. Without it, the text on the sign-in card can be hard to read.
Logo
| Field | Content |
|---|---|
logo |
The path of an image that replaces the word “Solo” on the sign-in card. |
logoLight |
The path of a different logo for the light scheme. |
Palette
dark and light have the same fields. Each field is optional.
Colour formats
A colour can be:
- A hex value:
#rgb,#rgba,#rrggbbor#rrggbbaa. - A function:
rgb(),rgba(),hsl()orhsla(). - A CSS colour keyword, such as
white.
Solo refuses a package that has a different value in a colour field.
Brand colours
| Field | Use |
|---|---|
primary |
The main accent: buttons, links, the selected sidebar entry and icons. |
secondary |
The second accent. |
tertiary |
The third accent. |
Surfaces
| Field | Use |
|---|---|
background |
The background of the page. |
backgroundGray |
A second background shade. |
surface |
The background of cards, dialogs and menus. |
appbarBackground |
The background of the app bar. |
appbarText |
The text and icons in the app bar. |
drawerBackground |
The background of the sidebar. |
drawerText |
The text in the sidebar. |
drawerIcon |
The icons in the sidebar. |
Text and controls
| Field | Use |
|---|---|
textPrimary |
Body text. |
textSecondary |
Captions and less important text. |
textDisabled |
The text of disabled controls. |
actionDefault |
Icon buttons in their normal state. |
actionDisabled |
Disabled controls. |
actionDisabledBackground |
The background of disabled controls. |
Lines and tables
| Field | Use |
|---|---|
divider |
Dividers. |
dividerLight |
Lighter dividers. |
linesDefault |
The borders of cards and panels. |
linesInputs |
The borders of text fields. |
tableLines |
The lines between table rows. |
tableStriped |
The background of alternate table rows. |
tableHover |
The background of a table row below the pointer. |
Status colours
| Field | Use |
|---|---|
success |
Success messages and completed items. |
warning |
Warnings. |
error |
Errors and destructive commands. |
info |
Information messages. |
Overlays
| Field | Use |
|---|---|
overlayDark |
The layer behind a dialog. |
overlayLight |
A lighter overlay layer. |
Contrast text
These fields set the text colour on a filled control:
primaryContrastText, secondaryContrastText, tertiaryContrastText, successContrastText, warningContrastText, errorContrastText, infoContrastText
Omit them. Solo then calculates each one from the WCAG contrast of its fill colour. For example, a light accent colour gets black text on its buttons.
The default theme as an example
This is the dark palette of Ahlquist Interactive. It shows colours with transparency for lines:
"dark": {
"primary": "#fff600",
"secondary": "#c9c400",
"tertiary": "#8a8600",
"background": "#000000",
"backgroundGray": "#080808",
"surface": "#101010",
"appbarBackground": "#000000",
"appbarText": "#fff600",
"drawerBackground": "#080808",
"drawerText": "#ffffff",
"drawerIcon": "#fff600",
"textPrimary": "#ffffff",
"textSecondary": "#b0b0a0",
"textDisabled": "#6f6f64",
"actionDefault": "#c9c400",
"divider": "#fff60040",
"dividerLight": "#fff60026",
"linesDefault": "#fff60040",
"linesInputs": "#fff60059",
"tableLines": "#fff60026",
"tableHover": "#fff6000f",
"success": "#5ad469",
"warning": "#ffb300",
"error": "#ff5252",
"info": "#fff600"
}
The full file is ahlquist-interactive/theme.json.