Background
Pick a decoration (gradient, dot grid, frosted spots, or flat), override page background color per mode, or tune the Jam gradient's color, size, position, and opacity.
The background block in docs.json controls the page background: choosing between four decoration treatments (default gradient, dot grid, Windows 11–style frosted spots, or flat), overriding the base color per mode, and tuning the default gradient's color, size, position, and opacity.
{
"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 regardless of the value.
{
"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. In Jam dark mode, all values render 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 |
Both fields are optional. Set just light to override light mode and keep the theme's dark default, or vice versa. Works on all themes (Jam, Nebula, Pulsar).
Pair decoration: "none" with a color override for a flat, branded background — common in editorial or marketing-style docs.
gradient
Tune the Jam theme's light-mode radial gradient. All four fields are optional and applied independently. Set just color to recolor, or just 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 read --color-primary for their pattern color, so customize that via the colors block instead.
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: they render the brand default and ignore your gradient overrides. The fallback itself looks clean. It just can't be customized.
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. Reads --color-primary, so change the dot color by setting 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.