Un design system client arrivait avec sa propre grille d’espacements : 4px, 8px, 16px, 24px, 32px, 48px, 64px, convertis en rem, sept paliers précis à respecter partout, du padding d’un bouton à la marge entre deux sections. L’échelle par défaut de theme.json, avec ses valeurs en pourcentage relatives les unes aux autres, ne correspondait à aucun de ces sept paliers. Il fallait la remplacer intégralement, pas la retoucher à la marge.
C’est un cas fréquent dès qu’un client arrive avec une charte graphique déjà formalisée par une agence de design, souvent conçue sans connaissance de WordPress. Le rôle du développeur est alors de faire correspondre exactement le système imposé aux réglages de theme.json, pas d’imposer l’échelle par défaut du thème.
La clé settings.spacing.spacingSizes
Par défaut, WordPress génère une échelle d’espacement automatique basée sur des ratios (settings.spacing.spacingScale), pratique pour démarrer mais rarement calée sur un design system existant. La solution consiste à désactiver cette échelle automatique et à déclarer manuellement chaque palier via settings.spacing.spacingSizes :
{
"version": 2,
"settings": {
"spacing": {
"spacingScale": {
"steps": 0
},
"spacingSizes": [
{ "name": "4px", "slug": "10", "size": "0.25rem" },
{ "name": "8px", "slug": "20", "size": "0.5rem" },
{ "name": "16px", "slug": "30", "size": "1rem" },
{ "name": "24px", "slug": "40", "size": "1.5rem" },
{ "name": "32px", "slug": "50", "size": "2rem" },
{ "name": "48px", "slug": "60", "size": "3rem" },
{ "name": "64px", "slug": "70", "size": "4rem" }
]
}
}
}Mettre steps à 0 dans spacingScale désactive la génération automatique, pour ne conserver que les valeurs explicitement listées dans spacingSizes. Sans cette désactivation, les deux échelles cohabitent et l’éditeur propose un mélange confus de valeurs automatiques et personnalisées.
Choisir des slugs stables dès le départ
Le slug de chaque palier (ici 10, 20, 30…) est ce qui est enregistré dans le contenu des articles et des pages, pas la valeur en rem elle-même. Renommer ou réordonner ces slugs après que des rédacteurs ont commencé à les utiliser casse silencieusement les espacements déjà appliqués sur le site : les blocs concernés se retrouvent avec un slug qui ne correspond plus à rien.
- Choisissez des slugs numériques croissants (
10,20,30…) plutôt que des noms descriptifs, pour pouvoir insérer un palier intermédiaire plus tard sans tout renommer. - Documentez la correspondance slug ↔ valeur dans un fichier interne à l’agence, pas seulement dans
theme.json, pour que l’équipe garde une référence même hors du code. - Ne supprimez jamais un palier utilisé en production sans vérifier d’abord son usage réel dans le contenu existant, via une recherche dans la base de données sur le slug concerné.
Le lien avec les contrôles de l’éditeur
Une fois spacingSizes défini, les contrôles de marge et de padding de l’éditeur de blocs (pour les blocs qui supportent spacing dans leurs block.json) affichent automatiquement les sept paliers définis, avec leur nom lisible (« 16px », « 32px »…). Les rédacteurs ne manipulent jamais directement les valeurs en rem : ils choisissent parmi les options proposées, ce qui garantit le respect de la grille du design system sans discipline particulière à leur demander.
Un piège fréquent : les unités mixtes
Un design system peut mélanger des valeurs en rem pour les espacements de contenu et en pixels pour des éléments d’interface fixes (bordures, par exemple). spacingSizes accepte n’importe quelle unité CSS valide dans le champ size, mais mélanger les unités au sein d’une même échelle complique la compréhension pour l’équipe rédactionnelle, qui voit des valeurs incohérentes selon le contexte. Notre recommandation : une seule unité par échelle, quitte à documenter séparément les exceptions ponctuelles gérées hors theme.json.
En résumé
Redéfinir l’échelle d’espacement de theme.json pour coller à un design system client est une opération simple techniquement, mais qui engage le projet sur le long terme via le choix des slugs. Prenez le temps de figer une nomenclature stable avant la mise en production : c’est le seul élément de cette configuration qui devient coûteux à corriger une fois du contenu réel créé.
