thème

ultrahand: theme

Construisez le thème d'un projet une fois et faites-le évoluer à partir de là. Le thème est un fichier de jetons de design (design tokens) accompagné d'un court enregistrement de ses décisions, conservé dans le projet, afin que toute conception et révision ultérieure repose sur la même base plutôt que de repartir de zéro. Le format du fichier est décrit dans shared/theme/README.md ; les règles sont dans shared/theme/rules.md, et chaque règle cite shared/theme/sources.md.

Chaque thème respecte les non-négociables (NN-1 à NN-12 : niveaux, grille de 8 points, les deux schémas, contraste, une vraie échelle typographique et le reste) et fait un choix original sur chaque axe créatif (CR-1 à CR-10 : teinte, neutres, voix typographique, coins, profondeur, densité…). Les règles sont fixes pour que chaque thème soit bien conçu ; les axes sont ouverts pour que deux produits ne se ressemblent pas. Lisez rules.md avant de commencer.

Les scripts ci-dessous se trouvent dans ${CLAUDE_PLUGIN_ROOT}/shared/theme/.

1. Trouver ce qui existe

Regardez avant de demander. Pour un design qui n'existe que sous forme d'artefact sur le canevas, listez les fichiers de l'artefact et lisez design/ à partir de là. Dans le projet, recherchez design/THEME.md, *.tokens.json, tokens/, une configuration Style Dictionary, et le code de thème de la plateforme : propriétés personnalisées CSS, tailwind.config.*, Flutter ThemeData / ColorScheme, ressources de couleur SwiftUI, Compose MaterialTheme. Le résultat détermine le mode :

Trouvé	Mode
Un fichier de thème et THEME.md	Évoluer (étape 4). Ne jamais le régénérer.
Pas de fichier de thème, mais du code stylé	Extraire (étape 2), puis évoluer.
Rien (un nouveau produit)	Créer (étape 3).

2. Extraire le thème que le code possède déjà

Le but est de capturer l'apparence actuelle, nettoyée, pas de la reconcevoir.

1. Exécutez node scan.mjs <répertoire src> (ajoutez --json pour les listes complètes). Il liste chaque couleur, valeur d'espacement, rayon et taille de police avec les compteurs et emplacements, regroupe les couleurs quasi-dupliquées et signale les espacements hors grille. Lisez également le code de thème de la plateforme : les valeurs nommées par un objet thème sont les valeurs prévues, et les valeurs brutes dispersées sont les dérives.
2. Nommez les rôles. Pour chaque groupe de couleurs, trouvez à quoi il sert (fond de page, texte du corps, boutons, bordures, erreurs) et associez-le à un rôle sémantique (le README.md liste les rôles requis). Un rôle, une valeur : lorsque deux quasi-duplicatas servent un même rôle, conservez le plus utilisé.
3. Alignez sur les règles. Pliez l'espacement sur l'échelle NN-2, les tailles sur une échelle typographique (NN-6), les rayons sur une courte échelle (NN-7). Corrigez les échecs de contraste en vous déplaçant le long des mêmes palettes tonales d'une teinte (NN-4). Chaque changement est un changement visible pour le produit, donc listez-les sous forme de tableau (13px → 12px, 4 endroits) pour que le propriétaire les approuve, et gardez tout ce qu'il souhaite inchangé.
4. Remplissez les lacunes. La plupart des codes n'ont pas de mode sombre, d'anneau de focus ou de rôles on-. Concevez-les dans la propre palette du thème (NN-3, NN-10) plutôt que d'en ajouter des génériques.
5. Inventoriez les composants. Listez les composants réutilisables (cherchez dans components/, ui/, widgets/, views/), leurs variantes et où chacun est défini. Notez toute tâche effectuée par deux composants différents : c'est un candidat à la fusion (EV-4), pas quelque chose à copier dans le thème.
6. Enregistrez la personnalité qu'il a déjà. Placez l'apparence existante sur chaque axe créatif et écrivez-la dans THEME.md. Les choix imposés par la marque (couleur du logo, polices sous licence) sont locked (verrouillés) ; le reste est open (ouvert).

Ensuite, écrivez les fichiers (étape 5).

3. Créer un nouveau thème

1. Personnalité. Demandez trois adjectifs et à qui il est destiné, ainsi que tout ce qui est fixe : couleurs de la marque, logo, polices, plateforme (les applications iOS ou Android natives s'appuient sur la police et les couleurs système ; le thème se mappe sur elles [HIG-COLOR] [M3-COMPOSE]).
2. Trois directions. Proposez trois directions qui diffèrent sur au moins trois axes créatifs, chacune avec une justification d'une ligne liée aux adjectifs. Évitez l'apparence par défaut décrite dans rules.md sauf si le propriétaire la souhaite. Montrez-les côte à côte (étape 6), et laissez le propriétaire en choisir une ou les mélanger.
3. Construisez-le.
   • Palette : pour chaque couleur clé (primaire, neutre, plus erreur et toute accentuation), une échelle tonale d'environ 10 à 13 étapes du foncé au clair [M3-HCT] [M3-COMPOSE], afin que chaque rôle puisse trouver une étape qui respecte le contraste dans les deux schémas.
   • Couleurs sémantiques : chaque rôle requis, chacun avec sa valeur sombre, chaque on-X conçu par rapport à X.
   • Espace : l'échelle NN-2, puis espacement sémantique par fonction : étapes inset pour le remplissage, et gap-related, gap-group et gap-section afin que la règle de composition selon laquelle les écarts entre les groupes sont nettement plus grands que les écarts à l'intérieur des groupes (SEC-2 dans shared/composition/principles.md) soit intégrée.
   • Typographie : une échelle basée sur le rapport choisi (CR-5), avec les rôles display, headline, title, body, label ; body à la valeur par défaut de la plateforme (16 sur le web, 17 pt sur iOS ; 13–14 uniquement pour un outil de bureau dense, voir NN-6).
   • Forme, profondeur, mouvement, focus : une échelle de rayons dans le style de coin choisi ; des niveaux d'élévation dans la méthode de profondeur choisie ; des jetons de durée et d'assouplissement ; un anneau de focus de 2 px ou plus.
   • Composants : uniquement les jetons de composants dont un composant a besoin pour différer de son rôle (EV-2). La plupart des composants n'en ont besoin d'aucun.

Commencez chaque valeur à la version 1.0.0.

4. Faire évoluer un thème existant

Pour une demande comme « ajouter une couleur d'avertissement », « nous avons besoin d'un tableau plus dense », « rendez-le plus chaleureux », ou une compétence de design ou theme-review proposant des ajouts :

• Lisez d'abord THEME.md et les jetons (EV-1). Respectez les décisions locked ; si la demande nécessite d'en changer une, dites-le et demandez.
• Réutilisez un rôle existant si l'un d'eux convient (EV-2). Ajoutez un jeton uniquement pour une vraie lacune, aliasé sur une étape primitive existante (EV-3).
• Un changement large (« plus chaleureux », « plus ludique ») déplace un axe créatif open : déplacez les primitives, conservez chaque nom sémantique, et réexécutez la vérification du contraste. Les noms restent vrais même lors d'un changement de marque (NN-11).
• Mettez hors service avec $deprecated en nommant le remplacement ; supprimez dans une version ultérieure (EV-6).
• Augmentez la version et ajoutez une ligne dans le journal des modifications indiquant ce qui a changé et quels écrans en avaient besoin (EV-5).

5. Écrire et vérifier

1. Écrivez design/theme.tokens.json (ou l'emplacement existant des jetons du projet) et design/THEME.md, en suivant README.md. example.tokens.json montre la structure.
2. Exécutez node check.mjs design/theme.tokens.json et corrigez chaque erreur. Un avertissement nécessite une correction ou une justification dans THEME.md.
3. Remettez-le au code. Pour le web, node css.mjs design/theme.tokens.json --out <chemin>/theme.css donne des propriétés personnalisées CSS avec le mode sombre intégré. Pour d'autres plateformes, ou plusieurs à la fois, recommandez Style Dictionary, qui lit ce format et écrit en Swift, Android, Compose et Flutter [STYLE-DICT]. Proposez de remplacer les valeurs brutes trouvées par le scan par des jetons ; ne le faites pas sans demander, car cela touche chaque fichier stylé.

6. Montrer le thème

Construisez un spécimen sur le canevas du plugin (shared/canvas/ ; son README contient le contrat) afin que le propriétaire voie le thème en action, pas une liste de codes hexadécimaux :

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 "<Produit> theme" --out index.html

Le screen.html du spécimen utilise uniquement les propriétés personnalisées du thème et montre : les rôles de couleur sous forme de texte on-X sur X avec le rapport mesuré ; l'échelle typographique avec du texte réel ; l'échelle d'espacement ; les niveaux de rayon et d'élévation ; chaque composant inventorié dans ses états ; et un petit écran réaliste (une liste et un formulaire) construit à partir de cela. Les bascules Light / Dark et texte à 200% du canevas testent les deux schémas et le redimensionnement du texte. Si le thème nécessite une police web, placez son <link> dans le même fichier head.

Comparaison des directions (étape 3) : émettez chaque direction sans --style, délimité avec --selector '[data-state="a"]' (puis b, c), et collez-les en haut du propre <style> du template d'écran : le canevas définit data-state à l'intérieur de l'écran, là où l'en-tête de page ne peut pas l'atteindre. Déclarez les états a, b, c dans config.json avec les noms des directions comme étiquettes, et le sélecteur d'état bascule entre eux.

Publiez index.html en tant qu'artefact. Lorsque le design lui-même est un artefact, republiez-le construit avec le thème (--head theme.html) et incluez les deux fichiers design/.

7. Présenter

Partagez le lien de l'artefact. En quelques lignes : le mode (créé, extrait ou évolué), la version, où se situe la personnalité sur les axes créatifs et pourquoi, ce qui est verrouillé et ce qui est ouvert, les éventuels changements d'alignement que le propriétaire doit approuver, le résultat de la vérification, et l'étape suivante : concevoir avec (les compétences mobile, tablet et desktop le lisent), ou auditer le code par rapport à lui avec theme-review.