| 📦 Turbo Go 3d7798b k33g 13h ago | 1 | # Écrire son propre thème |
| 2 | |
| 3 | 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. |
| 4 | |
| 5 | ## 1. Trouver où vont les thèmes |
| 6 | |
| 7 | ```bash |
| 8 | turbo-go -list-themes |
| 9 | ``` |
| 10 | |
| 11 | 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 : |
| 12 | |
| 13 | ```bash |
| 14 | mkdir -p ~/.config/turbo-go/themes |
| 15 | ``` |
| 16 | |
| 17 | ## 2. Partir d'un thème existant |
| 18 | |
| 19 | 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 : |
| 20 | |
| 21 | ```toml |
| 22 | # ~/.config/turbo-go/themes/mine.toml |
| 23 | name = "Le mien" |
| 24 | description = "Turbo Classic, mais avec des commentaires lisibles." |
| 25 | inherits = "turbo-classic" |
| 26 | |
| 27 | [colors] |
| 28 | "syntax.comment" = { fg = "#8a8a8a", italic = true } |
| 29 | "syntax.string" = { fg = "#87d7af" } |
| 30 | ``` |
| 31 | |
| 32 | Tout ce que vous ne définissez pas est repris de `turbo-classic`. |
| 33 | |
| 34 | **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. |
| 35 | |
| 36 | ## 3. L'utiliser |
| 37 | |
| 38 | ```bash |
| 39 | turbo-go -theme mine main.go |
| 40 | ``` |
| 41 | |
| 42 | Ou depuis l'éditeur : `Options ▸ Theme…`, qui liste tous les thèmes trouvés. |
| 43 | |
| 44 | ## 4. Itérer |
| 45 | |
| 46 | Modifiez le fichier, puis relancez l'éditeur. Il n'y a pas de rechargement à chaud. |
| 47 | |
| 48 | 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* : |
| 49 | |
| 50 | ```bash |
| 51 | turbo-go -list-themes |
| 52 | ``` |
| 53 | |
| 54 | 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. |
| 55 | |
| 56 | ## 5. Vérifier qu'il reste lisible |
| 57 | |
| 58 | 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. |
| 59 | |
| 60 | | Règle | Pourquoi | |
| 61 | | --- | --- | |
| 62 | | 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 | |
| 63 | | Le curseur n'est jamais une simple inversion de cette ligne | Un terminal qui dessine son curseur en inversant la cellule le rendrait invisible | |
| 64 | | La ligne courante est à au moins 16 de la page | `turbo-dark` a un jour utilisé dix, ce qui n'est pas un surlignage | |
| 65 | | 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 | |
| 66 | | 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. | |
| 67 | |
| 68 | |
| 69 | 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. |
| 70 | |
| 71 | 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. |
| 72 | |
| 73 | 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é. |
| 74 | |
| 75 | ## Variantes |
| 76 | |
| 77 | **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. |
| 78 | |
| 79 | **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. |
| 80 | |
| 81 | **Ne colorer que la syntaxe.** Une seule clé suffit : |
| 82 | |
| 83 | ```toml |
| 84 | [colors] |
| 85 | syntax = { fg = "silver" } |
| 86 | ``` |
| 87 | |
| 88 | `syntax.keyword`, `syntax.string` et les autres y retombent toutes. |
| 89 | |
| 90 | **Garder les couleurs du terminal.** Utilisez `default` comme valeur : |
| 91 | |
| 92 | ```toml |
| 93 | [colors] |
| 94 | "editor.text" = { fg = "default", bg = "default" } |
| 95 | ``` |
| 96 | |
| 97 | **L'essayer depuis un clone sans l'installer.** Pointez l'éditeur sur n'importe quel répertoire : |
| 98 | |
| 99 | ```bash |
| 100 | TURBO_GO_THEME_DIR=./mes-themes turbo-go -theme mine main.go |
| 101 | ``` |
| 102 | |
| 103 | **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 : |
| 104 | |
| 105 | ```toml |
| 106 | [colors] |
| 107 | "editor.cursor" = { fg = "#000000", bg = "#ff8700" } |
| 108 | ``` |
| 109 | |
| 110 | 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. |
| 111 | |
| 112 | **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. |
| 113 | |
| 114 | **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. |
| 115 | |
| 116 | ```toml |
| 117 | [colors] |
| 118 | "syntax.heading" = { fg = "white", bold = true } |
| 119 | "syntax.tag" = { fg = "aqua" } |
| 120 | "syntax.attribute" = { fg = "yellow" } |
| 121 | "syntax.emphasis" = { fg = "fuchsia", bold = true } |
| 122 | "syntax.link" = { fg = "aqua", underline = true } |
| 123 | ``` |
| 124 | |
| 125 | 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. |
| 126 | |
| 127 | **L'arbre du projet est plat.** Il a quatre clés à lui, dont aucune ne se rabat sur `list` : |
| 128 | |
| 129 | ```toml |
| 130 | [colors] |
| 131 | "tree.text" = { fg = "silver", bg = "navy" } |
| 132 | "tree.directory" = { fg = "white", bg = "navy", bold = true } |
| 133 | "tree.selected" = { fg = "black", bg = "aqua" } |
| 134 | "tree.unfocused" = { fg = "black", bg = "gray" } |
| 135 | ``` |
| 136 | |
| 137 | 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. |
| 138 | |
| 139 | **Les fenêtres terminal rendent mal.** Elles ont deux clés à elles, et aucune ne se rabat sur `editor` : |
| 140 | |
| 141 | ```toml |
| 142 | [colors] |
| 143 | "terminal.text" = { fg = "silver", bg = "black" } |
| 144 | "terminal.cursor" = { fg = "black", bg = "aqua" } |
| 145 | ``` |
| 146 | |
| 147 | `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. |
| 148 | |
| 149 | ## Voir aussi |
| 150 | |
| 151 | - Toutes les clés définissables et tous les noms de couleurs : [référence du format de thème](../reference/themes.md) |
| 152 | - Pourquoi du TOML avec deux formes d'héritage : [Décisions de conception](../explanation/design-decisions.md) |