# Design tokens : une source unique pour la couleur et la typo

[Canonical HTML page](https://gradiently.design/fr/guide/design-tokens)

Une couleur de marque répartie dans quarante fichiers finit par dériver. Un token vit à un seul endroit et chaque plateforme le lit. Voici comment structurer vos design tokens, les nommer pour qu’ils durent et les livrer au code comme aux outils de design.

## The short version

- Les design tokens sont des valeurs nommées et indépendantes de toute plateforme pour les décisions de design : couleurs, familles de polices, tailles, espacements, arrondis, ombres et durées d’animation.
- La plupart des systèmes de tokens ont trois niveaux : les tokens primitifs contiennent les valeurs brutes, les tokens sémantiques décrivent un usage, et les tokens de composant appliquent ces usages à des éléments précis.
- Le format du W3C Design Tokens Community Group stocke les tokens en JSON avec les propriétés $value et $type, et référence d’autres tokens entre accolades.
- Des outils comme Style Dictionary transforment un seul fichier de tokens en propriétés personnalisées CSS, en JavaScript et en ressources iOS et Android.
- Le mode sombre et les marques multiples se résument à changer les valeurs derrière les tokens sémantiques, sans toucher aux composants.

Les **design tokens** sont des valeurs nommées pour chaque décision de design qu’une marque répète : couleurs, polices, tailles de texte, espacements, arrondis, ombres et durées d’animation. Au lieu de taper `#5b21b6` dans une feuille de style, un fichier Figma et une application iOS, vous définissez `color.brand.700` une fois, dans un seul fichier, et vous générez à partir de lui le format de chaque plateforme. Modifiez le token et tous les produits se mettent à jour ensemble. Cette source unique de vérité, c’est tout l’intérêt.

## À quoi ressemble un design token

Un token a un nom, une valeur et un type. Le format publié par le [W3C Design Tokens Community Group](https://www.w3.org/community/design-tokens/) les écrit en JSON, avec des propriétés qui commencent par un signe dollar pour ne jamais entrer en conflit avec les noms de groupes.

```json
{
  "color": {
    "violet": {
      "100": { "$type": "color", "$value": "#ede9fe" },
      "500": { "$type": "color", "$value": "#8b5cf6" },
      "700": { "$type": "color", "$value": "#6d28d9" },
      "900": { "$type": "color", "$value": "#4c1d95" }
    },
    "ink": { "$type": "color", "$value": "#14121f" },
    "paper": { "$type": "color", "$value": "#faf8ff" }
  },
  "font": {
    "heading": { "$type": "fontFamily", "$value": ["Fraunces", "Georgia", "serif"] },
    "body": { "$type": "fontFamily", "$value": ["Inter", "system-ui", "sans-serif"] }
  },
  "radius": {
    "control": { "$type": "dimension", "$value": { "value": 10, "unit": "px" } }
  },
  "duration": {
    "quick": { "$type": "duration", "$value": { "value": 160, "unit": "ms" } }
  }
}
```

Des tokens primitifs au format du groupe communautaire. Les groupes s’imbriquent librement ; le chemin, comme color.violet.700, devient le nom du token.

- color.violet.100: #ede9fe
- color.violet.500: #8b5cf6
- color.violet.700: #6d28d9
- color.violet.900: #4c1d95
- color.ink: #14121f
- color.paper: #faf8ff

Les tokens de couleur ci-dessus sous forme de nuancier. Ce sont des ingrédients bruts : rien ne dit encore lequel est un bouton ou un titre.

## Tokens primitifs, sémantiques et de composant

Une liste plate de couleurs est une palette, pas un système. La structure qui tient dans la durée compte trois niveaux, chacun faisant référence à celui du dessous. Les composants ne touchent jamais aux valeurs brutes : ils demandent un usage.

| Niveau | Exemple de nom | Valeur | Change quand |
| --- | --- | --- | --- |
| Primitif | `color.violet.700` | `#6d28d9` | La palette est redessinée |
| Sémantique | `color.action.primary` | `{color.violet.700}` | Un rôle passe à une autre couleur |
| Sémantique | `color.text.default` | `{color.ink}` | Mode sombre, nouvelle marque |
| Composant | `button.primary.background` | `{color.action.primary}` | Un composant a besoin d’une exception |

Les références entre accolades sont des alias. Modifiez color.violet.700 et chaque token qui pointe vers lui suit.

```json
{
  "color": {
    "action": {
      "primary": { "$type": "color", "$value": "{color.violet.700}" },
      "primary-hover": { "$type": "color", "$value": "{color.violet.900}" }
    },
    "text": {
      "default": { "$type": "color", "$value": "{color.ink}" },
      "on-action": { "$type": "color", "$value": "{color.paper}" }
    },
    "surface": {
      "page": { "$type": "color", "$value": "{color.paper}" },
      "tint": { "$type": "color", "$value": "{color.violet.100}" }
    }
  }
}
```

Les tokens sémantiques décrivent à quoi sert une couleur. C’est le niveau dans lequel designers et développeurs devraient se parler.

Beaucoup d’équipes s’arrêtent à deux niveaux, primitif et sémantique, et n’ajoutent des tokens de composant que là où un composant diffère vraiment. Le fichier reste ainsi assez petit pour être compris.

## Nommer les design tokens pour qu’ils durent

Les noms survivent aux valeurs. Un token appelé `color.purple` casse le jour où la marque passe au sarcelle ; un token appelé `color.action.primary` y survit. Nommez les tokens sémantiques par rôle, et gardez des noms primitifs qui décrivent la valeur.

### Des noms qui vieillissent mal

- `color.purple` utilisé pour les boutons
- `text.dark`, qui est clair en mode sombre
- `spacing.16` utilisé comme règle de mise en page
- `blue2`, `blueNew`, `blueFinal`
- `hero.gradient.lisa`, nommé d’après une personne

### Des noms qui durent

- `color.action.primary`
- `color.text.default`
- `space.section` qui pointe vers `{space.16}`
- Une échelle numérotée comme `blue.100` à `blue.900`
- `gradient.hero` avec ses arrêts en tokens

Choisissez un schéma, par exemple catégorie, puis rôle, puis variante, puis état, et consignez-le dans votre [guide de style de marque](https://gradiently.design/fr/guide/brand-style-guide). La cohérence des noms compte plus que le schéma choisi.

## Du fichier de tokens au CSS et aux applications

Le fichier de tokens n’est pas livré tel quel. Une étape de build le transforme dans le format dont chaque plateforme a besoin. Style Dictionary est l’outil open source le plus utilisé pour cela, et d’autres lisent le même format. Pour le web, le résultat est en général des propriétés personnalisées CSS.

```css
:root {
  --color-violet-100: #ede9fe;
  --color-violet-700: #6d28d9;
  --color-violet-900: #4c1d95;
  --color-ink: #14121f;
  --color-paper: #faf8ff;

  --color-action-primary: var(--color-violet-700);
  --color-text-default: var(--color-ink);
  --color-surface-page: var(--color-paper);

  --font-heading: Fraunces, Georgia, serif;
  --radius-control: 10px;
  --duration-quick: 160ms;
}

.button {
  background: var(--color-action-primary);
  color: var(--color-paper);
  border-radius: var(--radius-control);
  transition: background var(--duration-quick) ease;
}
```

Le résultat généré. Les alias deviennent des références var(), si bien que le niveau sémantique survit jusque dans le navigateur. Voir [les variables CSS pour les thèmes](https://gradiently.design/fr/guide/css-custom-properties-theming).

Si vous utilisez Tailwind v4, le bloc `@theme` est lui-même un niveau de tokens : chaque variable `--color-*` devient des classes utilitaires. [Les couleurs Tailwind](https://gradiently.design/fr/guide/tailwind-colors) montre comment y brancher une gamme de tokens. Le même fichier peut aussi produire des constantes Swift et des ressources Android, et c’est là que les tokens se rentabilisent pour les équipes multiplateformes.

## Mode sombre et marques multiples

Comme les composants ne lisent que des tokens sémantiques, un thème n’est qu’un autre jeu de valeurs pour ce niveau. Le mode sombre redéfinit `color.text.default` et `color.surface.page` ; une deuxième marque redéfinit `color.action.primary`. Rien ne change dans les composants.

```css
@media (prefers-color-scheme: dark) {
  :root {
    --color-text-default: #e9e5f5;
    --color-surface-page: #0b0a14;
    --color-action-primary: var(--color-violet-500);
  }
}

[data-brand="harbour"] {
  --color-action-primary: #0f766e;
}
```

Deux surcharges, aucune modification de composant. Les dégradés méritent eux aussi leurs propres valeurs sombres ; [les dégradés en mode sombre](https://gradiently.design/fr/guide/dark-mode-gradients) explique comment les régler.

> **Les tokens dans les outils de design** Les Variables Figma gèrent les collections et les modes, qui correspondent bien aux tokens primitifs et sémantiques et aux thèmes clair et sombre. Gardez le fichier de tokens comme source et synchronisez vers l’outil de design, pas l’inverse, sinon les deux se contrediront en moins d’un mois.

## Déployer des design tokens

1. **Faites l’inventaire de l’existant** Rassemblez chaque couleur, taille de texte et valeur d’espacement utilisée. Attendez-vous à des doublons qui ne diffèrent que d’un chiffre hexadécimal.
2. **Définissez les primitifs** Réduisez-les à des échelles claires. Construire les gammes de couleurs en OKLCH garde des paliers réguliers ; voir [OKLCH expliqué](https://gradiently.design/fr/guide/oklch-explained).
3. **Ajoutez le niveau sémantique** Nommez les rôles : texte, surface, bordure, action, retour. Faites pointer chacun vers un primitif.
4. **Automatisez le build** Générez le CSS et les ressources d’application à partir du fichier dans votre build, jamais à la main.
5. **Protégez-le** Ajoutez une règle de lint contre les valeurs hex brutes dans les composants, pour que le nouveau code utilise des tokens dès le premier jour.

Les tokens gardent le produit cohérent, mais les marques dérivent aussi dans les visuels créés en dehors : publications, slides, bannières. Un kit de marque Gradiently contient les mêmes décisions, vos palettes de couleurs, polices de titres et de texte, logos et ton, pour que les designs créés dans le Studio s’accordent. Et comme Gradiently fonctionne dans ChatGPT, Claude et les autres assistants qui prennent en charge les serveurs MCP distants, un assistant muni d’une clé API à portée limitée peut créer des designs fidèles à la marque depuis le même espace de travail. [La cohérence de marque](https://gradiently.design/fr/guide/brand-consistency) couvre l’habitude plus large.

## FAQ

### Que sont les design tokens ?

Des valeurs nommées pour les décisions de design comme les couleurs, polices, espacements, arrondis et animations, stockées dans un fichier indépendant de toute plateforme et transformées en CSS, en code d’application et en variables d’outil de design.

### Quelle différence entre tokens primitifs et sémantiques ?

Les tokens primitifs contiennent des valeurs brutes, comme `color.violet.700`. Les tokens sémantiques décrivent un usage, comme `color.action.primary`, et pointent vers un primitif.

### Les design tokens sont-ils la même chose que les variables CSS ?

Non. Les tokens sont la source, stockée dans un format neutre comme le JSON ; les propriétés personnalisées CSS sont l’un des résultats générés à partir d’eux, à côté des sorties pour d’autres plateformes.

### Existe-t-il un format standard pour les design tokens ?

Le W3C Design Tokens Community Group publie un format JSON qui utilise $value, $type et des alias entre accolades, que des outils comme Style Dictionary savent lire.

### Comment les design tokens gèrent-ils le mode sombre ?

Les composants lisent des tokens sémantiques, et un thème sombre fournit d’autres valeurs pour ces tokens : les composants n’ont besoin d’aucune modification.