---
title: Background
description: Choisissez une décoration (gradient, grille de points, taches givrées ou plat), remplacez la couleur de fond par mode, ou ajustez la couleur, la taille, la position et l'opacité du gradient Jam.
---

Le bloc `background` dans `docs.json` contrôle le fond de page : choix entre quatre traitements de décoration (gradient par défaut, grille de points, taches givrées style Windows 11, ou plat), remplacement de la couleur de base par mode, et réglage de la couleur, de la taille, de la position et de l'opacité du gradient par défaut.

```json docs.json
{
  "theme": "jam",
  "background": {
    "decoration": "none",
    "color": {
      "light": "#faf7f2",
      "dark": "#0a0a0d"
    }
  }
}
```

Tous les champs sont optionnels. Omettez l'intégralité du bloc `background` pour utiliser les valeurs par défaut du thème.

## decoration

Choisissez le traitement de fond pour le mode clair du thème Jam. Chaque valeur affiche un motif distinct sur la couleur de base `--color-bg-primary` ; le mode sombre affiche toujours un fond uni quelle que soit la valeur.

```json docs.json
{
  "background": {
    "decoration": "grid"
  }
}
```

| Valeur | Comportement |
|--------|-------------|
| `gradient` (par défaut) | Gradient radial ancré en haut. Configurable via le bloc `gradient` ci-dessous |
| `grid` | Grille de points subtile : points de 1.5 px en `--color-primary` à 8 % d'opacité, espacement de 24 px |
| `windows` | Deux taches radiales douces dans les coins supérieurs (aspect givré style Windows 11) |
| `none` | Remplissage `--color-bg-primary` uni, sans décoration |

<Note>
`decoration` n'affecte que le mode clair du thème Jam. Nebula et Pulsar affichent des fonds unis quelles que soient la valeur. En mode sombre Jam, toutes les valeurs affichent un fond uni.
</Note>

## color

Remplacez la couleur de fond de la page par mode. Accepte toute couleur CSS : hex, `rgb(...)`, `rgba(...)`, ou `hsl(...)`.

```json docs.json
{
  "background": {
    "color": {
      "light": "#faf7f2",
      "dark": "#0a0a0d"
    }
  }
}
```

| Champ | S'applique à |
|-------|-------------|
| `color.light` | Fond du corps en mode clair |
| `color.dark` | Fond du corps en mode sombre |

Les deux champs sont optionnels. Définissez uniquement `light` pour remplacer le mode clair et conserver la valeur sombre par défaut du thème, ou inversement. Fonctionne sur tous les thèmes (Jam, Nebula, Pulsar).

<Tip>
Associez `decoration: "none"` à un remplacement `color` pour un fond plat et personnalisé — courant dans la documentation de style éditorial ou marketing.
</Tip>

## gradient

Réglez le gradient radial en mode clair du thème Jam. Les quatre champs sont optionnels et appliqués indépendamment. Définissez uniquement `color` pour recolorer, ou uniquement `size` pour réduire ou agrandir.

```json docs.json
{
  "background": {
    "gradient": {
      "color": "#a855f7",
      "size": "800px",
      "position": "top center",
      "opacity": 0.25
    }
  }
}
```

| Champ | Par défaut | Description |
|-------|------------|-------------|
| `color` | Hérite de `colors.primary` | Couleur du gradient (toute couleur CSS) |
| `size` | `500px` | Rayon. Toute longueur CSS (`px`, `rem`, `%`, `vh`) |
| `position` | `top center` | Point central. Mots-clés `top`/`bottom`/`center`/`left`/`right`, pourcentages ou coordonnées en pixels |
| `opacity` | `0.12` | Opacité maximale au centre. Nombre entre `0` et `1` |

<Note>
`gradient` ne s'applique que lorsque `decoration` est `gradient` (ou non défini). Les décorations `grid`, `windows` et `none` ignorent ce bloc — `grid` et `windows` lisent `--color-primary` pour leur couleur de motif ; personnalisez-la via le bloc `colors` à la place.
</Note>

### Compatibilité navigateurs

Le gradient paramétrique (consommation de variables CSS) utilise `color-mix()`, qui nécessite :

- Chrome / Edge 111+
- Firefox 113+
- Safari 16.2+

Les navigateurs plus anciens reviennent au gradient Jam d'origine : ils affichent le gradient par défaut de la marque et ignorent vos remplacements `gradient`. Le fallback lui-même est propre. Il ne peut simplement pas être personnalisé.

## Recettes courantes

<AccordionGroup>
  <Accordion title="Fond crème plat, sans gradient">
    ```json docs.json
    {
      "background": {
        "decoration": "none",
        "color": {
          "light": "#faf7f2",
          "dark": "#0a0a0d"
        }
      }
    }
    ```
    Courant dans la documentation de style éditorial. Fonctionne sur tous les thèmes.
  </Accordion>

  <Accordion title="Gradient violet subtil">
    ```json docs.json
    {
      "background": {
        "gradient": {
          "color": "#a855f7",
          "opacity": 0.15
        }
      }
    }
    ```
    Recolore le gradient Jam sans modifier sa taille ni sa position.
  </Accordion>

  <Accordion title="Gradient plus grand, décentré">
    ```json docs.json
    {
      "background": {
        "gradient": {
          "size": "1200px",
          "position": "top left",
          "opacity": 0.2
        }
      }
    }
    ```
    Gradient plus large et plus diffus, ancré dans le coin supérieur gauche.
  </Accordion>

  <Accordion title="Grille de points subtile">
    ```json docs.json
    {
      "background": {
        "decoration": "grid"
      }
    }
    ```
    Affiche une grille de points de 24 px légère dans la couleur principale de votre thème. Lit `--color-primary`, donc changez la couleur des points en définissant `colors.primary` dans `docs.json`.
  </Accordion>

  <Accordion title="Aspect givré style Windows 11">
    ```json docs.json
    {
      "background": {
        "decoration": "windows"
      }
    }
    ```
    Deux taches radiales douces dans les coins supérieurs, ancrées au viewport. Lit `--color-primary` pour la couleur des taches.
  </Accordion>

  <Accordion title="Remplacement du mode sombre uniquement">
    ```json docs.json
    {
      "background": {
        "color": {
          "dark": "#0d0d12"
        }
      }
    }
    ```
    Conserve les valeurs par défaut du thème en mode clair, choisit un fond personnalisé en mode sombre.
  </Accordion>
</AccordionGroup>

## Et ensuite ?

<Columns cols={3}>
  <Card title="Thématisation" icon="palette" href="/fr/customization/theming">
    Choisissez un thème de base et personnalisez les couleurs
  </Card>
  <Card title="CSS personnalisé" icon="paintbrush" href="/fr/customization/custom-css">
    Remplacez tout ce que CSS peut modifier
  </Card>
  <Card title="Branding" icon="image" href="/fr/customization/branding">
    Logos, favicons et ressources de marque
  </Card>
</Columns>