Theming

ZenithDocs styles are built on the design tokens of Lumos. Changing a handful of custom properties is enough to make the site yours. To try everything below at once and leave with the files to paste, use the theme builder.

A theme sets an accent, a backdrop and a font preset that go together, and a few tokens of its own, such as corner radii.

zenith({
  title: 'My Docs',
  theme: 'paper',
});

A theme only fills in what you leave unset: theme: 'paper', accent: 'rose' keeps everything from Paper except the accent. Its other tokens can be overridden in a customCss file like any other.

The default accent is emerald. Pick another preset with the accent option: teal, amber, rose, violet, or neutral for a black and white theme. Try them in the theme builder, which also takes any custom color.

zenith({
  title: 'My Docs',
  accent: 'violet',
});

Pages are drawn over a decorative background, tinted with the accent color. Pick its style with the backdrop option, and compare them in the theme builder.

zenith({
  title: 'My Docs',
  backdrop: 'grid',
});

aurora, dither and grain stay in place while the page scrolls; the other styles sit at the top of the page. dither is anchored to the top left, and backdropPosition: 'center' or 'right' moves it.

Every style is plain CSS, with no image file to download and no JavaScript: grain draws its noise with an SVG filter inlined in the stylesheet. Tune them with --zd-backdrop-strength, for the dither dots, and --zd-backdrop-line, for the grid and dots.

.theme-light {
  --zd-backdrop-line: color-mix(in oklab, var(--text) 5%, transparent);
}

Create a CSS file and register it with the customCss option.

zenith({
  title: 'My Docs',
  customCss: ['./src/styles/theme.css'],
});

Custom stylesheets are loaded after the built-in styles and are not part of any cascade layer, so they always win without !important.

Set your own accent for each color scheme:

:root {
  --zd-accent-light: oklch(55% 0.16 145);
  --zd-accent-dark: oklch(80% 0.15 145);
}

Light and dark themes are defined with the Lumos theme-light and theme-dark classes. Each redeclares the same tokens, so you can tune them independently:

.theme-dark {
  --background: oklch(15% 0.02 260);
  --background-2: oklch(19% 0.02 260);
}

The theme builder writes these for any color you pick, and derives the dark accent from the light one.

ZenithDocs ships seven font presets, self-hosted through the Astro Fonts API. The default, instrument, sets Instrument Serif over Instrument Sans with Martian Mono for code. Pick another with the fonts option, and compare them on the typography page.

The same page covers the three family tokens, --font-body, --font-mono and --font-display, fonts of your own, and the scales that make all text larger or smaller at once.

The width of the sidebar, the maximum width of the content column, and the radius of every rounded corner:

:root {
  --zd-sidebar-width: 18rem;
  --zd-content-width: 52rem;
  --radius-main: 0;
}

The page, the sidebar, the table of contents, code blocks and the search results all share one thin scrollbar style: a rounded thumb over a transparent track, so the background shows through.

The thumb is mixed from --text instead of being given a color of its own, which means it follows the light and dark themes, and any background you set, without being redefined.

:root {
  --zd-scrollbar-size: 0.75rem;
  --zd-scrollbar-thumb: color-mix(in oklab, var(--accent) 30%, transparent);
}

Firefox has no fine-grained control over scrollbars, so it gets scrollbar-width: thin and the same thumb color, without the rounding.

Built-in styles are split into layers, from lowest to highest priority:

@layer lumos.base, zenith.theme, zenith.layout, zenith.content, zenith.components;