Background
Pick a decoration (gradient, dot grid, frosted spots, or flat), set the page background color per mode, or tune the Jam gradient's color and size.
The background block in docs.json controls the page background. Pick one of four decoration treatments, override the base color per mode, or tune the default gradient.
{
"theme": "jam",
"background": {
"decoration": "none",
"color": {
"light": "#faf7f2",
"dark": "#0a0a0d"
}
}
}All fields are optional. Omit the entire background block to use theme defaults.
decoration
Pick the background treatment for the Jam theme's light mode. Each value renders a distinct pattern over the base --color-bg-primary color. Dark mode always renders solid.
{
"background": {
"decoration": "grid"
}
}| Value | Behavior |
|---|---|
gradient (default) | Radial gradient anchored to the top. Tunable via the gradient block below |
grid | Subtle dot grid pattern: 1.5px dots in --color-primary at 8% opacity, 24px spacing |
windows | Two soft radial spots in the upper corners (Windows 11-style frosted look) |
none | Flat --color-bg-primary fill, no decoration |
decoration only affects the Jam theme's light mode. Nebula and Pulsar render solid backgrounds regardless. Jam dark mode always renders solid.
color
Override the page background color per mode. Accepts any CSS color: hex, rgb(...), rgba(...), or hsl(...).
{
"background": {
"color": {
"light": "#faf7f2",
"dark": "#0a0a0d"
}
}
}| Field | Applies to |
|---|---|
color.light | Light mode body background |
color.dark | Dark mode body background |
Set only light to override light mode and keep the theme's dark default. Set only dark for the reverse. This works on every theme: Jam, Nebula, Pulsar, Halo, and Dusk.
Pair decoration: "none" with a color override for a flat, branded background. This is common in editorial or marketing-style docs.
gradient
Tune the Jam theme's light-mode radial gradient. Every field is optional and applies on its own. Set only color to recolor, or only size to shrink or expand.
{
"background": {
"gradient": {
"color": "#a855f7",
"size": "800px",
"position": "top center",
"opacity": 0.25
}
}
}| Field | Default | Description |
|---|---|---|
color | Inherits colors.primary | Gradient color (any CSS color) |
size | 500px | Radius. Any CSS length (px, rem, %, vh) |
position | top center | Center point. top/bottom/center/left/right keywords, percentages, or pixel coords |
opacity | 0.12 | Peak opacity at the center. Number between 0 and 1 |
gradient only applies when decoration is gradient (or unset). The grid, windows, and none decorations ignore this block. grid and windows take their pattern color from --color-primary. Change it in the colors block.
Browser support
The parametric gradient (CSS variable consumption) uses color-mix(), which requires:
- Chrome / Edge 111+
- Firefox 113+
- Safari 16.2+
Older browsers fall back to the original Jam gradient and ignore your gradient overrides.
Common Recipes
{
"background": {
"decoration": "none",
"color": {
"light": "#faf7f2",
"dark": "#0a0a0d"
}
}
}Common in editorial-style docs. Works on any theme.
{
"background": {
"gradient": {
"color": "#a855f7",
"opacity": 0.15
}
}
}Recolors the Jam gradient without changing its size or position.
{
"background": {
"gradient": {
"size": "1200px",
"position": "top left",
"opacity": 0.2
}
}
}Wider, more diffuse gradient anchored to the top-left corner.
{
"background": {
"decoration": "grid"
}
}Paints a faint 24px dot grid in your theme's primary color. Change the dot color with colors.primary in docs.json.
{
"background": {
"decoration": "windows"
}
}Two soft radial spots in the upper corners, anchored to the viewport. Reads --color-primary for the spot color.
{
"background": {
"color": {
"dark": "#0d0d12"
}
}
}Keeps theme defaults in light mode, picks a custom dark mode background.