Theme and branding
Read and write a project's theme, meaning its CSS variables, colors, logos and fonts, with GetTheme, SetTheme and CreateThemeLayer.
Overview
A project's look (its colors, corners, font and logos) lives in its own frontend layer, above the DMS, as plain files: a stylesheet of CSS variables, the ui.colors and branding.logo keys of its app/app.config.ts, and logo and font files under public/. That is the path the DMS theming guide describes, and the files stay hand-editable and versioned with the rest of the project.
GetTheme reads those files back, SetTheme writes them in one transaction, and CreateThemeLayer gives a project without a layer of its own the one a theme is written to. Like every other operation, they edit code, in development: nothing is stored in a database, and a theme reaches production with the next build.
import {
CreateThemeLayer,
GetTheme,
SetTheme,
} from "@antelopejs/interface-dms-builder";
Where the theme lives
The layer is the highest-priority frontend module the project registers from inside its root (the DMS and installed modules never are), unless the module config names one (theme.layerPath, relative to projectRoot or absolute). Inside it:
| File | Holds |
|---|---|
app/assets/css/theme.css | The @font-face rules of the fonts it hosts, then the variables, unlayered: :root for those both modes share, :root:not(.dark) for light, .dark for dark |
app/app.config.ts | ui.colors.<role>, a palette per Nuxt UI color role, and branding.logo.<slot>.<light|dark> |
public/branding/ | The uploaded logos, named after their content, and in fonts/ the files of the fonts the theme hosts |
dms.frontend.ts | The layer's entry, which imports the stylesheet |
The light rule is not plain :root: unlayered, a :root rule also matches the page in dark mode and beats the DMS's own dark values, which live in its dms cascade layer. A value set for light alone would show in dark too.
The DMS frontend loader applies a layer's app/app.config.ts on its own (the file's default export is spelled defineDmsAppConfig({…})), so the entry only imports the stylesheet. The email and favicon slots of branding.logo, and the branding.defaults an editor previews a return to the DMS look with, need a DMS that ships them.
A layer with a layers/ directory is read differently by the loader: it ignores the module root and reads each layer in layers/, sorted by name, the last one winning a value or a public file two of them set. The theme then goes in that last layer (layers/<name>/app/… and layers/<name>/public/branding/), and the entry, which stays the module's, imports the stylesheet from there. files in GetTheme's answer says which. A layers/ directory with no layer in it is answered unsupported: nothing written in the module would be read.
Read the theme
import { GetTheme } from "@antelopejs/interface-dms-builder";
async function readTheme() {
const result = await GetTheme();
if (!result.ok) {
if (result.error.code === "not_found") {
console.log(`no layer yet; CreateThemeLayer would create ${result.error.ref}`);
}
return;
}
const { variables, colors, logos, version } = result.data;
return { variables, colors, logos, version };
}
ThemeStructure is the theme as the files hold it:
| Field | Type | Description |
|---|---|---|
layer | ThemeLayer | The layer's name and absolute source path. |
variables | ThemeVariableSets | shared, light and dark: the custom properties each sets, by name. |
colors | ThemeColors | The palette each role takes: primary, success, warning, error, info. |
logos | ThemeLogos | The public path of each slot's file, per mode: default, collapsed, email, favicon. |
files | ThemeFiles | The files above, relative to the layer. |
stylesheetImported | boolean | Whether the entry imports the stylesheet already. |
version | string | A content hash of the stylesheet, the app config and the entry, for expectedVersion. |
Only what the builder can read back is reported: a palette or a logo path written as a string literal. A value the file holds any other way is the author's, and reads as no override. That covers an expression (primary: brand, process.env.BRAND ?? "violet"), a shorthand ({ primary }), a method and an accessor. In an object with a spread ({ ...base, primary: "violet" }), the string literals are read, and every other key reads as no override, since the spread may carry it in. A stylesheet holding anything but rules of custom properties under those three selectors, and the @font-face rules the builder writes, is reported unsupported rather than flattened.
Write the theme
SetTheme takes the whole theme, as it should be: what the draft leaves out goes back to the DMS default.
import { GetTheme, SetTheme } from "@antelopejs/interface-dms-builder";
const svg = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><circle cx="12" cy="12" r="10"/></svg>';
async function writeTheme() {
const theme = await GetTheme();
if (!theme.ok) return;
return SetTheme(
{
variables: {
shared: { "--ui-radius": "0.5rem" },
light: { "--ui-bg-muted": "#f6f5f2" },
dark: { "--ui-bg-muted": "#0c0b09" },
},
colors: { primary: "violet" },
logos: theme.data.logos,
uploads: [
{
slot: "default",
mode: "light",
contentType: "image/svg+xml",
base64Content: Buffer.from(svg).toString("base64"),
},
],
},
{ expectedVersion: theme.data.version },
);
}
- Code of the author's. A palette or a logo path the app config holds in code of its own (see above) is left as written by a draft that leaves it out, as one read back from
GetThemedoes. A draft that sets it is refused withunsupported, itsdetailnaming each key path (ui.colors.primary,branding.logo.default.light), and nothing is written: change it in the file itself. In an object with a spread, a draft may keep the literals as they were read, and changes none. - Uploads. An upload sets its slot and mode, over whatever
logossays there. SVG, PNG, JPEG, WebP or ICO, up to 512 KiB, its bytes checked against its type. Theemailslot takes a PNG or a JPEG alone, as an upload or as a path: Gmail and Outlook show no other image. The file is named<slot>-<mode>-<hash>.<ext>, so a new logo is a new URL no cache keeps serving under the old one; one file sent for several slots is written once. Of two uploads for one slot and mode, only the last is written. - SVG. It is written sanitized: scripts, event handlers,
javascript:links and embedded documents are taken out, and so is every reference to another file. That covers a link (href,xlink:href) on any element unless it points inside the file (#id), aurl()that does not (url(#gradient)stays),image-set()and@import, in attributes,styleand<style>alike.<image>and<feImage>may keep an embedded PNG, JPEG, GIF or WebP (data:image/png;base64,…), which loads nothing. The result carries ansvg_sanitizedwarning when anything that runs or fetches was taken out; what drawing tools leave in their exports (<metadata>,inkscape:*,sodipodi:*) goes silently. What is left must be a single well-formed<svg>: an HTML page, two images, or an Illustrator export declaring its namespaces as DOCTYPE entities (&ns_svg;) is refused withinvalid_config. Export it again as plain SVG. An SVG without itsxmlns, as copied out of an HTML page, is given one. - Old logos. A file the builder wrote and the theme no longer points at is deleted, the email logo's included. A file it did not name is never touched. An email already sent links to its logo by absolute URL, so it shows no header image once the file it names is deleted and deployed.
- Fonts. A variable whose value starts with one of the fonts below (
--font-sans: "Inter", ui-sans-serif, sans-serif) gets that font hosted by the project: its files are downloaded from Fontsource through jsDelivr (@fontsource-variable/<package>, at a pinned release) intopublic/branding/fonts/, and the stylesheet declares them in@font-facerules, so the dashboard shows it the same everywhere and fetches nothing from elsewhere. Each font comes as variable WOFF2 files covering the Latin alphabet, its italics when it has some, and itsOFL.txtlicense. A font named further down a stack is a fallback, and is not downloaded. The files are downloaded once: a save whose fonts are all in the layer needs no network, and one that cannot download a file is refused withunsupported, nothing written. A font file the builder downloaded and the theme no longer uses is deleted; one it did not name is never touched. The fonts, all under the SIL Open Font License: Inter, IBM Plex Sans, Public Sans, DM Sans, Manrope, Plus Jakarta Sans, Figtree, Atkinson Hyperlegible Next, Nunito and Source Serif 4. - Values. A variable's name must be a custom property, its value must not be able to end its declaration (
;, braces, comments,url(),@import,!important) nor leave a parenthesis, a bracket or a quote open (calc(1remwould swallow the rules after it), and a palette name must be one (violet, orbrandfor a project's own--color-brand-50…950). A logo path is rooted inpublic/(/branding/logo.svg), never//host/…. - Shape. A draft that is not shaped as
ThemeDraftsays (novariables, a value that is not a string, an upload without itsbase64Content) is answeredinvalid_config, each issue'spointernaming the value. - The entry. The first save that writes a stylesheet adds its import to the entry. In development that one change reloads the page; the stylesheet, the app config, new logos and new fonts are applied without one.
Every file is checked before any is written, and each is written whole, through a temporary file renamed over it. A write that fails half way puts back those already written and removes the directories it created, then throws the error that stopped it. stale comes back when the files changed since expectedVersion was read.
Create the layer
A project without a frontend layer of its own gets not_found from GetTheme, its ref naming where the layer would go. A layer whose entry file is missing also gets not_found, its ref naming that file; CreateThemeLayer does not fix that case, it returns the layer unchanged. CreateThemeLayer creates it there (frontend-vue/ beside the sources, with a package.json and an entry importing the stylesheet) and registers it from the project's exported start(), above the DMS:
import path from "node:path";
import { AddFrontendModule } from "@antelopejs/interface-dms/page";
export function start() {
AddFrontendModule({
name: "shop-frontend",
sourcePath: path.join(__dirname, "../frontend-vue"),
renderer: { name: "vue", version: "3" },
priority: 1,
});
}
start() is created, or made async, as it needs to be, and the edit is typechecked like any other; a registration that cannot be written takes the layer's files back with it. The layer's package.json declares the loader releases it runs on in its engines entry for @antelopejs/dms-frontend, and its app config, written by the first save that needs one, starts as export default defineDmsAppConfig({}). A project that has a layer keeps it, and nothing is written. The backend reloads with the registration; the frontend dev server reads its modules at startup, so it serves the layer once restarted.