Creating Themes

If you are setting up a new website, you will usually want a custom theme.

The first step is to create a custom extension for your theme files.

See extensions.md for full extension documentation. The minimal theme setup is:

1. Create a folder at extensions/my_theme.
2. Create extensions/my_theme/package.json.
3. Enable the extension in the Latch admin dashboard.

Example package.json:

{
    "name": "My Theme",
    "description": "A custom theme for my website.",
    "author": "My Name",
    "version": "0.0.1"
}

Working With Chanterelle

Latch ships with a first-party theme called Chanterelle. You can use it in two ways:

1. Copy Chanterelle's files into your own extension folder, except package.json, and adjust them as needed.
2. Enable both Chanterelle and your theme, with your theme lower in the active extension list.

Option 2 is usually preferable because Chanterelle can continue receiving updates while your extension only contains overrides and additions.

Latch does not have a formal "child theme" concept. Instead, active extension order determines which files and styles win. Loading Chanterelle first makes it act like the base theme for extensions that follow it.

Latch itself contains very little CSS outside vendor libraries and generated variables. If you disable all theme extensions, both the site and admin dashboard will be minimally styled.

Theme File Structure

The main stylesheet entry point is:

extensions/my_theme/css/style.css

Latch automatically includes this file for every active extension when it exists.

We recommend using a preprocessor such as Sass for larger themes. Chanterelle's source shows one possible structure.

To test that your theme is loading, add a simple rule:

.search-container
{
    display: none;
}

Save the file and hard-refresh a page. If your stylesheet is loading, the search icon will no longer appear in the header.

You can also inspect the page source and look for a stylesheet reference similar to:

<link rel="stylesheet" href="/latch/extensions/my_theme/css/style.css?version=...">

Using Global Variables

Latch exposes common site properties as CSS custom properties, including colors, fonts, layout sizes, and spacing. These are generated by lib/components/css.php.

Theme authors should use these variables for common styling rather than creating separate dashboards for the same settings.

Example plain CSS:

.my-custom-el
{
    margin-block: calc(tan(atan2(var(--size_margin), var(--size_root_font))) * var(--site_scale) * 1rem);
}

If you are using Chanterelle's Sass helpers, you can use remvar_():

.my-custom-el
{
    margin-block: remvar_(--size_margin);
}

These variables are generated by Latch itself. Chanterelle does not need to be active for the variables to exist.