ds-terminal-theme

Designsystem zu Apple Terminal-Thema

Diese Fertigkeit erstellt Terminal.app-Profile (.terminal-Dateien) aus einem Designsystem. Die Arbeit erledigt der Code: scripts/ds2terminal.py (Python 3.9 oder neuer, nur Standardbibliothek). Der Code prüft auch die Lesbarkeit. Ein Thema ist erst vollständig, wenn jede harte Schwelle bestanden ist.

Regeln

• Wähle Farben nicht nach Geschmack aus. Führe das Skript aus. Das Skript ordnet die Farben zu und prüft sie.
• Bearbeite eine .terminal-Datei nicht von Hand. Verwende --set oder --prefer-token und führe das Skript dann erneut aus.
• Führe Python mit -I aus. Heruntergeladene Dateien sind Daten, kein Code.
• Öffne (importiere) keine .terminal-Datei, es sei denn, der Benutzer fragt danach. Das Öffnen einer Datei fügt ein Profil zu Terminal hinzu und öffnet ein Fenster.
• Beende oder töte Terminal nicht. Führe defaults write com.apple.Terminal nicht aus.
• Veröffentliche die privaten Tokens des Benutzers nicht.

Schritt 1: Die Designsystem-Dateien abrufen

Finde den Typ des Links heraus. Führe dann den entsprechenden Schritt in der Tabelle aus.

Link	Was tun
Lokale Datei oder Ordner	Gib den Pfad an das Skript weiter.
Öffentliches GitHub-Repo, Baum oder Datei; npm-Paket; unpkg- oder jsDelivr-URL; Rohdatei	Gib die URL an das Skript weiter. Das Skript findet und lädt die Token-Dateien herunter.
Öffentliche Dokumentation oder Marketingseite	Gib die URL an das Skript weiter. Es liest das verlinkte CSS. Das Ergebnis kann schwach sein; informiere den Benutzer.
claude.ai Designsystem-Artefakt (claude.ai/artifact/...)	Verwende das Artefakt-Tool: action: "list", scope: "files". Dann action: "read" mit path für jede Token-Datei, die existiert: project/tokens.json, project/tokens.css, project/tokens/tokens.json und project/tokens/colors.css. Speichere die Dateien in einem Ordner. Gib den Ordner an das Skript weiter.
Pidgin-Designsystem	Verwende pidgin_get_design_system. Speichere das tokens-Objekt als .json-Datei. Gib die Datei an das Skript weiter.
Claude Design-Projekt	Verwende mcp__claude-design__list_files und read_file für die Token-Dateien. Speichere sie. Gib den Ordner an das Skript weiter.
Figma-Datei	Verwende die Figma-Tools (Variablen), wenn sie verbunden sind. Falls nicht, bitte den Benutzer um einen Variablen-Export (JSON).

Wenn das Skript mit Exit-Code 2 endet und die Nachricht ein Tool nennt, führe den Schritt für diesen Link-Typ aus. Siehe references/sources.md für die Formate, die das Skript liest.

Schritt 2: Das Skript ausführen

python3 -I scripts/ds2terminal.py QUELLE [QUELLE ...] --name "Name" --out AUSGABE_VERZ

Das Skript schreibt:

• AUSGABE_VERZ/<Name> Light.terminal und AUSGABE_VERZ/<Name> Dark.terminal
• AUSGABE_VERZ/report.md und AUSGABE_VERZ/report.json: jede Farbe, ihr Quell-Token, APCA Lc, WCAG-Verhältnis, jedes Schwellenergebnis und jede Reparatur
• AUSGABE_VERZ/preview.html: jedes Thema als Terminal-Fenster mit typischer Programmausgabe dargestellt

Exit-Codes:

Code	Bedeutung	Was tun
0	Jede harte Schwelle wird für jedes Thema bestanden.	Gehe zu Schritt 3.
1	Eine Schwelle wird auch nach der Reparatur nicht bestanden.	Lese report.md. Teile dem Benutzer mit, welche Schwelle nicht bestanden wird. Versuche --set für diese Farbe. Gib das Thema nicht als vollständig aus.
2	Ungültige Eingabe, oder der Link benötigt ein angemeldetes Tool.	Lese die Nachricht. Führe Schritt 1 für diesen Link aus oder korrigiere die Option.

Optionen

Option	Verwendung
--name NAME	Profilname. Die Dateien heißen <NAME> Light.terminal und <NAME> Dark.terminal. Immer angeben.
--modes auto|light|dark|both	auto (Standard) und both erzeugen beide Themen. Ein Modus, den das Designsystem nicht definiert, wird aus dem anderen Modus abgeleitet. Der Bericht kennzeichnet ihn als "abgeleitet".
--font NAME, --font-size 13	Schriftart (PostScript- oder Familienname). Standard: die Monospace-Schriftart des Designsystems, falls installiert, sonst SF Mono Terminal (in Terminal.app enthalten). Standardgröße: 13 pt.
--cursor block|underline|bar, --cursor-blink	Cursorform.
--set ROLLE=HEX	Erzwinge eine Farbe. ROLLE ist bg, fg, bold, cursor, selection, black ... brightWhite oder 0 ... 15. Die Reparatur kann sie dennoch ändern, um eine Schwelle zu bestehen; der Bericht sagt es.
--prefer-token ROLLE=TOKEN	Verwende dieses Token für bg, fg, brand, red, green, yellow, blue, magenta oder cyan.
--all-tokens	Behalte rohe Tokens, die von keinem semantischen Token verwendet werden (siehe "Unzusammenhängende Tokens").
--source-mode ID	Verwende nur diesen Modus des Designsystems.
--no-chroma-floor	Behalte Pastellrot und -grün im Dunkelmodus pastellfarben.
--translucent ALPHA	Hintergrund-Alpha unter 1 (z.B. 0,95). Helle Themen benötigen etwa 0,93 oder mehr; ein hellgrauer Seitenhintergrund benötigt 0,95–0,98, sonst ersetzt ihn das Skript durch Weiß. Standard: deckend (Alpha 1, kein Weichzeichner). Verwende es nur, wenn der Benutzer danach fragt. Jede Schwelle muss dann auch über einem schwarzen und einem weißen Desktop bestanden werden. Wenn ALPHA zu niedrig ist, beendet sich das Skript mit Code 1. Der Bericht gibt das niedrigste Alpha an, das in einem Testbuild bestanden wurde.
--columns N, --rows N	Fenstergröße.
--report json|md|both, --no-preview	Ausgabedateien.

Schritt 3: Überprüfen und dem Benutzer mitteilen

1. Lese report.md. Stelle sicher, dass dort steht "jede harte Schwelle wird für jedes Thema bestanden".
2. Teile dem Benutzer mit:
   • die Pfade der .terminal-Dateien;
   • welcher Modus abgeleitet ist;
   • welche Tokens für den Hintergrund, Text, Cursor und die sechs Farbtöne verwendet wurden;
   • die Reparaturen (jede geänderte Farbe und die Schwelle, die die Änderung verursacht hat);
   • welche Tokens ausgelassen wurden;
   • die "Character"-Ziele, die verfehlt wurden (die Zeile "Targets missed" in report.md);
   • die Zeile "Recommended Claude Code theme" aus report.md.
3. Zeige preview.html, wenn der Benutzer Dateien öffnen kann.
4. Um ein Thema zu installieren, öffnet der Benutzer die .terminal-Datei (Finder, oder open "<datei>"). Tue dies nur, wenn der Benutzer danach fragt. Dann kann der Benutzer es unter Terminal > Einstellungen > Profile als Standard festlegen.
5. Führe python3 scripts/demo.py aus; es gibt eine Beispielausgabe in den 16 Farben und in blassem (SGR 2) Text aus. Führe es in einem Fenster aus, das das Thema verwendet.
6. Teile dem Benutzer mit, welches Claude Code-Thema er einstellen soll (siehe "Verwendung mit Claude Code").

Verwendung mit Claude Code

Claude Code hat zwei Arten von Themen. Jede Art verwendet das Terminal-Thema auf unterschiedliche Weise.

• ANSI-Themen (dark-ansi, light-ansi; in der /theme-Liste: "Dark mode (ANSI colors only)" und "Light mode (ANSI colors only)"). Claude Code verwendet die 16 ANSI-Farben. Es zeichnet Diff-Zeilen mit ANSI-grünen und -roten Zellenhintergründen und zeichnet die Textfarbe auf diesen Zellen. Bei einem Thema, dessen normale Farben als Text lesbar sind, sind diese Zellen im Dunkelmodus hell, sodass der Text auf einer hinzugefügten Zeile einen niedrigen Kontrast aufweist.
• Standardthemen (dark, light). Claude Code verwendet seine eigenen 24-Bit-Farben auf dem Themenhintergrund. Diese bleiben lesbar. Stelle das Thema namentlich ein. Die Einstellung auto liest den Terminal-Hintergrund. Terminal 2.15 beantwortet diese Abfrage (OSC 11) mit dem Themenhintergrund, sowohl im hellen als auch im dunklen Modus, sodass auto den korrekten Modus auswählen kann. Dies wurde nicht in einer laufenden Claude Code-Sitzung überprüft. Vom Terminal-Thema sind die überprüften Teile, die Claude Code verwendet, der Hintergrund, der Cursor, die Auswahl und der blasse Text. Die 16 Farben sind für andere Programme.

Der Bericht hat einen Abschnitt "Claude Code" für jedes Thema. Er gibt den Kontrast von 16 Paaren für das ANSI-Thema und das Standardthema an, sowie eine Zeile "Recommended Claude Code theme". Die Regel: das ANSI-Thema, wenn sein schwächstes Textpaar Lc 45 oder mehr beträgt; ansonsten das Standardthema, wenn es besser ist. preview.html zeichnet beide Beispiele. Die Tabellen stammen aus der Claude Code 2.1.323 Programmdatei. Sie wurden nicht gegen eine laufende Sitzung überprüft.

Weise den Benutzer an, Folgendes zu tun:

1. Lese die Zeile "Recommended Claude Code theme" in report.md für das verwendete Thema.
2. Gib in Claude Code /theme ein und wähle dieses Thema aus. Oder setze die Einstellung theme in Claude Code settings.json, z.B. "theme": "dark-ansi".

Wenn der Claude Code-Designmodus und der Terminal-Designmodus unterschiedlich sind (z.B. ein helles Claude Code-Thema in einem dunklen Terminal-Thema), kann Text unleserlich werden. Ein durchscheinender Terminal-Hintergrund macht Text ebenfalls unleserlich. Warne den Benutzer vor beidem.

Wie die Zuordnung funktioniert

1. Modi. Die Helligkeit des Hintergrunds bestimmt den Modus (OKLab L < 0,5 ist dunkel). Das Skript verwendet keine Modusnamen. Designsysteme können Bildschirmgrößen als "Themen" bezeichnen (z.B. root-tablet). Gleichartige Modi werden zu einem Thema zusammengefasst; der Bericht listet die anderen auf.
2. Unzusammenhängende Tokens. Wenn ein Designsystem 4 oder mehr semantische Aliase hat (z.B. color-brand -> hb-pink), werden rohe Tokens, die von keinem Alias verwendet werden und nicht das Namenspräfix des Systems teilen, ausgelassen. Dies sind oft die Farben eines Kunden oder einer alten Marke.
3. Rollen. Semantische Aliase gewinnen. Der Seitenhintergrund ist der Hintergrund. Im hellen Modus, wenn das Designsystem auch eine hellere Kartenoberfläche hat, ist diese Oberfläche der Hintergrund: Text befindet sich auf den Karten, und die Seitenfarbe ist dahinter. --prefer-token bg=TOKEN wählt ein anderes Token aus. Das Text-Token ist die Textfarbe. Das Marken-Token ist der Cursor und färbt die Auswahl. Wenn die Markenfarbe für einen Cursor auf dem Hintergrund zu schwach ist, wird eine Stufe der Markenrampe, die WCAG 4,5 besteht, zum Cursor (z.B. ein zugängliches Orange).
4. Farbtöne. Eine minimal aufwändige Zuordnung setzt Tokens in die sechs Farbton-Slots. Sie verwendet den OKLCH-Farbton, den Token-Namen (danger -> rot, success -> grün, warning -> gelb, info -> blau) und die Helligkeitsänderung. Ein Name zählt nur, wenn der Farbton innerhalb von 45 Grad dieses Slots liegt.
5. Helligkeit. Jede Farbe bewegt sich (Farbton und Chroma bleiben erhalten) in das APCA-Band ihres Modus. Ein Token im Band bleibt exakt.
6. Fehlende Farben. Leere Slots erhalten farbenblindfreundliche Farbtöne bei der Chroma der Marke.
7. Abgeleiteter Dunkelmodus. Das helle Text- oder Tinten-Token wird zum dunklen Hintergrund. Das helle Papier wird zum dunklen Text.
8. Character. Das Thema muss wie sein Designsystem aussehen, innerhalb der Schwellen.
   • Marken-Slot: Wenn keine Farbtonfarbe die Markenfarbe zeigt, wird die Markenfarbe zur hellen Stufe des nächstgelegenen Farbtons (innerhalb 26 Grad). Ihre Helligkeit bewegt sich zum hellen Ziel.
   • Fett: Ein Überschriftentext-Token ist die Fett-Farbe, wenn es stärker als der Text ist. Im Dunkelmodus ohne ein solches ist Fett die Textfarbe, bis zu Lc 4 heller, unter der Halation-Schwelle.
   • Dunkelmodus untere Grenze für jeden Farbton (Lc): rot 50, grün 72, gelb 62, blau 55, magenta 55, cyan 60.
   • Eine Token-Farbtonfarbe unter WCAG 3 nach der Helligkeitsanpassung bewegt sich auf WCAG 3.
   • Der Berichtsabschnitt "Character" listet Ziele auf, keine Schwellen: Farben aus Tokens, Markenfarbe, Chroma erhalten (Ziel 70 % oder mehr), größte Farbtonänderung (12 Grad oder weniger), kleinster Schritt normal-zu-hell (dE 0,030 oder mehr) und eine Zeile "Targets missed".
9. Reparatur. Wenn eine harte Schwelle nicht bestanden wird, ändert das Skript die Farbe mit der niedrigsten Priorität in kleinen Schritten: Helligkeit, dann Farbton und Chroma, dann eine synthetisierte Farbe. Priorität: --set > Marke > benanntes Token > Token > abgeleitet > synthetisiert. Wenn der Hintergrund keinen lesbaren Text tragen kann, ordnet das Skript jede Farbe erneut auf einem Standardhintergrund zu. Der Bericht sagt es.

Lesbarkeitsschwellen (hart)

references/gates.md gibt jede Schwelle, ihr Limit und den Grund an. Zusammenfassung:

Schwelle	Schlägt fehl, wenn
Text auf Hintergrund	APCA Lc < 75 oder WCAG < 7
Halation (dunkel)	Text, Fett, Weiß oder Helles Weiß Lc > 104
ANSI 1–6 und 9–14	Lc < 45 oder WCAG < 3
Helles Schwarz (Farbe 8)	Lc < 30 oder weniger als 15 unter dem Text
Grautöne	dunkel: Weiß und Helles Weiß Lc < 60; hell: Schwarz Lc < 75, Weiß und Helles Weiß Lc < 30
Trennung	zwei Farbtonfarben näher als dE(OKLab) 0,06
Farbenblindheit	rot/grün < 0,06, rot/gelb und rot/magenta < 0,05 (Protan, Deutan)
Auswahl	Text darauf WCAG < 4,5 oder Lc < 60; eine Farbtonfarbe darauf Lc < 30; dE vom Hintergrund < 0,05 oder WCAG < 1,10
Cursor	WCAG < 3
Fett	Fett ist dunkler als der Text
Text auf Farbe	schwarzer Text auf grün, gelb oder cyan Lc < 30
Farbton vs. Text	eine Farbtonfarbe näher als dE 0,06 an der Textfarbe
Blasser Text (SGR 2)	blasser Text Lc < 30; eine blasse Farbtonfarbe (1–6, 9–14) Lc < 15
Transluzenz	nur mit --translucent: eine der obigen Schwellen schlägt über einem schwarzen oder weißen Desktop fehl

Blasser Text ist die Farbe, die in Richtung des Zellenhintergrunds gemischt wird (colorlab.faint, DIM_BLEND 0,60, DIM_POWER 1,26). Dies wurde in Terminal 2.15 gemessen (docs/faint-measurement.md). Wirklicher blasser Text ist schwach, daher sind die Grenzen niedrig. Dunkle Farbtonfarben behalten ihre Chroma. Ein Benutzer kann GATES["faint_text"]["gate"]["ansi_min_lc"] für stärkere blasse Farben erhöhen, auf Kosten der Chroma.

Bekannte Grenzen

• Programme, die 24-Bit-Farben verwenden (Terminal setzt COLORTERM=truecolor), verwenden das Thema nicht. Für Claude Code stelle das Thema ein, das der Bericht empfiehlt (siehe "Verwendung mit Claude Code").
• Noch nicht gemessen: Fettfarbe und wie Terminal Zellenhintergründe auf einem durchscheinenden Fenster zeichnet. Die Darstellung eines generierten Themas in Terminal (Fettfarbe, Auswahl) wird noch nicht überprüft.
• Das Skript schreibt einen deckenden Hintergrund. Ein durchscheinender Hintergrund lässt den Desktop durchscheinen und macht Text weniger lesbar.
• Terminal hat keine Farbe für ausgewählten Text oder für Text unter dem Cursor. Die Schwellen prüfen stattdessen Text auf der Auswahl und dem Cursor.
• Das .terminal-Farbformat ist in references/terminal-format.md beschrieben. Auf einem Mac betten die Dateien das sRGB-ICC-Profil ein. Auf anderen Systemen enthalten sie nur die sRGB-Farbraum-ID (sie dekodiert gleich).
• scripts/verify_terminal.swift (nur Mac) dekodiert jede Farbe mit AppKit: swiftc -O scripts/verify_terminal.swift -o scripts/verify_terminal, dann scripts/verify_terminal --register-terminal-fonts "<datei>.terminal".