Skip to content

Themes

Define a theme that controls colour, typography, spacing, and charts across every doc, grid, mail, and plot.

AI-assisted, human-approvednovem uses AI to review and keep our documentation up to date.

Why themes

Themes define colours, fonts, spacing, and other styles shared by documents and plots. Use the --novem-* CSS variables to change these styles. For example, --novem-accent supplies the accent colour used by links and callouts that refer to it.

Embedded custom JavaScript plots can read the document's resolved variables through CSS, such as var(--novem-text), or through render.theme.text. Using these values lets the plot follow its containing document's theme.

Theme structure

Novem supplies structural styles and default values for its CSS variables. The selected theme defines the appearance. Custom styles can then target individual elements or override variables where the selected mode allows it.

For documents, the modes are:

ModeStyles applied after the structural defaults
novemBuilt-in novem theme; document custom CSS is ignored
customDocument custom CSS
Organisation themeOrganisation CSS, followed by document custom CSS

Within those stylesheets, normal CSS specificity and source order determine which rule applies. The document theme reference lists the available selectors and variables.

Page layouts

A theme can define page layouts as well as colours and fonts. For example, a page with type: summary gets the class novem--doc--page--type-summary. Use that class to define a CSS grid, then place blocks within the grid using area in the markdown.

The Layout reference includes a complete example. The Document theme reference lists the CSS selectors and variables.

Choosing a theme

Each document, grid, plot, or mail has a config/theme value. Use novem for the built-in theme, custom for the resource's own CSS, or +<organisation>/<theme> for an organisation theme with shared CSS and assets.

You can set the theme via the CLI, the API or the editor.

# CLI
novem -p example_plot -w config/theme custom

# API
curl -X POST -H "Authorization: Bearer $NOVEM_TOKEN" \
  -H "Content-Type: text/plain" -d "custom" \
  https://api.novem.io/v1/vis/plots/example_plot/config/theme

Writing custom styles

Use semantic variables such as var(--novem-axis-color) in CSS or render.theme.axisColor in JavaScript. A fixed dark colour may have poor contrast in dark mode.

Check the result in both light and dark mode. Novem supplies defaults for both, but custom colours may need their own dark-mode overrides. The theme example shows how to provide them.

Define reusable palette values as private variables, such as --brand-navy, then assign the relevant --novem-* variables to them. This keeps the palette in one place while retaining the purpose of each novem variable.

Resolved theme variables are passed to embedded plots. Set document variables on .novem--doc--page when the embedded plots should use those values.

Reference

  • Colors — named colors, scales and theme variables.
  • Typography — font families, sizes and weights.
  • Document — document-only theme primitives.
  • Charts — chart theme variables.
  • Org themes — reusable organisation themes.
Next
Example