Semantic

Themes

The semantic.css stylesheet includes five built-in themes: blue (the default), green, violet, red, and orange. Each theme overrides only the primary color, --p, with values for light and dark mode. Text, headings, links, backgrounds, surfaces, and borders use the same shared formulas and derive their colors from that primary. Layout, spacing, and corner radii stay consistent across themes.

Example text link

My form

Example form.

Usage

Load semantic.css and set data-theme on the root <html> element:

<!doctype html>
<html lang="en" data-theme="green">
  <head>
    <link rel="stylesheet" href="semantic.css">
  </head>
  <body>
    <!-- Your content -->
  </body>
</html>

Use data-theme="blue" or omit the attribute to use the default palette. An unrecognized value also falls back to blue. All five themes are included in the same stylesheet.

Place the attribute on <html>, rather than <body>, so the root variables are available throughout the document. Use the standard custom-data attribute data-theme instead of a custom theme attribute.

Color tokens

The color definitions live in theme.css. A theme needs only one override:

:root[data-theme="green"] {
  --p: light-dark(#086d4f, #4de6ac);
}

The shared tokens are --f for text, --fs for secondary text, --h for headings, --a for links, --b for the page background, --bs for subtle surfaces, and --d for borders. Changing --p updates these derived colors without duplicating the rest of the palette. Text and headings share one foreground color, and links use the primary color. Only the foreground and page background need color mixes; the other tokens reuse those colors or add transparency.

Hugo

Select the theme for a page in its frontmatter:

---
title: Example page
theme: green
---

baseof.html adds data-theme="green" to <html>, so the entire page uses the selected theme from the first render. Pages without a theme use the site parameter, or blue if no site parameter is set:

[params]
theme = 'blue'

A section can also supply the theme through Hugo’s cascade. The top-level Hugo setting theme = 'semantic' selects the Hugo theme itself.

To embed the stylesheet in every page instead of loading an external CSS file:

[params]
inject = true

inject defaults to false. This documentation site enables it. Production builds minify the CSS in either mode, and semantic.css remains available for download in both modes.

The favicon defaults to static/favicon.ico, supplied by your site. To embed the theme’s SVG favicon in every page instead:

[params]
injectFavicon = true

injectFavicon defaults to false and is enabled on this documentation site. To replace the embedded SVG, add your own assets/favicon.svg.

Light and dark modes

Palette selection is independent of light and dark mode. Each palette uses light-dark() colors and follows the system preference through color-scheme: light dark.

To force a mode, set color-scheme on the same root element:

<html lang="en" data-theme="violet" style="color-scheme: dark">

To change the palette from JavaScript:

document.documentElement.dataset.theme = "green";

All five themes are built in, so changing the attribute switches palettes immediately using the same stylesheet.