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.
{
"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
tintedheader; - header text on the search field of a
solidheader.
The error names the project, the color, the pair and the ratio:
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.
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
{
"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.
Logo
Without a logo image, the mark is a square in the project color with one or two letters:
{ "logo": { "mark": "R" } }With images, light replaces the letters, and dark, when set, is shown in dark mode:
{ "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.
Banner
A project can show one announcement above the top bar:
{
"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:
:root {
--r-card: 10px;
}
html[data-mode="dark"] {
--r-card: 6px;
}{ "theme": { "css": "theme.css" } }The build fails, naming the selector or property, on:
- any selector other than
:rootorhtmlwith attribute conditions such as[data-mode="dark"]; - any declaration that is not a custom property;
- at-rules such as
@mediaor@import; - the characters
<,>and\anywhere in the file; - attribute values with characters other than letters, digits, spaces and
_ . : -.
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.