theme

ultrahand: theme

Erstelle das Theme eines Projekts einmalig und entwickle es von da an weiter. Das Theme besteht aus einer Design-Token-Datei und einer kurzen Aufzeichnung seiner Entscheidungen, die im Projekt gespeichert werden, sodass jedes spätere Design und jede Überprüfung auf derselben Grundlage aufbaut, anstatt ein neues Erscheinungsbild zu beginnen. Das Dateiformat ist in shared/theme/README.md beschrieben; die Regeln sind in shared/theme/rules.md festgelegt, und jede Regel verweist auf shared/theme/sources.md.

Jedes Theme behält die Nicht-Verhandelbaren (NN-1 bis NN-12: Ebenen, das 8-Punkt-Raster, beide Farbschemata, Kontrast, eine echte Schriftskala und der Rest) und trifft eine neue Wahl auf jeder kreativen Achse (CR-1 bis CR-10: Farbton, Neutrale, Schrift-Charakter, Ecken, Tiefe, Dichte …). Die Regeln sind fest, damit sich jedes Theme hochwertig anfühlt; die Achsen sind offen, damit keine zwei Produkte gleich aussehen. Lies rules.md, bevor du beginnst.

Die folgenden Skripte befinden sich in ${CLAUDE_PLUGIN_ROOT}/shared/theme/.

1. Finde heraus, was existiert

Sieh nach, bevor du fragst. Für ein Design, das nur als Leinwand-Artefakt existiert, liste die Dateien des Artefakts auf und lies design/ von dort. Suche im Projekt nach design/THEME.md, *.tokens.json, tokens/, einer Style-Dictionary-Konfiguration und dem plattformspezifischen Theme-Code: CSS Custom Properties, tailwind.config.*, Flutter ThemeData / ColorScheme, SwiftUI-Farb-Assets, Compose MaterialTheme. Das Ergebnis bestimmt den Modus:

Gefunden	Modus
Eine Theme-Datei und THEME.md	Weiterentwickeln (Schritt 4). Nie neu generieren.
Keine Theme-Datei, aber gestylter Code	Extrahieren (Schritt 2), dann weiterentwickeln.
Nichts (ein neues Produkt)	Erstellen (Schritt 3).

2. Extrahiere das Theme, das der Code bereits hat

Das Ziel ist es, das aktuelle Erscheinungsbild bereinigt zu erfassen, nicht es neu zu gestalten.

1. Führe node scan.mjs <src dir> aus (füge --json für die vollständigen Listen hinzu). Es listet jede Farbe, jeden Abstandswert, Radius und jede Schriftgröße mit Anzahl und Fundorten auf, gruppiert nahezu identische Farben und markiert vom Raster abweichende Abstände. Lies auch den plattformspezifischen Theme-Code: Die Werte, die ein Theme-Objekt benennt, sind die beabsichtigten, und die verstreuten Rohwerte sind die Abweichungen.
2. Benenne die Rollen. Finde für jedes Farbcluster heraus, wofür es verwendet wird (Seitenhintergrund, Fließtext, Schaltflächen, Ränder, Fehler) und ordne es einer semantischen Rolle zu (README.md listet die erforderlichen). Eine Rolle, ein Wert: Wenn zwei nahezu identische Werte eine Rolle bedienen, behalte den häufiger verwendeten.
3. Passe an die Regeln an. Falte Abstände auf die NN-2-Skala, Größen auf eine Schriftskala (NN-6), Radien auf eine kurze Skala (NN-7). Behebe Kontrastfehler, indem du dich entlang der Farbtonschritte desselben Farbtons bewegst (NN-4). Jede Änderung ist eine sichtbare Änderung am Produkt, also liste sie als Tabelle auf (13px → 12px, an 4 Stellen), damit der Eigentümer sie genehmigen kann, und behalte alles bei, was er unverändert lassen möchte.
4. Fülle die Lücken. Die meiste Codebasis hat keinen Dark Mode, keinen Fokusring und keine on--Rollen. Gestalte sie in der eigenen Palette des Themes (NN-3, NN-10), anstatt generische hinzuzufügen.
5. Inventarisiere die Komponenten. Liste die wiederverwendbaren Komponenten auf (suche in components/, ui/, widgets/, views/), ihre Varianten und wo jede definiert ist. Notiere jede Aufgabe, die von zwei verschiedenen Komponenten erledigt wird: Es ist ein Kandidat für eine Zusammenlegung (EV-4), nicht etwas, das in das Theme kopiert werden muss.
6. Halte die bereits vorhandene Persönlichkeit fest. Platziere das bestehende Erscheinungsbild auf jeder kreativen Achse und schreibe es in THEME.md. Von der Marke vorgegebene Entscheidungen (Logo-Farbton, lizenzierte Schriftarten) sind locked; der Rest ist open.

Schreibe dann die Dateien (Schritt 5).

3. Erstelle ein neues Theme

1. Persönlichkeit. Frage nach drei Adjektiven und für wen es bestimmt ist, plus allem Festgelegten: Markenfarben, Logo, Schriftarten, Plattform (native iOS- oder Android-Apps stützen sich auf die Systemschriftart und -farben; das Theme wird darauf abgebildet [HIG-COLOR] [M3-COMPOSE]).
2. Drei Richtungen. Schlage drei Richtungen vor, die sich in mindestens drei kreativen Achsen unterscheiden, jede mit einer einzeiligen Begründung, die mit den Adjektiven verknüpft ist. Halte dich von dem Standard-Look fern, den rules.md beschreibt, es sei denn, der Eigentümer wünscht ihn. Zeige sie nebeneinander (Schritt 6) und lass den Eigentümer eine auswählen oder mischen.
3. Baue es.
   • Palette: für jede Schlüsselfarbe (Primärfarbe, Neutral, plus Fehler und jede Akzentfarbe) eine Tonskala von etwa 10–13 Schritten von dunkel bis hell [M3-HCT] [M3-COMPOSE], sodass jede Rolle einen Schritt finden kann, der den Kontrast in beiden Farbschemata erfüllt.
   • Semantische Farben: jede erforderliche Rolle, jeweils mit ihrem Dunkelwert, jedes on-X gegen X entworfen.
   • Abstände: die NN-2-Skala, dann semantische Abstände nach Aufgabe: inset-Schritte für Innenabstände und gap-related, gap-group und gap-section, sodass die Kompositionsregel, dass Lücken zwischen Gruppen deutlich größer sind als Lücken innerhalb von Gruppen (SEC-2 in shared/composition/principles.md), eingebaut ist.
   • Typografie: eine Skala aus dem gewählten Verhältnis (CR-5), mit den Rollen Display, Headline, Title, Body, Label; Body in der Standardgröße der Plattform (16 im Web, 17 pt auf iOS; 13–14 nur für ein dichtes Desktop-Tool, siehe NN-6).
   • Form, Tiefe, Bewegung, Fokus: eine Radius-Skala im gewählten Eckenstil; Höhenstufen in der gewählten Tiefenmethode; Dauer- und Easing-Token; ein Fokusring von 2 px oder mehr.
   • Komponenten: nur die Komponenten-Tokens, die eine Komponente benötigt, um sich von ihrer Rolle zu unterscheiden (EV-2). Die meisten Komponenten benötigen keine.

Beginne jeden Wert mit Version 1.0.0.

4. Entwickle ein bestehendes Theme weiter

Für eine Anfrage wie „füge eine Warnfarbe hinzu“, „wir brauchen eine dichtere Tabelle“, „mach es wärmer“ oder einen Design-Skill oder theme-review, der Ergänzungen vorschlägt:

• Lies zuerst THEME.md und die Tokens (EV-1). Respektiere locked-Entscheidungen; wenn die Anfrage eine Änderung einer solchen Entscheidung erfordert, sage dies und frage nach.
• Verwende eine vorhandene Rolle wieder, wenn eine passt (EV-2). Füge nur für eine echte Lücke einen Token hinzu, der auf einen vorhandenen primitiven Schritt abgebildet ist (EV-3).
• Eine weitreichende Änderung („wärmer“, „verspielter“) verschiebt eine open kreative Achse: Verschiebe die Primitiven, behalte jeden semantischen Namen bei und führe die Kontrastprüfung erneut durch. Namen bleiben auch bei einem Marken-Rebranding gültig (NN-11).
• Kennzeichne als veraltet mit $deprecated und nenne den Ersatz; entferne in einer späteren Version (EV-6).
• Erhöhe die Version und füge eine Changelog-Zeile hinzu, die sagt, was sich geändert hat und welche Bildschirme es betraf (EV-5).

5. Schreiben und prüfen

1. Schreibe design/theme.tokens.json (oder den vorhandenen Token-Speicherort des Projekts) und design/THEME.md gemäß README.md. example.tokens.json zeigt die Struktur.
2. Führe node check.mjs design/theme.tokens.json aus und behebe jeden Fehler. Eine Warnung erfordert eine Behebung oder einen Grund in THEME.md.
3. Übergib es an den Code. Für das Web gibt node css.mjs design/theme.tokens.json --out <path>/theme.css CSS Custom Properties mit integriertem Dark Mode aus. Für andere Plattformen oder mehrere gleichzeitig empfehle Style Dictionary, das dieses Format liest und Swift, Android, Compose und Flutter ausgibt [STYLE-DICT]. Biete an, die vom Scan gefundenen Rohwerte durch Tokens zu ersetzen; tue dies nicht ohne Nachfrage, da es jede gestylte Datei betrifft.

6. Zeige das Theme

Erstelle ein Muster auf der Plugin-Leinwand (shared/canvas/; dessen README enthält den Vertrag), damit der Eigentümer das Theme in Aktion sieht, nicht nur eine Liste von Hex-Codes:

node "${CLAUDE_PLUGIN_ROOT}/shared/theme/css.mjs" design/theme.tokens.json --style --out theme.html
node "${CLAUDE_PLUGIN_ROOT}/shared/canvas/build.mjs" \
  --presets "${CLAUDE_PLUGIN_ROOT}/skills/desktop/references/presets.md" \
  --head theme.html --screen screen.html --title "<Produkt> Theme" --out index.html

Das Muster screen.html verwendet nur die Custom Properties des Themes und zeigt: Farbrollen als on-X-Text auf X mit dem gemessenen Verhältnis; die Schriftskala mit echtem Text; die Abstandsskala; Radius- und Höhenstufen; jede inventarisierte Komponente in ihren Zuständen; und einen kleinen realistischen Bildschirm (eine Liste und ein Formular), der daraus erstellt wurde. Die Leinwand-Umschalter für Hell / Dunkel und 200 % Text testen beide Farbschemata und Textskalierung. Wenn das Theme eine Webschriftart benötigt, setze ihren <link> in dieselbe Kopfdatei.

Richtungen vergleichen (Schritt 3): gib jede Richtung ohne --style aus, mit Gültigkeitsbereich über --selector '[data-state="a"]' (dann b, c), und füge sie oben in das eigene <style> der Bildschirmvorlage ein: Die Leinwand setzt data-state innerhalb des Bildschirms, wo der Seitenkopf nicht hinkommt. Deklariere states a, b, c in config.json mit den Richtungsnamen als Labels, und der Zustandsauswähler wechselt zwischen ihnen.

Veröffentliche index.html als Artefakt. Wenn das Design selbst ein Artefakt ist, veröffentliche es neu, erstellt mit dem Theme (--head theme.html), und füge die beiden design/-Dateien hinzu.

7. Präsentieren

Teile den Artefakt-Link. In ein paar Zeilen: der Modus (erstellt, extrahiert oder weiterentwickelt), die Version, wo die Persönlichkeit auf den kreativen Achsen sitzt und warum, was locked und was open ist, alle Änderungen durch die Anpassung an Regeln, die der Eigentümer genehmigen muss, das Prüfergebnis und der nächste Schritt: damit entwerfen (die Skills mobile, tablet und desktop lesen es) oder den Code dagegen prüfen mit theme-review.