Themes

Information about theming in Stump, including how to add new themes and fonts.

Color palettes

Stump supports CSS-based theming using Tailwind v4's CSS custom properties. This means that you can create your own themes by defining CSS variables in the themes file. All themes are defined in a single CSS file using CSS custom properties.

Adding a new theme

To add a new theme, you'll need to follow these steps:

1. Define the theme in CSS

Add your theme to the packages/components/tailwind/themes.css file. Each theme is defined as a CSS class with all the required color variables.

For example, let's create a "midnight" theme that is based on the dark theme, but with a pure black background:

.midnight {
	/* MARK: backgrounds */
	--color-background: #000000;
	--color-background-inverse: #ffffff;

	/* ... other theme colors ... */
}

You can copy an existing theme (like .dark or .light) as a starting point.

2. Add the theme to the theme selector

Update the ThemeSelect component to include your new theme in the dropdown:

<NativeSelect
	value={theme}
	options={[
		{ label: t(`${localeKey}.options.system`), value: 'system' },
		{ label: t(`${localeKey}.options.light`), value: 'light' },
		// ... existing themes ...
		{ label: t(`${localeKey}.options.midnight`), value: 'midnight' }, // <- our new theme
	]}
	onChange={(e) => changeTheme(e.target.value)}
/>

3. Add translation keys

Add the theme name to the translation files. The main English locale file is at packages/i18n/src/locales/en-US.json:

{
	"settingsScene": {
		"app/preferences": {
			"sections": {
				"themeSelect": {
					"options": {
						"system": "System",
						"light": "Light",
						"dark": "Dark",
						// ... other themes ...
						"midnight": "Midnight"
					}
				}
			}
		}
	}
}

4. Update the dark themes list (if applicable)

If your theme is a dark variant, add it to the DARK_THEMES array in packages/browser/src/hooks/useTheme.ts:

export const DARK_THEMES = ['dark', 'ocean', 'cosmic', 'pumpkin', 'autumn', 'midnight']

This ensures that the theme is recognized as a dark variant for proper UI adjustments.

5. Add gradient support (optional)

If your theme supports gradient backgrounds, add it to the THEMES_WITH_GRADIENTS array in the same file:

export const THEMES_WITH_GRADIENTS = ['cosmic', 'midnight']

Fonts

Stump has a limited number of fonts built-in:

• Inter
• OpenDyslexic
• Atkinson Hyperlegible
• Bitter
• Charis
• Literata
• Libre Baskerville
• Nunito
• Hina Mincho

Adding a new font

If you would like to add a new font, follow these steps:

1. Add the font files

Place your font files in the packages/browser/public/assets/fonts directory. Create a new folder for your font with a CSS file that defines the @font-face rules:

@font-face {
	font-family: 'My Font';
	/* define accordingly, this is an example */
	src: url('path/to/font.woff2') format('woff2');
}

2. Register the font in Tailwind CSS

Add your font to the Tailwind preset at packages/components/tailwind/preset.css. In the @theme block, add your font family definition:

@theme {
	/* MARK: fonts */
	--font-inter: 'Inter', ui-sans-serif, system-ui, sans-serif;
	--font-opendyslexic: 'OpenDyslexic', ui-sans-serif, system-ui, sans-serif;
	/* ... other fonts ... */
	--font-myfont: 'My Font', ui-sans-serif, system-ui, sans-serif;
}

Also add your font to the safelist so Tailwind doesn't purge it:

/* MARK: safelist fonts */
@source inline(
	'font-inter font-opendyslexic font-atkinsonhyperlegiblenext font-charis font-literata font-bitter font-librebaskerville font-nunito font-hinamincho font-myfont'
);

3. Add the font to the FontSelect component

Add your font to the SUPPORTED_FONT_OPTIONS in the FontSelect component:

export const SUPPORTED_FONT_OPTIONS = [
	{
		label: 'Atkinson Hyperlegible',
		value: 'atkinsonhyperlegiblenext',
		fontClassName: 'font-atkinsonhyperlegiblenext',
	},
	{
		label: 'Bitter',
		value: 'bitter',
		fontClassName: 'font-bitter',
	},
	{
		label: 'My Font',
		value: 'myfont',
		fontClassName: 'font-myfont',
	},
	// ... other fonts
]

This will allow users to select the new font from the settings page.

Restrictions

There are some restrictions for which fonts can be added:

• The font must be free to use and distribute (e.g., under the SIL Open Font License)*
• The font must be in a format that can be used on the web (e.g., WOFF2)
• The font must not add a significant amount of weight to the app (e.g., 1MB+)

* This is to ensure that the project remains in compliance with open-source standards and guidelines, and free to use for everyone. Stump is largely licensed under MIT, mobile app excluded, so fonts must be compatible with our licensing.

Future plans