Thèmes d'interface

Une interface (Classique, Slant, Cabinet…) est un thème : un dossier simple, lu sur disque comme les mods et les skins, qu'on supprime pour le retirer. Le joueur choisit son thème dans Skins → Interface (réglage uiTheme, l'identifiant du thème).

Pourquoi des données et pas du code

Les scripts n'ont jamais accès au DOM, au CSS ni au JavaScript de la WebView, et toute valeur qui entre dans la page est validée en Rust (AGENTS.md). Un thème est donc de la donnée : un manifeste, un fichier de jetons (un sous-ensemble strict de CSS) et des images. Le crate themes (crates/themes) valide tout contre un contrat de jetons typés, puis l'hôte publie à la page l'événement interfaces avec les seules valeurs qui ont passé. La page les pose comme variables CSS sous [data-direction="<id>"]. Le CSS structurel (plaques, boutons, onglets, liste, graphes) reste dans l'application et ne lit que ces jetons : un thème tiers restyle toute l'interface sans balisage ni script, et ne peut rien exécuter ni rien charger.

Où sont les thèmes

Ordre de recherche : themes/ à côté de prism.exe (en développement : le dossier themes/ du dépôt, trouvé en remontant jusqu'à Cargo.lock), puis <data>/themes (PRISM_THEMES_DIR change ce dossier). Le même identifiant deux fois : le premier gagne, le second est signalé. Chaque dossier s'appelle comme son identifiant (minuscules, chiffres, tirets, 32 caractères au plus).

themes/<id>/
  theme.json     le manifeste
  tokens.css     les jetons
  preview.png    (facultatif) aperçu ; sans lui, la carte du sélecteur est dessinée avec les jetons
  images/…       (facultatif) images citées par les jetons de type image

theme.json

tokens.css

Un bloc :root { --pv-x: valeur; … } et jusqu'à deux blocs @media (max-width: <n>px) { :root { … } } pour les fenêtres étroites (320 à 4000 px). Rien d'autre : aucun autre sélecteur, propriété, @import, @font-face, imbrication, url(), expression, var() hors couleurs. Les commentaires /* … */ sont permis. Limites : 64 Kio par fichier, 200 déclarations, 600 caractères par valeur, images de 4 Mio au plus. Un jeton absent garde la valeur neutre de l'application : un thème peut être partiel. Un fichier refusé retire son thème de la liste, avec un message précis (numéro de ligne, jeton, raison) dans le journal.

Le contrat des jetons

Types de valeurs :

• color : couleur : #rgb, #rrggbb, #rrggbbaa, rgb() / rgba() / hsl() / hsla() (nombres, syntaxe virgules ou espaces avec / alpha), color-mix(in srgb, <couleur> [n%], <couleur> [n%]), transparent, white, black, et var(--pv-<jeton couleur>) (la seule référence permise, vers un autre jeton de type couleur, par exemple l'accent).
• length : longueur : nombre + px, em, rem, %, vw, vh, vmin, vmax (ou 0), clamp(a, b, c), min(a, b), max(a, b).
• font : pile de polices : 1 à 8 familles (noms entre guillemets ou mots simples : lettres, chiffres, espaces, ., _, -), la dernière une famille générique (sans-serif, serif, monospace, system-ui, ui-monospace, cursive) ; PrismLegacy est la police du jeu.
• weight : graisse : entier de 1 à 1000.
• opacity : nombre de 0 à 1.
• easing : ease, ease-in, ease-out, ease-in-out, linear ou cubic-bezier(x1, y1, x2, y2) (x de 0 à 1, y de -4 à 4).
• clip : forme : none, polygon(x y, …) (3 à 16 points, coordonnées en longueurs ou calc(<n>% ± <n>px)) ou inset(1 à 4 décalages [round 1 à 4 rayons]).
• layers : dégradés : none ou 1 à 4 linear-gradient(…) / repeating-linear-gradient(…) séparés par des virgules (angle 90deg ou to right, 2 à 12 arrêts : couleur + 0 à 2 positions).
• filter : filtre : none ou jusqu'à 6 fonctions parmi saturate, brightness, contrast, grayscale, sepia, opacity, hue-rotate(<n>deg), blur(≤ 12px).
• image : image : none ou image("chemin/relatif.png") (un fichier image du dossier du thème : png, jpg, webp, gif, svg).
• case : none, uppercase, lowercase ou capitalize.
• scheme : dark ou light.
• choice : un mot pris dans la liste du jeton (voir « Choix de mise en page »). Tout autre mot, plusieurs mots, une valeur vide, un nombre ou un var() sont refusés.

Choix de mise en page

Un thème peut changer la construction des menus, toujours comme des données : un jeton de type choice prend un mot dans une liste fermée (vérifiée par Rust, puis par la page). La page pose chaque choix valide en attribut data-layout-<nom> sur <html> ; les feuilles de style de l'application (theme/layout.css et les composants) y réagissent avec grid-template-areas, order et des variables. Un thème ne fournit aucun sélecteur ni aucun CSS : seulement ces mots. Le premier mot de chaque liste est la mise en page actuelle : un choix omis (ou refusé) vaut ce mot, donc un thème qui n'en dit rien ne change rien.

Graphe de progression du replay

Le graphe de progression (combo, précision, densité de la map sur un axe de temps commun) se règle par les mêmes jetons. Le composant lit ces mots (attributs data-graph-* sur <html>) sans aucun balisage par thème ; zoom, panoramique, popovers, légende et masquage des intervalles de miss ne changent pas.

Les trois courbes restent distinguables, quoi que fasse le thème. Le combo est toujours plein, la précision toujours pointillée, la densité toujours une aire ou des barres (ce n'est pas réglable). Côté couleur, le combo, la précision et le milieu de la densité doivent différer deux à deux d'au moins 30° de teinte (pour des gris : 25 % de luminosité) ; sinon le thème entier est refusé au chargement, avec le nom des deux jetons. Les couleurs des paliers de jugement et ratingColor ne sont jamais des jetons ; --pv-rating-dark et --pv-tier-dark ne font qu'assombrir leur texte.

Les tailles du jeu (espacements --pv-s*, durées --pv-dur*, --pv-stagger) appartiennent à l'application ; sous prefers-reduced-motion les durées et --pv-shift-base tombent à zéro quel que soit le thème.

L'illustration de la map reste visible, quel que soit le thème. L'image de la map derrière les menus fait partie de l'identité du jeu : un thème peut la teinter (--pv-shade), l'assombrir, la flouter, la désaturer ou la recolorer (--pv-art-filter), jamais la retirer ni l'enterrer. Le validateur (crates/themes/src/artwork.rs) calcule la part de lumière de l'image qui atteint l'écran, en moyenne sur la fenêtre : chaque dégradé de --pv-shade compte pour la moyenne de son opacité le long de son axe, les couches se composent, et le filtre compte pour ses brightness() et opacity(). Les règles : au moins 20 % de l'image visible ; aucune couche de --pv-shade ne couvre plus de 90 % en moyenne (un aplat opaque est refusé) ; dans le filtre, brightness ≥ 0,25, opacity ≥ 0,4 et contrast ≥ 0,5. Le contrôle s'applique aussi à chaque bloc @media. Le joueur garde son interrupteur : « Fond noir » (Vidéo → Fond en jeu) masque l'image en jeu ; la sélection de morceaux n'est pas concernée, et la luminosité du fond (backgroundBrightness) ne change pas non plus. Pour des plaques lisibles sans cacher l'image, préférer des plaques translucides (opacité de 0,7 à 0,85).

Un thème ne change pas la géométrie d'un bouton-icône. Un bouton-icône (IconButton, les « ? » d'aide, les icônes d'export et d'import) est un carré dont le côté vient des jetons --pv-h-md (--pv-h-sm pour la petite taille) et dont la forme vient de --pv-clip-sm ; l'icône est centrée dedans (display: inline-grid; place-items: center, svg en bloc), et ni la casse, ni l'interlettrage, ni la hauteur de ligne, ni le remplissage latéral que les thèmes donnent aux boutons de texte ne l'atteignent. Un thème en capitales, en mono ou espacé ne peut donc pas décentrer ni déformer une icône. Les boutons de texte (Utiliser, Personnaliser…) restent libres d'avoir le style du thème. Garde-fou : tests/icon-button-geometry.spec.ts parcourt tous les thèmes livrés, à 1400×850 et 1000×700, et vérifie que chaque bouton-icône de la page Skins est un carré, que son icône est centrée à ±0,5 px, qu'elle ne déborde pas, que les boutons d'une même rangée ont la même hauteur, et que le survol, le focus clavier et l'appui ne changent pas la taille.

Écrire un quatrième thème

1. Copier themes/slant/ en themes/<mon-id>/ (ou dans <data>/themes).
2. Éditer theme.json (id = nom du dossier) et tokens.css.
3. Dans Skins → Recharger (ou relancer), la carte du thème apparaît ; l'aperçu est dessiné avec vos jetons.

Pour changer la construction des écrans, ajouter des mots --pv-layout-* dans tokens.css (voir « Choix de mise en page ») ; un mot omis garde la mise en page actuelle. Les thèmes livrés servent d'exemples : macos (rail d'onglets, bandeau de fenêtre), hack (crochets, focus clignotant, dense), ledger (rail, profil en colonne, tiroir à droite). Les jetons --pv-tier-dark et --pv-rating-dark servent à un thème clair (texte des paliers assombri).

Rien d'autre : pas de code, pas d'enregistrement. Le thème par défaut (réglage uiTheme absent ou invalide) est cabinet ; le thème d'identifiant classic reste choisissable et est réservé à la structure d'origine des menus (les composants d'avant le système de design lui sont rattachés par cet identifiant) ; un autre identifiant reçoit la structure du système de design.

Repli

Le thème choisi est absent : le premier thème disponible est utilisé, avec un avis. Aucun thème n'existe : l'application utilise ses jetons neutres intégrés (theme/fallback.css), de sorte que rien n'est jamais affiché sans style.

L'éditeur de skin

L'éditeur de skin (Skins → Personnaliser) vit dans la surcouche, une page WebView à part qui n'a ni la liste des thèmes ni les réglages : l'hôte lui envoie overlayTheme (le thème choisi uiTheme, accentSource, accentCustom et les thèmes déjà validés, les mêmes données que interfaces, aucune de plus et rien qu'un script puisse atteindre). La page en tire, avec le même code que les menus (theme/apply.ts, direction.ts, accent.ts), les variables CSS sous [data-direction], les mots data-layout-*, data-scheme et l'accent du joueur (un thème accent: fixed garde le sien). Sur la page, PrismLegacy est déclarée comme dans les menus pour les piles de polices qui la nomment.

Le panneau, les onglets, les champs, les interrupteurs, la barre d'outils et les cadres de l'éditeur ne lisent que ces jetons, par une couche de variables --ed-* (apps/web/src/overlay/editor/editor-theme.css) : surfaces (--pv-plate, --pv-bg, --pv-plate-raised), lignes (--pv-line), textes (--pv-text, -2, -3), accent et encre (--pv-accent, --pv-ink), sélection (--pv-accent-2, à défaut l'accent), rayons (--pv-radius-input, --pv-radius-panel), polices (--pv-font-body, -display, -label, -num), --pv-switch et --pv-thumb avec le mot --pv-layout-controls: pill (interrupteur en pilule, onglets en capsule à pouce relevé). Aucune couleur n'est écrite en dur dans l'éditeur (un test le vérifie) : un thème ajouté plus tard le restyle sans changement. Seuls le voile sur le jeu, les ombres et l'espace colorimétrique du sélecteur de couleur sont neutres.