Dark mode

Every Dokly site supports light and dark mode out of the box. Readers toggle between them with a button in the top-right; their choice is remembered.

Defaults#

In Project Settings → Branding → Theme, pick the default theme:

• Light — site loads in light mode.
• Dark — site loads in dark mode.
• System (default) — follows the reader's OS preference.

Most developer-tool docs use System. It respects the reader's setup without forcing a choice.

The toggle#

The toggle is always present in the top-right of the published site. There's no setting to remove it — readers expect it, and removing it would be hostile.

The reader's choice is stored in localStorage on your domain. It persists across pages and visits. If localStorage is unavailable (e.g., private browsing), the choice is lost on reload.

How components handle dark mode#

Every component Dokly ships with — Callout, Card, Tabs, Steps, code blocks, badges — has a dark-mode variant baked in. You don't think about it.

Code blocks specifically: light mode uses GitHub Light, dark mode uses GitHub Dark. Both are tuned for high contrast and accessibility.

Authoring for both themes#

The only thing you need to think about is images. A screenshot taken in light mode looks bad on a dark background. A screenshot in dark mode looks bad on a light one.

Three options:

Logos#

Logos are the other thing to handle. Most logos don't read on both backgrounds. See Logo & favicon for how to upload light/dark variants.

Theme detection in custom CSS#

If you're using custom CSS (Pro+), you can target dark mode with the dark class on the root element:

.my-class {
  color: black;
}
 
.dark .my-class {
  color: white;
}

This matches the convention Dokly uses internally — Tailwind-style dark: variants.

Where next#