Thème d'un royaume : une autre apparence pour la connexion et le compte
Sur cette page
Les pages de connexion (/auth/) et l’espace compte (/account/) lisent au chargement un fichier, auth/themes/themes.json. Pour chaque royaume, il peut donner une feuille de style, un logo, un nom et une ligne de copyright. Une seule feuille habille tout le parcours, de la connexion à l’espace compte, et il n’y a rien à recompiler ni à redémarrer.
Ce tutoriel installe l’exemple Université des Sciences, puis montre comment sa feuille est construite pour que vous puissiez l’adapter à votre établissement. L’exemple ne change pas seulement les couleurs : la page de connexion perd sa carte et montre un campus dessiné, et le menu latéral du compte devient une barre d’onglets.
Étape 1 : télécharger l’exemple#
Téléchargez theme-universite.zip (50 Ko). Il contient :
| Fichier | Rôle |
|---|---|
themes.json | Déclare le thème pour le royaume racine |
universite/theme.css | La feuille de style : palette, jetons TOSIAM, mise en page |
universite/logo.svg, universite/logo-dark.svg | Le logo, sur fond clair et sur fond sombre |
universite/login-art.svg, universite/login-art-dark.svg | Le campus dessiné à droite du formulaire de connexion |
universite/favicon.svg, universite/favicon-dark.svg | L’icône de l’onglet, pour une barre d’onglets claire et sombre |
universite/fonts/ | La police Atkinson Hyperlegible Next et sa licence (SIL Open Font License 1.1) |
Tout est local : la page ne charge rien depuis un autre site, pas même la police.
Étape 2 : copier le thème dans TOSIAM#
Les thèmes vivent dans le dossier auth/themes/ de l’application déployée. Avec la QuickStart, c’est apache-tomcat-11.0.14/webapps/tosiam/auth/themes/ :
cd ~/tosiam-quickstart-3.38.0/apache-tomcat-11.0.14/webapps/tosiam/auth/themes
unzip -o ~/Téléchargements/theme-universite.zipÉtape 3 : déclarer le thème#
Voici le themes.json de l’archive :
{
"default": {},
"realms": {
"/": {
"stylesheet": "universite/theme.css",
"logo": { "light": "universite/logo.svg", "dark": "universite/logo-dark.svg", "alt": "Université des Sciences" },
"name": { "fr": "Espace étudiant", "en": "Student portal" },
"layout": "card",
"theme": "auto",
"copyright": "Copyright © 2026 Université des Sciences. Tous droits réservés.",
"favicon": { "light": "universite/favicon.svg", "dark": "universite/favicon-dark.svg" }
}
}
}Chaque clé de realms est le chemin d’un royaume. / est le royaume racine ; un royaume sans entrée prend celle de son parent le plus proche, donc / habille aussi tous les royaumes qui n’ont pas la leur. Pour n’habiller qu’un royaume, utilisez son chemin, par exemple "/ref". default donne les valeurs communes à toutes les entrées.
| Réglage | Rôle |
|---|---|
stylesheet | La feuille chargée après celle de l’application, relative au dossier themes/ |
logo | Le logo à la place de celui de TOSIAM : light, dark (facultatif, pour le thème sombre) et alt, le texte lu par les lecteurs d’écran |
name | Le nom de l’espace, par langue : pastille à côté du logo sur la connexion, légende sous le logo dans le compte |
layout | connected (par défaut : la carte reliée à ses nœuds, sur le fond animé) ou card (une carte simple sur --tos-bg, que la feuille peut ensuite remodeler) |
theme | auto (suit l’appareil), light ou dark. L’utilisateur peut toujours choisir le sien : avec le bouton à côté de la langue sur la connexion, dans son menu dans le compte |
copyright | La ligne du pied de page, en texte |
favicon | L’icône de l’onglet à la place de celle de TOSIAM : light, et dark (facultatif) pour les barres d’onglets sombres |
D’autres réglages ajoutent des textes, un avis, des liens, un contact, ou un thème propre à un arbre : voir Aller plus loin.
Le fichier est relu à chaque chargement de page : il n’y a pas de cache à vider dans TOSIAM. Tomcat peut servir l’ancienne version quelques secondes après une modification.
Étape 4 : voir le résultat#
Ouvrez http://localhost:8080/tosiam/auth/. La connexion est maintenant une page à part entière : le logo et le nom de l’espace dans la barre du haut (1), le formulaire posé sur la page, sans carte, avec un grand titre (2), le bouton principal aux couleurs de l’université (3) et, à droite, le campus. À côté de la langue, le bouton de thème (4) reprend le style du thème sans rien ajouter à la feuille.
1
2
3
4
Connectez-vous : l’espace compte suit le même thème, avec l’en-tête sombre et son logo clair (1), et le menu devenu une barre d’onglets (2).
1
2
Pour voir l’autre version, choisissez « Sombre » ou « Clair » avec le bouton de thème (4) : chaque couleur du thème a ses deux valeurs. Le choix est gardé dans le navigateur, le même pour la connexion et l’espace compte ; « Appareil » revient au réglage de l’appareil. Les captures de cette page suivent d’ailleurs le thème du site.
Comment la feuille est construite#
Ouvrez universite/theme.css. Elle se lit en quatre parties.
1. Une portée : :root[data-realm]#
Les deux applications posent le royaume courant sur l’élément racine (data-realm="root" pour le royaume racine, data-realm="ref" pour /ref), et ne chargent la feuille que pour les royaumes qui la déclarent. Toute la feuille est donc imbriquée sous :root[data-realm] : cela suffit à la limiter à ces royaumes, et ce sélecteur l’emporte sur les valeurs par défaut de TOSIAM.
2. La palette, puis les jetons de TOSIAM#
La feuille définit d’abord la palette de l’université (--hz-*), puis y fait pointer les jetons de TOSIAM (--tos-*) que les deux applications utilisent pour tout dessiner :
:root[data-realm] {
--hz-surface: light-dark(#FFFFFF, #202734);
--hz-ink: light-dark(#202734, #E0F8C7);
--hz-primary: light-dark(#36415A, #B7D894);
--tos-surface: var(--hz-surface);
--tos-text: var(--hz-ink);
--tos-accent: var(--hz-primary);
--tos-font-sans: "Atkinson Hyperlegible Next", system-ui, sans-serif;
--tos-radius-md: 10px;
}Chaque couleur est une paire light-dark(clair, sombre) : le navigateur choisit selon le choix de l’utilisateur, sinon selon theme dans themes.json, sinon selon le thème de l’appareil. Les jetons les plus utiles :
| Jeton | Ce qu’il colore |
|---|---|
--tos-accent, --tos-accent-hover, --tos-accent-contrast | Le bouton principal, son survol, son texte |
--tos-id-fill, --tos-id-text, --tos-id-line | Le bouton « Se connecter », la pastille du royaume, l’entrée choisie du menu et les compteurs du compte |
--tos-brand, --tos-focus | Les liens et l’anneau de focus |
--tos-bg, --tos-surface, --tos-surface-raised | Le fond, les cartes, les zones en relief |
--tos-text, --tos-text-soft, --tos-text-muted | Le texte, du plus fort au plus discret |
--tos-border, --tos-border-strong | Les traits, et le contour des champs |
--tos-danger, --tos-warning, --tos-info, --tos-success et leurs -soft | Les états : erreur, avertissement, information, succès |
--tos-font-sans, --tos-font-mono | Les polices |
--tos-radius-*, --tos-control-h | Les arrondis et la hauteur des champs et boutons |
Changez aussi les couleurs d’état : le rouge par défaut de TOSIAM jure vite avec une autre palette. L’exemple prend un rouge brique, un ocre et un bleu ardoise de la même famille que ses couleurs, chacun avec au moins 4,5:1 de contraste sur la page et sur sa teinte claire. En sombre, le texte posé sur ces couleurs est foncé, pas blanc.
3. La mise en page#
Aucune des deux applications n’enferme ses composants dans un shadow DOM : la feuille atteint chaque élément par sa classe, et peut donc changer la mise en page, pas seulement les couleurs. La page de connexion « sans carte » tient en quelques règles :
:root[data-realm] {
--hz-login-split: 52%;
--hz-login-art: url("login-art.svg");
.tos-cardlogo, .tos-circuit { display: none; }
.tos-column { position: relative; }
/* le campus, à droite du formulaire, sous la barre du haut */
.tos-column::after { content: ""; position: absolute; top: 64px; right: 0; bottom: 0; left: var(--hz-login-split);
background: var(--hz-login-art) center / cover no-repeat; }
.tos-main, .tos-footer { margin-right: calc(100% - var(--hz-login-split)); }
.tos-shell[data-layout] .tos-card { max-width: 400px; padding: 0; background: transparent; box-shadow: none; }
}La barre d’onglets du compte ne s’applique qu’au-dessus de 860 px (@media (min-width: 861px)) : en dessous, le compte garde son tiroir de menu, pensé pour le téléphone. Gardez cette règle si vous remodelez le compte.
4. Les images et la police#
Une image n’est pas une couleur : light-dark() ne peut pas choisir entre deux fichiers. Le campus passe donc par une variable, changée pour le thème sombre :
:root[data-realm][data-theme="dark"] { --hz-login-art: url("login-art-dark.svg"); }
@media (prefers-color-scheme: dark) {
:root[data-realm]:not([data-theme="light"]) { --hz-login-art: url("login-art-dark.svg"); }
}Le logo, lui, a sa version sombre dans themes.json (logo.dark). Les adresses de la feuille (url(...)) sont relatives au dossier de la feuille, et la police est déclarée par un @font-face vers fonts/ : rien ne part vers un autre site.
Adapter l’exemple à votre établissement#
- Copiez le dossier
universitesous un autre nom et changez le chemin dansthemes.json. - Remplacez les logos (SVG de préférence, environ 130 × 40) et le dessin, ou supprimez la règle
.tos-column::afterpour une page sans image. - Changez la palette
--hz-*en haut de la feuille, en gardant deux valeurs par couleur, et vérifiez les contrastes : 4,5:1 pour le texte, 3:1 pour les contours de champs et l’anneau de focus. - Changez
nameetcopyright. - Vérifiez la connexion, une erreur de mot de passe, l’espace compte et un téléphone, en clair et en sombre.
Aller plus loin : textes, avis, liens, contact, thème d’un arbre#
Une entrée de themes.json peut aussi changer des textes de la page et ajouter des informations autour du formulaire. Tout reste du texte : aucun HTML n’est accepté, et rien ne demande de recompiler TOSIAM.
1
2
3
4
"texts": {
"fr": { "logIn": "Entrer dans l'Espace étudiant", "forgotPassword": "Code perdu ?" },
"en": { "logIn": "Enter the student portal", "forgotPassword": "Lost your code?" }
},
"notice": {
"fr": "Maintenance prévue samedi de 8 h à 10 h : la connexion sera indisponible.",
"en": "Planned maintenance on Saturday, 8 to 10 am: sign-in will be unavailable."
},
"links": [
{ "label": { "fr": "Première connexion ?", "en": "First time here?" }, "href": "https://www.example.edu/premiere-connexion" },
{ "label": { "fr": "Charte informatique", "en": "IT charter" }, "href": "https://www.example.edu/charte" }
],
"contact": { "email": "support@example.edu", "phone": "+33 1 23 45 67 89", "url": "https://aide.example.edu" },
"trees": {
"sms": {
"name": { "fr": "Connexion par SMS", "en": "Sign in by SMS" },
"notice": { "fr": "Un code vous sera envoyé par SMS.", "en": "A code will be sent to you by SMS." }
}
}| Réglage | Rôle |
|---|---|
texts | Des textes à la place de ceux de TOSIAM, par langue puis par clé de traduction. Ils valent pour la connexion et pour le compte |
notice | Un avis au-dessus du formulaire, par langue |
links | Des liens sous le formulaire : un libellé par langue et une adresse |
contact | Le support dans le pied de page, sur la connexion et dans le compte : email, phone et url, chacun facultatif |
trees | Une entrée par arbre (ou chaîne) du royaume, qui complète celle du royaume |
Quelques règles :
- Un texte contenant
<,>ou"est ignoré, et la console du navigateur dit lequel. Une clé inconnue est ignorée aussi. - Une adresse de
linksdoit commencer parhttps:,mailto:outel:; une autre est ignorée,javascript:commehttp:. L’urldecontactdoit commencer parhttps:. - L’entrée d’un arbre s’applique quand le lien de connexion le demande, avec
service=smsouauthIndexType=service&authIndexValue=sms; sans ce paramètre, la page prend l’entrée du royaume. Ici, seuls le nom et l’avis changent pour l’arbresms.
Les clés de texte#
Les clés sont celles des fichiers de traduction de l’interface, src/apps/auth/locales/fr.json pour la connexion et src/apps/account/locales/fr.json pour le compte. Les plus utiles sur la page de connexion :
| Clé | Texte par défaut |
|---|---|
logIn | Se connecter (le bouton) |
forgotPassword | Mot de passe oublié ? |
forgotUsername | Nom d’utilisateur oublié ? |
rememberMe | Se souvenir de moi |
createAccount | Créer un compte (le lien vers l’inscription) |
Le titre de l’étape (« Connexion à TOSIAM ») et les libellés des champs (« Nom d’utilisateur », « Mot de passe ») viennent du serveur : ils se règlent dans l’arbre ou le module d’authentification, pas dans texts.
Garder le thème après un redémarrage#
Le dossier auth/themes/ fait partie de l’application déployée. Au démarrage, la QuickStart extrait de nouveau tosiam.war par-dessus webapps/tosiam/ : votre dossier universite/ reste, mais themes.json reprend la version du WAR, qui ne déclare aucun royaume. Recopiez votre themes.json après chaque démarrage, ou ajoutez le thème au WAR lui-même :
mkdir -p build/auth/themes
cp -r universite themes.json build/auth/themes/
cd build && zip -r ../tosiam.war auth/themesLancée à côté de votre tosiam.war, la commande y remplace auth/themes/themes.json et ajoute le dossier du thème ; déployez ensuite ce WAR comme d’habitude.
Limites#
- Le thème ne change ni l’ordre des champs ni les étapes de connexion : ils viennent du graphe d’authentification, comme le titre de l’étape et les libellés des champs.
textsne change que les textes de l’interface. - Un thème ne peut pas remplacer le HTML de la page comme les gabarits de l’ancienne interface (XUI) : les textes, l’avis, les liens et le contact sont posés comme du texte.
nameest le même pour la connexion et le compte.- La console d’administration (
/console) ne lit pasthemes.json. - Derrière un CDN placé sur l’adresse de TOSIAM, le thème s’applique de la même façon :
themes.jsonet les dossiers des thèmes ne sont jamais mis en cache. Voir CDN sur le même domaine.
Mis à jour le