Theming

Nausikaä comes with a light and a dark theme, and follows the visitor’s system setting by default. A third theme is made for e-ink displays. All colors, fonts and sizes are custom properties (CSS variables), so you can adjust them to your own design without touching the framework.

Every custom property starts with --nausikaa-, for example --nausikaa-base or --nausikaa-link-color. The prefix keeps them apart from the variables of other stylesheets on the same page.

Out of the box, Nausikaä follows the appearance chosen in the visitor’s operating system: a dark system setting shows the dark theme, a light one the light theme. Nothing needs to be configured for this.

To choose a theme yourself, set data-theme on the <html> element. Leave the attribute out to follow the system again.

<!-- Follow the system setting -->
<html lang="en">

<!-- Always light -->
<html lang="en" data-theme="light">

<!-- Always dark -->
<html lang="en" data-theme="dark">

Nausikaä also tells the browser which theme is active, so built-in parts of the page—scrollbars, checkboxes, the date picker of a date field—match the theme too.

Remembering a visitor’s choice: this website offers Automatic, Light, Dark and E-ink in the navbar. The choice is stored in a cookie, and the server writes the matching data-theme into every page. Because the attribute is already in the HTML, the page never flashes in the wrong theme while it loads. If you store the choice with JavaScript instead, set the attribute in a small script at the top of the <head>, before the stylesheet is applied.

An e-ink display, such as that of an e-reader, shows sixteen shades of grey, redraws slowly and has no pointer that hovers. The e-ink theme is made for that. Choose it with data-theme="eink":

<html lang="en" data-theme="eink">

The theme is never chosen automatically. Browsers on these devices don’t say what kind of display they have, so offer the theme as a choice or set it on the pages you make for the device.

Choose E-ink in the navbar of this website to see the tags and buttons above, and every other page, in the theme. On a screen with color the page is shown in grey, the way an e-ink display would show it.

Meaning without color: in this theme a green and a yellow tag look the same. That is a reminder that a color should never be the only thing that carries a message: say it in words or with an icon as well. See Accessibility.

The accent colors of Nausikaä come from Catppuccin, an open-source color scheme by the Catppuccin community, published under the MIT license. Catppuccin offers four flavors of the same fourteen colors, from the light Latte to the dark Mocha. Nausikaä includes all four, numbered from 3 down to 0: the custom property for the Latte version of rosewater is --nausikaa-rosewater3, for the Mocha version --nausikaa-rosewater0. The full specification is available in the Catppuccin repository on GitHub.

The accent colors are the same in both themes. The step with the number 3 is the most saturated and works well for buttons, tags and progress bars; the lighter steps suit backgrounds, such as those of containers and panels.

The neutral colors for text, surfaces and backgrounds are Nausikaä’s own. They follow Catppuccin’s names, and the light backgrounds are taken from Latte. These are the colors that change between the light and dark theme; the swatches below show the theme you are viewing now.

Text uses --nausikaa-text on the --nausikaa-base background. The subtext colors are for secondary text, the overlay colors for borders and icons, and the surface colors for raised areas such as buttons. mantle and crust are slightly darker backgrounds, for areas such as the navbar and code examples.

Override any custom property in your own stylesheet, loaded after Nausikaä. Changes on :root apply to the whole page; sizes derived from the one you change, such as the line height from the font size, follow automatically.

:root {
  --nausikaa-font-size: 16px;
  --nausikaa-link-color: #8839ef;
  --nausikaa-block-text: "Source Serif 4", Georgia, serif;
}

To change a color in one theme only, use the same selectors as Nausikaä: [data-theme="dark"] for a chosen dark theme, and a media query for the system setting.

/* A warmer dark background */
:root[data-theme="dark"] {
  --nausikaa-base: #1e1e2e;
}

@media (prefers-color-scheme: dark) {
  :root:not([data-theme="light"]) {
    --nausikaa-base: #1e1e2e;
  }
}

Keep it readable: Nausikaä’s colors are chosen so that text meets the contrast guidelines in both themes, with a few exceptions listed under Accessibility. When you change colors, check the contrast of text against its background, for example with the WebAIM contrast checker.

Components such as buttons, panels, tags and notifications read their colors from custom properties of their own. A color class like primary or rosewater does nothing more than set those properties. That means you can add a color of your own in a few lines, and it gets every state—hover, focus, active, disabled—for free.

button.brand,
.button.brand {
  --nausikaa-button-background: #8839ef;
  --nausikaa-button-line: #5a1fa8;
  --nausikaa-button-shadow: #6a24c4;
  --nausikaa-button-text: #ffffff;
  --nausikaa-button-hover: #7a2ee0;
  --nausikaa-button-focus: #7a2ee0;
  --nausikaa-button-active: #6a24c4;
  --nausikaa-button-focus-ring: rgba(136, 57, 239, 0.5);
}

Your own colors in the e-ink theme

The e-ink theme sets the custom properties of every colored component itself, so that nothing ends up as hard-to-read text on a mid-grey. That also goes for a color class of your own: the brand button above becomes an ordinary outlined button there. To give it another look in the e-ink theme, set its properties once more for that theme, after your other rules:

[data-theme="eink"] button.brand,
[data-theme="eink"] .button.brand {
  --nausikaa-button-background: #000;
  --nausikaa-button-text: #fff;
  --nausikaa-button-shadow: #666;
}

Keep to black, white and a few greys: an e-ink display shows sixteen shades, and the two lightest look the same. #ddd is the lightest grey that can be told from white. Put text only on white, on #ddd or on black.