# Écrire son propre thème

Ce guide montre comment ajouter un thème de couleurs à vous. Il suppose que vous savez où se trouve votre répertoire de configuration et que vous savez éditer un fichier TOML.

## 1. Trouver où vont les thèmes

```bash
turbo-go -list-themes
```

La dernière ligne indique le répertoire — `~/.config/turbo-go/themes` sous Linux, `~/Library/Application Support/turbo-go/themes` sous macOS. Créez-le :

```bash
mkdir -p ~/.config/turbo-go/themes
```

## 2. Partir d'un thème existant

Le plus rapide est d'hériter d'un thème qui fonctionne déjà et de ne redéfinir que ce que vous voulez :

```toml
# ~/.config/turbo-go/themes/mine.toml
name = "Le mien"
description = "Turbo Classic, mais avec des commentaires lisibles."
inherits = "turbo-classic"

[colors]
"syntax.comment" = { fg = "#8a8a8a", italic = true }
"syntax.string"  = { fg = "#87d7af" }
```

Tout ce que vous ne définissez pas est repris de `turbo-classic`.

**Héritez d'un thème dont le fond ressemble au vôtre.** Les couleurs que vous omettez ont été choisies contre le fond du thème dont vous héritez : un thème sombre bâti sur `turbo-classic` affichera, ici et là, une couleur pensée pour le marine Borland. Pour un thème sombre, héritez de `turbo-dark`, `cappuccino`, `catppuccin-frappe`, `cobalt`, `darcula` ou `monochrome-dark` ; pour un thème clair, de `borland-light`, `catppuccin-latte`, `intellij-light` ou `monochrome-light`. C'est aussi pourquoi les onze thèmes livrés dans le binaire énoncent chacun leur palette en entier au lieu d'en hériter l'essentiel — un test les y oblige, parce qu'un thème livré engage le projet.

## 3. L'utiliser

```bash
turbo-go -theme mine main.go
```

Ou depuis l'éditeur : `Options ▸ Theme…`, qui liste tous les thèmes trouvés.

## 4. Itérer

Modifiez le fichier, puis relancez l'éditeur. Il n'y a pas de rechargement à chaud.

Si le thème ne se charge pas, Turbo Go retombe sur le thème par défaut plutôt que de refuser de démarrer. Pour savoir *pourquoi* :

```bash
turbo-go -list-themes
```

Un thème cassé apparaît dans la liste avec l'erreur d'analyse à côté — un nom de couleur inconnu est une erreur, pas un repli silencieux : une faute de frappe est signalée au lieu de repeindre discrètement la moitié de l'écran.

## 5. Vérifier qu'il reste lisible

Le projet soumet chaque thème qu'il livre à cinq règles mesurées, et elles valent pour le vôtre. `make test` les exécute.

| Règle | Pourquoi |
| --- | --- |
| Le curseur est à au moins 64 de la ligne qu'il occupe, dans son canal le plus fort | Le terminal dessine son curseur par-dessus la cellule ; un curseur qui se fond est introuvable |
| Le curseur n'est jamais une simple inversion de cette ligne | Un terminal qui dessine son curseur en inversant la cellule le rendrait invisible |
| La ligne courante est à au moins 16 de la page | `turbo-dark` a un jour utilisé dix, ce qui n'est pas un surlignage |
| Le texte destiné à la lecture est à au moins 64 de son fond | Le mobilier — bureau, ombre, gouttière d'ascenseur, entrée grisée — en est exempt : il est fait pour s'effacer |
| Les commentaires se lisent à 4,5:1 ou mieux sur leur fond, en luminance relative WCAG | Un commentaire est de la prose, lue mot à mot. `turbo-classic` les dessinait en `#808080` sur son bleu marine : 128 valeurs de canal d'écart, donc la règle ci-dessus laissait passer, et 4,05:1 à la lecture, sous le plancher du W3C pour du texte courant. Les commentaires étaient la couleur la plus terne dans six des onze thèmes livrés. |


La règle de contraste s'applique aux six thèmes que ce projet écrit lui-même. Les deux thèmes Catppuccin en sont exemptés, et l'exemption est écrite là où elle est faite : leurs couleurs sont la palette publiée de quelqu'un d'autre, copiée fidèlement, et Catppuccin place les commentaires à 2,87:1 en Frappé et 2,83:1 en Latte. Un thème nommé Catppuccin qui n'aurait pas exactement ces valeurs serait un autre thème portant un nom d'emprunt : le correctif, si quelqu'un en veut un, est en amont.

Elle s'applique aux commentaires et à rien d'autre. `syntax.punctuation` est plus discret encore dans plusieurs thèmes et le reste : la ponctuation se reconnaît à sa forme, elle ne se lit pas.

Une sixième règle attrape l'erreur qu'aucune mesure ne voit : **deux classes syntaxiques que le lecteur rencontre côte à côte ne doivent pas être dessinées à l'identique**. `turbo-classic` a un jour peint `syntax.link` du même vert que `syntax.string` : un lien Markdown et un extrait de code inline devenaient la même chose à l'écran — chaque couleur lisible, chaque clé définie, et les deux simplement égales. Les deux monochromes satisfont cette règle sans aucune teinte, en jouant du gras, de l'italique et du souligné.

## Variantes

**Remplacer un thème livré plutôt que d'en ajouter un.** Donnez à votre fichier le même nom — `turbo-classic.toml` — et c'est le vôtre qui gagne. Le thème embarqué n'est pas remplacé : supprimer votre fichier le fait revenir.

**Partir de zéro.** N'écrivez pas `inherits`. Définissez au moins `default` ; toute clé non définie retombe le long des points jusqu'à lui, si bien qu'un thème d'une seule ligne reste un thème utilisable.

**Ne colorer que la syntaxe.** Une seule clé suffit :

```toml
[colors]
syntax = { fg = "silver" }
```

`syntax.keyword`, `syntax.string` et les autres y retombent toutes.

**Garder les couleurs du terminal.** Utilisez `default` comme valeur :

```toml
[colors]
"editor.text" = { fg = "default", bg = "default" }
```

**L'essayer depuis un clone sans l'installer.** Pointez l'éditeur sur n'importe quel répertoire :

```bash
TURBO_GO_THEME_DIR=./mes-themes turbo-go -theme mine main.go
```

**Le curseur est peu visible.** `editor.cursor` fait deux choses : son **fond** est envoyé au terminal comme couleur de son propre curseur, et il peint aussi la cellule en dessous, en secours pour les terminaux qui ignorent la première. Mettez-la sur quelque chose de criard :

```toml
[colors]
"editor.cursor" = { fg = "#000000", bg = "#ff8700" }
```

Deux choses font une mauvaise couleur de curseur, et la suite de tests les refuse toutes les deux : une simple inversion de la ligne — que les terminaux dessinant leur curseur par inversion ramènent à l'invisibilité — et tout écart de moins de 64 valeurs de canal avec la ligne sur laquelle il se trouve.

**La ligne du curseur est difficile à repérer.** C'est `editor.currentline`, une autre clé. Elle doit s'écarter de `editor.text` d'au moins 16 valeurs de canal pour être un surlignage.

**Le Markdown et le HTML rendent fade.** Cinq clés appartiennent aux langages de balisage et n'ont pas d'équivalent en Go : un thème écrit avant leur existence ne les définit pas.

```toml
[colors]
"syntax.heading"   = { fg = "white", bold = true }
"syntax.tag"       = { fg = "aqua" }
"syntax.attribute" = { fg = "yellow" }
"syntax.emphasis"  = { fg = "fuchsia", bold = true }
"syntax.link"      = { fg = "aqua", underline = true }
```

Donnez à `syntax.link` une couleur différente de `syntax.string` : un lien et un `code` en ligne se côtoient dans presque toute prose, et partager une couleur en fait une bouillie. Le `turbo-classic` livré avait exactement ce défaut jusqu'à ce qu'on le regarde sur un vrai terminal.

**L'arbre du projet est plat.** Il a quatre clés à lui, dont aucune ne se rabat sur `list` :

```toml
[colors]
"tree.text"      = { fg = "silver", bg = "navy" }
"tree.directory" = { fg = "white", bg = "navy", bold = true }
"tree.selected"  = { fg = "black", bg = "aqua" }
"tree.unfocused" = { fg = "black", bg = "gray" }
```

Donnez à `tree.text` le même fond que `window.body`, pour que l'arbre fasse partie de sa fenêtre, et rendez `tree.selected` nettement différent — la suite de tests tient chaque thème livré à au moins 64 valeurs de canal entre les deux, parce qu'un surlignage de la couleur de la page n'est pas un surlignage.

**Les fenêtres terminal rendent mal.** Elles ont deux clés à elles, et aucune ne se rabat sur `editor` :

```toml
[colors]
"terminal.text"   = { fg = "silver", bg = "black" }
"terminal.cursor" = { fg = "black", bg = "aqua" }
```

`terminal.text` est ce que reçoit la sortie d'un shell lorsqu'elle ne nomme aucune couleur — donnez-lui quelque chose de proche d'un vrai terminal plutôt que du fond de votre éditeur, sans quoi `less` et `htop` détonneront. Un programme qui nomme ses couleurs les conserve dans les deux cas.

## Voir aussi

- Toutes les clés définissables et tous les noms de couleurs : [référence du format de thème](../reference/themes.md)
- Pourquoi du TOML avec deux formes d'héritage : [Décisions de conception](../explanation/design-decisions.md)