Écrire son propre thème

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152

# É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)