Skip to content
docsp
On this page

Theming

Theme axes, the accent color and its contrast rule, logo, banner, footer and the theme.css escape hatch.

A project changes its look through a fixed set of theme axes, its logo, banner and footer. Layout and components are the same for every project. Set the axes under theme in site.json to give every project a default, and in project.json to override them for one project.

JSONproject.json
{
  "theme": {
    "accent": "#0F7B6C",
    "mode": "system",
    "grays": "cool",
    "radius": "soft",
    "header": "tinted",
    "headings": "instrument-serif",
    "code": "light"
  }
}

Theme axes

Axis Values Default Effect
accent indigo, teal, orange, graphite or a hex color like #0F7B6C indigo Project color: links, active rows, buttons, header.
accentDark hex color accent Project color in dark mode.
mode light, dark, system system Color mode a first visit opens in. Readers can switch; their choice is saved.
grays warm, cool, neutral warm Gray scale of text, borders and surfaces.
radius sharp, standard, soft standard Corner radius scale.
header neutral, tinted, solid neutral Top bar: plain, the project color at 9% on the surface, or the project color with text on it.
headings geist, instrument-serif, space-grotesk or a custom font geist Heading font.
code dark, light dark Code block colors of the docsp code theme. Other code themes ignore it.
css path to a CSS file Escape hatch for custom properties; see below.

Code themes other than docsp are set with the top-level code.theme field; see Code themes.

The color mode on first paint comes from, in order: the reader's saved choice, the project's mode, then the system setting (prefers-color-scheme). A small script in the page head sets it before the page paints, so there is no flash.

Accent and contrast

For a hex accent, the build picks the text color that sits on it, white or #1b1b1a, whichever contrasts more, separately for light and dark mode. Presets come with their own text colors. It then checks these pairs in both modes and fails below 4.5:1:

  • text on the accent (buttons, the solid header);
  • accent text on the page surface (links);
  • accent text on the active sidebar row;
  • secondary header text on a tinted header;
  • header text on the search field of a solid header.

The error names the project, the color, the pair and the ratio:

Text
rocket/project.json (project "rocket"): theme color #F5A623 gives 2.03:1 for accent: --accent-text (#F5A623) on --surface (light), below the required 4.5:1. Choose a darker or more saturated color.

docsp check prints the lowest ratio of each project, so you can see how much margin a color has. This site uses #AF3A03 with warm grays.

Tip:

Dark mode needs its own color sometimes. A dark accent that works on a white page can fail as link text on a dark page. Set accentDark to a lighter variant. A project that sets accent without accentDark does not inherit the site's accentDark, since that one was chosen for a different color.

The four presets pass every check with the neutral and solid headers, in both modes and with every gray scale. graphite with a tinted header fails with every gray scale (4.29:1 in light mode and 3.93:1 in dark mode with warm grays): use another header with graphite. graphite uses white text in light mode and dark text in dark mode.

Custom heading font

JSONproject.json
{
  "theme": {
    "headings": { "family": "Brand Sans", "src": "fonts/brand.woff2", "weight": 600 }
  }
}

src is relative to the file that declares it, may contain letters, digits, ., _, - and /, cannot contain .., and must end in .woff2, .woff, .ttf or .otf. family may contain letters, digits, spaces, _ and -. weight defaults to 600. The build serves the file and writes the @font-face rule.

Without a logo image, the mark is a square in the project color with one or two letters:

JSON
{ "logo": { "mark": "R" } }

With images, light replaces the letters, and dark, when set, is shown in dark mode:

JSON
{ "logo": { "light": "brand/logo.svg", "dark": "brand/logo-dark.svg" } }

Paths are relative to the configuration file. The logo of site.json is the square in the top bar of the portal; the logo of project.json is used in the project selector, the portal card and the footer. A missing file fails the build.

A project can show one announcement above the top bar:

JSONproject.json
{
  "banner": {
    "id": "rocket-2-4",
    "variant": "accent",
    "tag": "New",
    "text": "Rocket 2.4 is out.",
    "link": { "label": "See what's new", "href": "/rocket/changelog/2.4.0/" },
    "until": "2026-12-31"
  }
}
Field Effect
id Required. A reader who closes the banner does not see it again for this id. Change the id to show a new banner.
variant Required. accent for releases, neutral for events, warning for breaking changes. A warning banner cannot be closed.
text Required. The announcement.
link, tag Optional link after the text and a short label before it.
dismissible true by default. false hides the close button.
until Last day the banner shows, YYYY-MM-DD.

until works twice: a build after that date leaves the banner out, and a page built earlier hides it in the browser once the date has passed, using the data-until attribute on the banner. Closed banners are remembered in the browser's local storage.

Pages of a deprecated version show a separate warning banner; see Versions and languages.

theme.css

theme.css is an escape hatch for values the axes do not cover. It may only redefine custom properties (--*) on :root or html selectors, optionally with attribute conditions:

CSStheme.css
:root {
  --r-card: 10px;
}
html[data-mode="dark"] {
  --r-card: 6px;
}
JSONproject.json
{ "theme": { "css": "theme.css" } }

The build fails, naming the selector or property, on:

  • any selector other than :root or html with attribute conditions such as [data-mode="dark"];
  • any declaration that is not a custom property;
  • at-rules such as @media or @import;
  • the characters <, > and \ anywhere in the file;
  • attribute values with characters other than letters, digits, spaces and _ . : -.
Warning:

No contrast check here. Colors set in theme.css are not contrast-checked. The four accent properties set by the build, --accent-light, --accent-dark, --on-accent-light and --on-accent-dark, cannot be overridden: set the color with accent instead.

The tokens you can redefine are in packages/docsp/tokens/tokens.css, and the token map says which design measure each one carries.

How the theme reaches the page

The theme is applied with attributes on <html> (data-mode, data-grays, data-radius, data-header, data-code, data-headings) and four inline custom properties for the accent. tokens.css derives every color from them. The build gives the rules of theme.css an id-level selector, so they win over tokens.css whatever the order of the stylesheets.

↑ ↓ to move↵ to openSearching docsp