[data-reveal]{opacity:1!important;transform:none!important}
AntelopeJS DMS
DocumentationTheme and branding

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.

typescript
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:

FileHolds
app/assets/css/theme.cssThe @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.tsui.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.tsThe 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

typescript
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:

FieldTypeDescription
layerThemeLayerThe layer's name and absolute source path.
variablesThemeVariableSetsshared, light and dark: the custom properties each sets, by name.
colorsThemeColorsThe palette each role takes: primary, success, warning, error, info.
logosThemeLogosThe public path of each slot's file, per mode: default, collapsed, email, favicon.
filesThemeFilesThe files above, relative to the layer.
stylesheetImportedbooleanWhether the entry imports the stylesheet already.
versionstringA 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.

typescript
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 GetTheme does. A draft that sets it is refused with unsupported, its detail naming 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 logos says there. SVG, PNG, JPEG, WebP or ICO, up to 512 KiB, its bytes checked against its type. The email slot 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), a url() that does not (url(#gradient) stays), image-set() and @import, in attributes, style and <style> alike. <image> and <feImage> may keep an embedded PNG, JPEG, GIF or WebP (data:image/png;base64,…), which loads nothing. The result carries an svg_sanitized warning 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 with invalid_config. Export it again as plain SVG. An SVG without its xmlns, 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) into public/branding/fonts/, and the stylesheet declares them in @font-face rules, 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 its OFL.txt license. 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 with unsupported, 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(1rem would swallow the rules after it), and a palette name must be one (violet, or brand for a project's own --color-brand-50…950). A logo path is rooted in public/ (/branding/logo.svg), never //host/….
  • Shape. A draft that is not shaped as ThemeDraft says (no variables, a value that is not a string, an upload without its base64Content) is answered invalid_config, each issue's pointer naming 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:

typescript
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.