Choose colours and a visual theme

This page is the colour and style reference in the customisation order. You do not need CSS to give a DocSprout site its own identity. Start with one colour preset and one visual style in docs/docsprout.json:

{
  "schema_version": 1,
  "project": {"name": "MyLibrary-FP"},
  "theme": {
    "preset": "purple",
    "style": "paper"
  }
}

Two choices that do different jobs

Visitors can choose a Mode: System, Light or Dark. System follows their browser or operating-system preference. You do not need to configure modes.

You choose the site’s starting Style:

• Classic (classic) is the clean, dependable default;
• Paper (paper) gives long guides a warm reading surface;
• Midnight (midnight) starts with a dark technical look.

Visitors can switch the Style too. DocSprout remembers both choices in the browser when storage is available.

The maintained single-version example starts in Paper ("style": "paper"), so its built opening page shows the warm reading surface before a visitor changes the control.

Classic is the showcase default: it keeps the header, navigation and reading surface quiet so ordinary Markdown supplies the personality. Paper and Midnight use the same spacing, typography and semantic states, with their own reading surfaces. No custom CSS is needed to make any of them publication-ready.

Pick an accent colour

The supported presets are:

Each preset provides link and highlight colours for both light and dark modes.

If your project already has accessible brand colours, you can provide exact hexadecimal values:

{
  "schema_version": 1,
  "project": {"name": "MyLibrary-FP"},
  "theme": {
    "accent": "#0f766e",
    "accent_secondary": "#0891b2",
    "style": "classic"
  }
}

Test custom colours in both Light and Dark mode. Links, selected navigation and keyboard focus must remain easy to see. A preset is safer when you are unsure. The maintained minimal example uses the exact teal values shown above; its built links, selected navigation and focus state use that accent.

Add a banner only when it helps

A home-page banner can show a project logo or useful illustration. It renders above the home page’s h1 heading, spans the content width and is capped at 16rem tall, so wide artwork works best. Save the image inside your repository first, then reference it and describe it for people who cannot see it. The file must already exist: docsprout build stops with a validation error when it is missing or unsafe.

{
  "schema_version": 1,
  "project": {"name": "MyLibrary-FP"},
  "banner": {
    "path": "docs/assets/project-banner.svg",
    "alt": "MyLibrary-FP logo"
  }
}

The alt text should communicate the image’s meaning. Use empty alt text only when the image is purely decorative and adds no information.

The maintained visual fixture configures the local docs/assets/visual-fixture-banner.svg asset. Build that fixture to see its banner above the opening content; it is the reproducible banner example, not a configuration you need to edit by hand.

The documented --dk-* tokens

Since v0.18, the public customisation token family is namespaced --dk-*; v1.0.0 is the stable commitment to the documented family. v1.1.0 renews that commitment under the DocSprout name without changing a single token. These tokens are ordinary CSS custom properties defined on the document root in every visual theme and colour mode. They are usable from the custom CSS escape hatch and by any tooling that reads generated styles:

These fifteen tokens are the documented customisation contract for 1.x. Classic, Paper and Midnight each define them in Light, Dark and System modes; the contract is regression-tested. Internal variables that DocSprout uses but does not document—radii, fonts, spacing scales, shadow, control heights and anything else whose name begins with --dk-—are not part of the contract and may change between releases. Pre-1.0 note: v0.18 renamed the earlier generic tokens (--bg, --text, --interactive, …) to this family; see the Migration guide if you referenced the old names.

Custom CSS: the advanced escape hatch

Custom CSS is optional, advanced and repository-local. It loads after DocSprout’s styles so it can deliberately override them, and DocSprout guarantees the safe inclusion mechanics—but the accessibility of the CSS you write is your responsibility. Ordinary sites need presets and exact colours only. See Custom CSS (advanced) for the complete contract and the maintained example.

Run docsprout check after every configuration change. The maintained visual fixtures explain how to review phone, tablet, desktop, keyboard and colour-mode behaviour.