Thème Terminal à partir d’un système de design

Système de design vers thème Apple Terminal

Cette compétence crée des profils Terminal.app (fichiers .terminal) à partir d’un système de design. Le code fait le travail : scripts/ds2terminal.py (Python 3.9 ou ultérieur, bibliothèque standard uniquement). Le code vérifie aussi la lisibilité. Un thème n’est complet que lorsque toutes les portes strictes passent.

Règles

• Ne choisissez pas les couleurs selon votre goût. Exécutez le script. Le script mappe les couleurs et les vérifie.
• Ne modifiez pas un fichier .terminal à la main. Utilisez --set ou --prefer-token, puis relancez le script.
• Exécutez Python avec -I. Les fichiers téléchargés sont des données, pas du code.
• N’ouvrez pas (n’importez pas) un fichier .terminal sauf si l’utilisateur le demande. Ouvrir un fichier ajoute un profil à Terminal et ouvre une fenêtre.
• Ne quittez pas et ne tuez pas Terminal. N’exécutez pas defaults write com.apple.Terminal.
• Ne publiez pas les tokens privés de l’utilisateur.

Étape 1 : Récupérer les fichiers du système de design

Identifiez le type du lien. Puis effectuez l’étape correspondante dans le tableau.

Lien	Action
Fichier ou dossier local	Donnez le chemin au script.
Dépôt GitHub public, arborescence ou fichier ; paquet npm ; URL unpkg ou jsDelivr ; fichier brut	Donnez l’URL au script. Le script trouve et télécharge les fichiers de tokens.
Documentation publique ou page marketing	Donnez l’URL au script. Il lit le CSS lié. Le résultat peut être faible ; informez l’utilisateur.
Artifact claude.ai Design System (claude.ai/artifact/...)	Utilisez l’outil Artifact : action: "list", scope: "files". Puis action: "read" avec path pour chaque fichier de tokens existant : project/tokens.json, project/tokens.css, project/tokens/tokens.json et project/tokens/colors.css. Enregistrez les fichiers dans un seul dossier. Donnez le dossier au script.
Système de design Pidgin	Utilisez pidgin_get_design_system. Enregistrez son objet tokens sous forme de fichier .json. Donnez le fichier au script.
Projet Claude Design	Utilisez mcp__claude-design__list_files et read_file pour les fichiers de tokens. Enregistrez-les. Donnez le dossier au script.
Fichier Figma	Utilisez les outils Figma (variables) lorsqu’ils sont connectés. Sinon, demandez à l’utilisateur une exportation de variables (JSON).

Si le script s’arrête avec le code de sortie 2 et que le message nomme un outil, effectuez l’étape pour ce type de lien. Consultez references/sources.md pour les formats lus par le script.

Étape 2 : Exécuter le script

python3 -I scripts/ds2terminal.py SOURCE [SOURCE ...] --name "Nom" --out DOSSIER_SORTIE

Le script écrit :

• DOSSIER_SORTIE/<Nom> Light.terminal et DOSSIER_SORTIE/<Nom> Dark.terminal
• DOSSIER_SORTIE/report.md et DOSSIER_SORTIE/report.json : chaque couleur, son token source, APCA Lc, ratio WCAG, résultat de chaque porte, et chaque réparation
• DOSSIER_SORTIE/preview.html : chaque thème représenté comme une fenêtre Terminal avec des sorties de programmes typiques

Codes de sortie :

Code	Signification	Action
0	Toutes les portes strictes passent pour tous les thèmes.	Passez à l’étape 3.
1	Une porte échoue encore après réparation.	Lisez report.md. Dites à l’utilisateur quelle porte échoue. Essayez --set pour cette couleur. Ne donnez pas le thème comme complet.
2	Entrée incorrecte, ou le lien nécessite un outil connecté.	Lisez le message. Effectuez l’étape 1 pour ce lien, ou corrigez l’option.

Options

Option	Utilisation
--name NOM	Nom du profil. Les fichiers sont <NOM> Light.terminal et <NOM> Dark.terminal. Donnez-le toujours.
`--modes auto	light
--font NOM, --font-size 13	Police (nom PostScript ou famille). Par défaut : la police monospace du système de design si elle est installée, sinon SF Mono Terminal (incluse dans Terminal.app). Taille par défaut : 13 pt.
`--cursor block	underline
--set ROLE=HEX	Forcer une couleur. ROLE est bg, fg, bold, cursor, selection, black ... brightWhite, ou 0 ... 15. La réparation peut encore la modifier pour passer une porte ; le rapport le dit.
--prefer-token ROLE=TOKEN	Utiliser ce token pour bg, fg, brand, red, green, yellow, blue, magenta ou cyan.
--all-tokens	Conserver les tokens bruts qu’aucun token sémantique n’utilise (voir « Tokens non liés »).
--source-mode ID	Utiliser uniquement ce mode du système de design.
--no-chroma-floor	Garder les pastels rouges et verts pastel en mode sombre.
--translucent ALPHA	Alpha du fond inférieur à 1 (ex. 0.95). Les thèmes clairs nécessitent environ 0.93 ou plus ; un fond de page gris clair nécessite 0.95-0.98, sinon le script le remplace par du blanc. Par défaut : opaque (alpha 1, pas de flou). Utilisez-le uniquement lorsque l’utilisateur le demande. Chaque porte doit alors aussi passer sur un bureau noir et un bureau blanc. Si ALPHA est trop faible, le script se termine avec le code 1. Le rapport donne l’alpha le plus bas qui a passé dans une construction de test.
--columns N, --rows N	Taille de la fenêtre.
`--report json	md

Étape 3 : Vérifier et informer l’utilisateur

1. Lisez report.md. Assurez-vous qu’il dit « toutes les portes strictes passent pour tous les thèmes ».
2. Dites à l’utilisateur :
   • les chemins des fichiers .terminal ;
   • quel mode est dérivé ;
   • quels tokens ont été utilisés pour le fond, le texte, le curseur et les six teintes ;
   • les réparations (chaque couleur modifiée et la porte qui a causé la modification) ;
   • les tokens qui ont été omis ;
   • les cibles « Character » manquées (la ligne « Targets missed » dans report.md) ;
   • la ligne « Recommended Claude Code theme » de report.md.
3. Montrez preview.html si l’utilisateur peut ouvrir des fichiers.
4. Pour installer un thème, l’utilisateur ouvre le fichier .terminal (Finder, ou open "<fichier>"). Ne le faites que lorsque l’utilisateur le demande. Ensuite, l’utilisateur peut le définir comme défaut dans Terminal > Réglages > Profils.
5. python3 scripts/demo.py affiche un exemple de sortie dans les 16 couleurs, et en texte faible (SGR 2). Exécutez-le dans une fenêtre qui utilise le thème.
6. Dites à l’utilisateur quel thème Claude Code définir (voir « Utilisation avec Claude Code »).

Utilisation avec Claude Code

Claude Code a deux sortes de thèmes. Chaque sorte utilise le thème Terminal différemment.

• Thèmes ANSI (dark-ansi, light-ansi ; dans la liste /theme : « Dark mode (ANSI colors only) » et « Light mode (ANSI colors only) »). Claude Code utilise les 16 couleurs ANSI. Il dessine les lignes de diff avec des fonds de cellule ANSI vert et rouge, et il dessine la couleur du texte sur ces cellules. Sur un thème dont les couleurs normales sont lisibles comme texte, ces cellules sont claires en mode sombre, donc le texte sur une ligne ajoutée a un faible contraste.
• Thèmes standard (dark, light). Claude Code utilise ses propres couleurs 24 bits sur le fond du thème. Celles-ci restent lisibles. Définissez le thème par son nom. Le réglage auto lit le fond du terminal. Terminal 2.15 répond à cette requête (OSC 11) avec le fond du thème, en mode clair et en mode sombre, donc auto peut sélectionner le bon mode. Cela n’a pas été vérifié dans une session Claude Code en cours. Parmi le thème Terminal, les parties vérifiées que Claude Code utilise sont le fond, le curseur, la sélection et le texte faible. Les 16 couleurs sont destinées aux autres programmes.

Le rapport a une section « Claude Code » pour chaque thème. Elle donne le contraste de 16 paires pour le thème ANSI et pour le thème standard, et une ligne « Recommended Claude Code theme ». La règle : le thème ANSI lorsque sa paire de texte la plus faible est Lc 45 ou plus ; sinon le thème standard lorsqu’il est meilleur. preview.html dessine les deux échantillons. Les tableaux proviennent du fichier programme Claude Code 2.1.323. Ils n’ont pas été vérifiés sur une session en cours.

Dites à l’utilisateur de faire ceci :

1. Lire la ligne « Recommended Claude Code theme » dans report.md pour le thème utilisé.
2. Dans Claude Code, tapez /theme et sélectionnez ce thème. Ou définissez le réglage theme dans settings.json de Claude Code, par exemple "theme": "dark-ansi".

Si le mode du thème Claude Code et le mode du thème Terminal sont différents (par exemple un thème Claude Code clair dans un thème Terminal sombre), le texte peut devenir illisible. Un fond Terminal translucide rend également le texte illisible. Avertissez l’utilisateur des deux cas.

Comment fonctionne le mappage

1. Modes. La luminosité du fond détermine le mode (OKLab L < 0.5 est sombre). Le script n’utilise pas les noms de modes. Les systèmes de design peuvent appeler les tailles d’écran « thèmes » (par exemple root-tablet). Les modes du même type deviennent un thème ; le rapport liste les autres.
2. Tokens non liés. Lorsqu’un système de design a 4 alias sémantiques ou plus (par exemple color-brand -> hb-pink), les tokens bruts qu’aucun alias n’utilise et qui ne partagent pas le préfixe de nom du système sont omis. Ce sont souvent les couleurs d’un client ou d’une ancienne marque.
3. Rôles. Les alias sémantiques l’emportent. Le fond de page est le fond. En mode clair, lorsque le système de design a aussi une surface de carte plus claire, cette surface est le fond : le texte est sur les cartes, et la couleur de la page est derrière elles. --prefer-token bg=TOKEN sélectionne un autre token. Le token du corps du texte est la couleur du texte. Le token de la marque est le curseur et teinte la sélection. Lorsque la couleur de la marque est trop faible pour un curseur sur le fond, un palier du dégradé de la marque qui passe WCAG 4.5 est le curseur (par exemple un orange accessible).
4. Teintes. Une affectation à coût minimum place les tokens dans les six emplacements de teinte. Elle utilise la teinte OKLCH, le nom du token (danger -> rouge, succès -> vert, avertissement -> jaune, info -> bleu) et le changement de luminosité. Un nom ne compte que lorsque la teinte est à moins de 45 degrés de cet emplacement.
5. Luminosité. Chaque couleur se déplace (teinte et chroma conservés) dans la bande APCA de son mode. Un token dans la bande reste exact.
6. Couleurs manquantes. Les emplacements vides reçoivent des teintes adaptées aux daltoniens au chroma de la marque.
7. Mode sombre dérivé. Le token d’encre ou de texte clair devient le fond sombre. Le papier clair devient le texte sombre.
8. Character. Le thème doit ressembler à son système de design, à l’intérieur des portes.
   • Emplacement de la marque : lorsqu’aucune couleur de teinte ne montre la couleur de la marque, la couleur de la marque devient le palier clair de la teinte la plus proche (à moins de 26 degrés). Sa luminosité se déplace vers la cible claire.
   • Gras : un token de texte de titre est la couleur grasse lorsqu’elle est plus forte que le texte. En mode sombre sans un tel token, le gras est la couleur du texte, jusqu’à Lc 4 plus clair, sous la porte d’halation.
   • Bord bas du mode sombre pour chaque teinte (Lc) : rouge 50, vert 72, jaune 62, bleu 55, magenta 55, cyan 60.
   • Une couleur de teinte de token en dessous de WCAG 3 après l’ajustement de luminosité se déplace vers WCAG 3.
   • La section « Character » du rapport liste les cibles, pas les portes : couleurs des tokens, couleur de la marque, chroma conservé (cible 70 % ou plus), plus grand changement de teinte (12 degrés ou moins), plus petit pas normal-vers-clair (dE 0.030 ou plus), et une ligne « Targets missed ».
9. Réparation. Si une porte stricte échoue, le script modifie la couleur de la priorité la plus basse, par petits pas : luminosité, puis teinte et chroma, puis une couleur synthétisée. Priorité : --set > marque > token nommé > token > dérivé > synthétisé. Si le fond ne peut pas porter un texte lisible, le script mappe à nouveau chaque couleur sur un fond standard. Le rapport le dit.

Portes de lisibilité (strictes)

references/gates.md donne chaque porte, sa limite et la raison. Résumé :

Porte	Échoue quand
Texte sur fond	APCA Lc < 75 ou WCAG < 7
Halation (sombre)	texte, gras, blanc ou blanc brillant Lc > 104
ANSI 1-6 et 9-14	Lc < 45 ou WCAG < 3
Noir brillant (couleur 8)	Lc < 30, ou moins de 15 en dessous du texte
Gris	sombre : blanc et blanc brillant Lc < 60 ; clair : noir Lc < 75, blanc et blanc brillant Lc < 30
Séparation	deux couleurs de teinte plus proches que dE(OKLab) 0.06
Daltonisme	rouge/vert < 0.06, rouge/jaune et rouge/magenta < 0.05 (protan, deutan)
Sélection	texte dessus WCAG < 4.5 ou Lc < 60 ; une couleur de teinte dessus Lc < 30 ; dE du fond < 0.05 ou WCAG < 1.10
Curseur	WCAG < 3
Gras	le gras est plus terne que le texte
Texte sur couleur	texte noir sur vert, jaune ou cyan Lc < 30
Teinte vs texte	une couleur de teinte plus proche que dE 0.06 de la couleur du texte
Texte faible (SGR 2)	texte faible Lc < 30 ; une couleur de teinte faible (1-6, 9-14) Lc < 15
Translucidité	seulement avec --translucent : une porte ci-dessus échoue sur un bureau noir ou blanc

Le texte faible est la couleur mélangée vers le fond de cellule (colorlab.faint, DIM_BLEND 0.60, DIM_POWER 1.26). Cela a été mesuré dans Terminal 2.15 (docs/faint-measurement.md). Le vrai texte faible est faible, donc les limites sont basses. Les couleurs de teinte sombres conservent leur chroma. Un utilisateur peut augmenter GATES["faint_text"]["gate"]["ansi_min_lc"] pour des couleurs faibles plus fortes, au détriment du chroma.

Limites connues

• Les programmes qui utilisent la couleur 24 bits (Terminal définit COLORTERM=truecolor) n’utilisent pas le thème. Pour Claude Code, définissez le thème que le rapport recommande (voir « Utilisation avec Claude Code »).
• Pas encore mesuré : la couleur grasse, et comment Terminal dessine les fonds de cellule sur une fenêtre translucide. Le rendu d’un thème généré dans Terminal (couleur grasse, sélection) n’est pas encore vérifié.
• Le script écrit un fond opaque. Un fond translucide laisse le bureau apparaître et rend le texte moins lisible.
• Terminal n’a pas de couleur pour le texte sélectionné ni pour le texte sous le curseur. Les portes vérifient le texte sur la sélection et le curseur à la place.
• Le format de couleur .terminal est dans references/terminal-format.md. Sur un Mac, les fichiers intègrent le profil ICC sRGB. Sur d’autres systèmes, ils contiennent uniquement l’ID d’espace colorimétrique sRGB (il décode de la même manière).
• scripts/verify_terminal.swift (Mac uniquement) décode chaque couleur avec AppKit : swiftc -O scripts/verify_terminal.swift -o scripts/verify_terminal, puis scripts/verify_terminal --register-terminal-fonts "<fichier>.terminal".