Aller au contenu

Pourquoi un accent d'instance piloté serveur

Kirexo distingue deux réglages d'apparence qui se ressemblent mais n'ont pas du tout le même statut : la couleur d'accent, qui est un réglage d'instance rendu côté serveur, et le thème clair/sombre, qui reste une préférence par visiteur gérée côté client. Cette page explique pourquoi cette frontière est tracée ainsi, et quelles conséquences techniques elle a eues — notamment le dégraissage du script accent.js. Pour la description factuelle des fichiers, attributs et valeurs, voir la référence Design system : tokens, thèmes et accent.

L'accent est un réglage d'instance, pas une préférence de visiteur

La couleur d'accent fait partie de l'identité visuelle de l'instance Kirexo, au même titre que son nom ou son favicon. Quand l'administrateur d'une instance choisit « Bordeaux », il décide de l'apparence de sa plateforme — pour tous ses lecteurs, pas seulement pour lui.

C'est pourquoi l'accent est persisté par une entité Setting singleton (une seule ligne en base), et non dans le navigateur de chaque visiteur. Une seule valeur fait autorité, partagée par tout le monde. À l'inverse, laisser chaque visiteur choisir sa propre couleur d'accent reviendrait à diluer l'identité de l'instance : deux lecteurs verraient deux « Kirexo » différents, ce qui n'a pas de sens pour une marque.

Le statut singleton porte cette intention dans le modèle : il n'existe pas de notion d'« accent du visiteur ». La seule question est « quel est l'accent de cette instance ? », et la réponse est unique.

Pourquoi le rendre côté serveur

L'accent étant une valeur d'instance unique, il est lu au rendu de chaque page et injecté directement dans le HTML servi :

<html lang="fr" data-theme="light" data-accent="{{ platform_accent() }}">

Deux raisons motivent ce rendu serveur plutôt qu'une application en JavaScript après chargement.

Cohérence multi-appareils. Comme la source de vérité est la base de données, l'accent est identique quel que soit l'appareil, le navigateur ou la session. Rien ne dépend d'un état local : ouvrir l'instance depuis un téléphone, un poste public ou une session fraîche donne exactement la même couleur. Un changement décidé par l'administrateur se propage à tout le monde au rechargement, sans qu'aucun visiteur n'ait à « resynchroniser » quoi que ce soit.

Pas de flash de couleur au chargement. Si l'accent était appliqué par un script après le rendu, la page s'afficherait d'abord avec une couleur par défaut (ou neutre), puis basculerait brutalement vers la bonne teinte une fois le JavaScript exécuté — un flash visible et désagréable. En posant data-accent directement dans le HTML, la bonne couleur est présente dès le premier octet rendu : aucune transition parasite.

Pourquoi accent.js a été dégraissé

Le script accent.js fourni par le design system, dans sa version source (design-system/accent.js), faisait trois choses : il stampait le logomark SVG, il construisait les sélecteurs d'accent, et il persistait l'accent choisi dans localStorage (clé kirexo-accent) pour le réappliquer au chargement de chaque page.

Cette dernière partie entre en conflit direct avec un accent d'instance rendu côté serveur. Si le script réappliquait l'accent depuis le localStorage du visiteur, il écraserait la valeur data-accent posée par le serveur dès le chargement de la page. Un visiteur ayant un jour cliqué sur « Prune » continuerait de voir « Prune » même après que l'administrateur a basculé l'instance sur « Forêt » — exactement l'inverse de la cohérence recherchée.

La copie de travail assets/js/accent.js est donc dégraissée de cette persistance et de cette ré-application : la valeur serveur data-accent reste la seule source de vérité au chargement. Les parties utiles au reste de l'application — le stampage du logomark et la fonction d'application de l'accent — sont conservées.

Le choix de l'accent par l'administrateur se fait sur la page Réglages (/admin/reglages), qui écrit la valeur dans l'entité Setting côté serveur — et non dans le localStorage du navigateur. Le déroulé est décrit dans le how-to Définir la couleur d'accent de la plateforme ; la mécanique de la page est en Référence des espaces et dashboards.

Pourquoi le thème reste, lui, une préférence locale

Le thème clair/sombre relève d'un tout autre besoin. Préférer le sombre ou le clair dépend de l'environnement du lecteur — luminosité ambiante, fatigue visuelle, heure de la journée, réglage système de son appareil. Ce n'est pas une décision de marque, c'est un confort personnel.

Le thème est donc géré côté client : assets/js/theme.js lit et écrit la clé localStorage kirexo-theme. Chaque visiteur garde son réglage, propre à son navigateur, sans incidence sur les autres ni sur l'instance.

Un sélecteur tri-état, pas une simple bascule

Là où l'accent se choisit sur la page Réglages admin, le thème se choisit dans le sélecteur porté par l'entête partagé (templates/components/Header.html.twig), présent sur tous les écrans — dans le menu du compte quand une session existe, à plat dans l'entête sinon. Il est donc disponible sur l'accueil public et sur les pages de connexion, puisqu'il ne suppose aucune authentification. C'est le pendant naturel d'une préférence de visiteur : à portée de clic, sur chaque page, sans détour par un espace connecté.

Le sélecteur n'offre pas un simple interrupteur clair/sombre, mais trois modes : light, dark et system. La nuance est délibérée. Forcer le clair ou le sombre, c'est figer une palette quelle que soit l'heure ou l'appareil ; choisir system, c'est déléguer la décision au réglage clair/sombre de l'OS. Stocker un booléen « sombre oui/non » perdrait cette troisième intention : la clé kirexo-theme mémorise donc le mode (light | dark | system), pas le thème résolu. Le mode par défaut, en l'absence de tout choix, est system.

Pourquoi « système » suit l'OS en direct

Le mode system ne se contente pas de lire prefers-color-scheme au chargement : il réagit en temps réel aux changements de l'OS, via un écouteur sur matchMedia('(prefers-color-scheme: dark)'). Si l'appareil bascule en sombre le soir, l'interface suit immédiatement, sans rechargement. Ce serait incohérent autrement : « suivre le système » qui ne suivrait qu'au premier affichage ne serait pas vraiment suivre le système. Les modes light et dark, eux, ignorent volontairement ce signal — l'utilisateur a explicitement forcé une palette.

Pourquoi synchroniser entre onglets

Une préférence de visiteur vit dans localStorage, qui est partagé par tous les onglets d'une même origine. Si le thème n'était appliqué qu'à l'onglet où l'on clique, les autres onglets ouverts afficheraient encore l'ancien thème jusqu'à un rechargement — une incohérence visible pour un même visiteur, dans un même navigateur. theme.js écoute donc l'event storage, émis dans les autres onglets quand kirexo-theme change, et y réaligne le thème. Le choix se propage à toutes les fenêtres ouvertes de l'instance.

Pourquoi appliquer le thème avant le premier paint

Le script de thème est chargé en module différé (via app.js / l'importmap) : exécuté tel quel, il s'appliquerait après le premier rendu, et un visiteur en sombre verrait un flash clair le temps que le module s'exécute — le même défaut que celui évité pour l'accent. Pour l'empêcher, un court script inline en tête de templates/base.html.twig résout le thème effectif (même logique que theme.js, volontairement minimale) et pose data-theme sur <html> avant le premier paint. La bonne palette est donc présente dès le premier octet, sans transition parasite.

Le site public suit le système, sans sélecteur ni JavaScript

Tout ce qui précède — le sélecteur tri-état, la clé kirexo-theme, le suivi OS en direct, le script inline anti-FOUC de templates/base.html.twig — concerne l'application : le back-office, l'espace utilisateur, et l'accueil public de la plateforme (page de connexion comprise). Ces écrans exécutent du JavaScript et servent une CSP qui l'autorise.

Les sites publics des utilisateurs — le rendu servi par le plugin web sur leur propre domaine — obéissent, eux, à un tout autre régime. Ce rendu affiche du HTML partiellement écrit par l'utilisateur ; en dernier verrou anti-XSS, il sert une CSP stricte dont la directive centrale est script-src 'none' : aucun JavaScript ne s'y exécute (voir Sécurité du rendu personnalisé des sites). Tout le mécanisme de thème décrit ci-dessus — qui repose sur theme.js et sur le script anti-FOUC — y est donc inapplicable : il serait purement et simplement bloqué par le navigateur.

La conséquence est directe : sur un site public, la bascule clair/sombre est purement CSS. Le site suit le réglage système du visiteur, via @media (prefers-color-scheme: dark), et n'offre aucun sélecteur de thème — pas de choix light/dark/system, puisqu'il n'y a aucun script pour le porter ni pour le mémoriser. C'est un compromis assumé : plutôt que d'affaiblir la CSP publique pour ré-autoriser un script de thème, on renonce au sélecteur sur ce périmètre et on s'en remet au réglage de l'OS, que le CSS sait lire sans une ligne de JavaScript.

Les deux mécanismes coexistent sans se marcher dessus. Sur l'application, le thème résolu est posé en data-theme sur <html> ; sur un site public, cet attribut est simplement absent. Et par construction, data-theme, quand il est présent, l'emporte sur la media query : un écran de l'application affiche donc le thème choisi par le visiteur, tandis qu'un site public — sans attribut — retombe sur prefers-color-scheme. Aucun arbitrage à l'exécution, aucun script commun : la présence ou l'absence de l'attribut suffit à trancher.

La distinction est assumée et symétrique :

Réglage Statut Source de vérité Mécanisme
Accent Identité d'instance Base de données (Setting singleton) Rendu serveur (data-accent)
Thème Confort du visiteur Navigateur (localStorage kirexo-theme, mode light/dark/system) Script client (data-theme), suivi OS live + synchro onglets

Mettre l'accent côté serveur et le thème côté client n'est pas une incohérence : c'est le reflet fidèle de ce que chaque réglage représente. L'un appartient à l'instance, l'autre au lecteur.

E-mails au design system

Les e-mails HTML de Kirexo adoptent le design system, mais par un chemin différent de celui des pages web — parce qu'un e-mail est un media à part.

Pourquoi pas var() ni feuille externe

Les pages web s'appuient sur les variables CSS du DS (var(--accent), var(--ink)…) et une feuille de styles. Les clients mail (Gmail, Outlook, Apple Mail…) ne sont pas des navigateurs : la plupart ne supportent ni les variables CSS, ni les feuilles externes, ni <style> fiable. La seule technique robuste est le style inline, posé directement sur chaque élément.

Le layout partagé templates/email/base.html.twig est donc écrit en styles inline, et non en classes du DS. Mais on ne réécrit pas les couleurs à la main pour autant : elles restent dérivées des tokens du design system, via un point unique côté serveur.

email_palette(space) : une palette matérialisée, source unique

La fonction Twig email_palette(space) (extension App\Twig\EmailPaletteExtension, exécution déléguée à App\Twig\Runtime\EmailPaletteRuntime) renvoie une palette en valeurs concrètes (hex), prête à inliner. Elle matérialise les tokens du DS en palette claire — le dark-mode en e-mail n'étant pas fiable, l'<head> déclare d'ailleurs color-scheme: light only.

L'argument space décide de l'accent :

  • user — reprend l'accent d'instance courant (le même que celui des pages, résolu depuis l'entité Setting). L'e-mail porte l'identité visuelle choisie dans les réglages.
  • admin — accent figé sur graphite, l'identité neutre du back-office, quel que soit l'accent d'instance. Le layout ajoute en plus une pastille « Admin » dans l'en-tête (p.isAdmin).

Le runtime étant lazy, le Setting d'instance n'est requêté que lorsqu'un e-mail est réellement rendu — jamais au rendu d'une page web. C'est la même source de vérité que l'accent serveur décrit plus haut : on ne redéfinit pas une palette propre aux e-mails, on projette celle du DS en hex pour ce contexte.

Le prix de cette projection est une synchronisation manuelle : les hex du runtime sont une copie des tokens, pas une lecture de kirexo-ds.css. Quand un token neutre change — --ink-3 a ainsi été foncé pour atteindre 4,5:1 de contraste —, la palette e-mail doit suivre, faute de quoi les e-mails conserveraient l'ancienne teinte. Générer la palette depuis la feuille CSS supprimerait cette double saisie, mais au prix d'un parseur CSS pour une dizaine de valeurs qui changent rarement ; c'est la copie commentée token par token qui est en place. La liste des tokens concernés est dans la référence du design system.

Premier e-mail concerné

L'e-mail de réinitialisation de mot de passe (templates/reset_password/email.html.twig) est le premier à en bénéficier : il étend email/base.html.twig et expose un CTA en bouton accent. C'est le space (transmis au rendu de l'e-mail) qui détermine s'il porte l'accent d'instance (espace utilisateur) ou l'identité graphite (espace admin). Pour le parcours fonctionnel, voir Réinitialiser son mot de passe ; pour faire arriver l'e-mail en local, Recevoir les e-mails en développement.

Pourquoi la documentation copie le design system au build

La documentation (doc.kirexo.app) est générée par mkdocs avec le thème Material, mais elle est habillée comme l'espace admin de Kirexo : mêmes polices, mêmes couleurs, même sélecteur de thème. Les fichiers du design system ne sont pourtant pas recopiés dans docs/ : ils sont copiés au moment du build. Cette section explique ce choix et les contraintes qui l'ont façonné. Pourquoi la documentation et le site vitrine sont deux sites distincts : voir Pourquoi un site vitrine séparé de la documentation.

Un hook plutôt qu'une copie dans docs/

Le plus simple aurait été de copier kirexo-ds.css, fonts.css, les polices, theme.js et le favicon dans docs/, d'où mkdocs les aurait publiés tels quels. Cela aurait créé une deuxième copie versionnée du design system : à chaque retouche d'un token dans assets/styles/kirexo-ds.css, il aurait fallu penser à recopier le fichier, sans que rien ne signale l'oubli. La documentation aurait peu à peu divergé de l'application.

Le hook mkdocs/hooks/kirexo_assets.py, déclaré sous hooks: dans mkdocs.yml, garde une seule source. À chaque build, il lit les fichiers du dépôt (assets/styles/, assets/fonts/, assets/js/theme.js, public/favicon/) et les écrit sous assets/kirexo/ dans la sortie. La disposition styles/ à côté de fonts/ est reproduite, ce qui garde valides les chemins relatifs ../fonts/ de fonts.css. La clé watch: de mkdocs.yml fait aussi recharger mkdocs serve quand le design system change.

En contrepartie, le build dépend de fichiers situés hors de docs/. Si une source manque, le hook arrête le build avec une PluginError qui nomme le fichier absent, plutôt que de publier une documentation sans styles. En local, le service docs doit donc monter ./assets, ./public/favicon et ./mkdocs (compose.override.yaml). En CI, ces fichiers viennent du checkout.

Lire en on_pre_build, écrire en on_post_build

Le hook lit ses sources dans on_pre_build, les garde en mémoire, puis les écrit dans on_post_build. Ce découpage vient de la CI. Les jobs quality:docs-build et pages construisent avec mkdocs build --strict -d public, et ce public/ est celui du dépôt, le même qui contient public/favicon/ pour Symfony. Or mkdocs vide le dossier de sortie entre on_pre_build et on_post_build. Un hook qui lirait le favicon en fin de build le trouverait déjà effacé, et les deux jobs échoueraient.

C'est aussi pour cela que les cartes Open Graph du plugin social n'ont pas de logo : il aurait fallu le lire dans public/favicon/, que mkdocs a déjà vidé quand le plugin génère les cartes.

Une palette Material unique, branchée sur les tokens

Material propose ses propres palettes et, si on en déclare plusieurs, une bascule clair/sombre avec son propre script de mémorisation. Kirexo déclare au contraire une palette en mapping unique (scheme: default, primary: custom, accent: custom). Dans ce cas, Material n'affiche ni bascule ni script de palette, et c'est ce qui permet de lui retirer la gestion du thème.

Les couleurs viennent ensuite de mkdocs/overrides/stylesheets/kirexo-docs.css, qui relie chaque variable --md-* de Material à un token du design system (--md-default-fg-color: var(--ink), --md-typeset-a-color: var(--accent)…). Ces correspondances sont posées une seule fois, sans bloc par thème. Les tokens changent de valeur selon [data-theme] sur <html>, et les --md-* suivent. Un même fichier sert donc le clair et le sombre, et une retouche de token dans le design system se retrouve dans la documentation au build suivant.

Le sélecteur de Kirexo à la place de la bascule Material

Garder la bascule de Material aurait fait cohabiter deux mécanismes : le sien et theme.js, avec deux clés de stockage et deux façons de résoudre le thème. La documentation reprend donc le sélecteur clair / sombre / système de l'application, avec le même markup .theme-toggle, le même assets/js/theme.js, la même clé kirexo-theme et le même script anti-flash dans le <head> (mkdocs/overrides/main.html). Le comportement est le même partout : trois modes, mode system par défaut, sélecteur masqué sans JavaScript.

Material n'offre aucun bloc surchargeable pour cette zone du header : la bascule et le titre sont écrits en dur dans partials/header.html. Le projet en garde donc une copie, mkdocs/overrides/partials/header.html, faite sur Material 9.7.7. Elle ne diffère de l'original que par la pastille « Docs » et le sélecteur. C'est une dette connue : à chaque montée de version de squidfunk/mkdocs-material, il faut comparer cette copie avec le nouveau partials/header.html, sinon les corrections de Material à ce gabarit ne seront pas reprises. La navigation instantanée (navigation.instant) est conservée, car elle remplace le contenu de la page sans recréer le <header> : le sélecteur reste branché d'une page à l'autre.

L'exception de l'accent sombre sans JavaScript

kirexo-docs.css n'écrit ses couleurs que par variables du design system, sauf à un endroit. Sans JavaScript, <html> n'a ni data-theme ni data-accent, et le sélecteur est masqué (html:not(.js) .theme-toggle) : la page suit prefers-color-scheme. Le repli sombre de kirexo-ds.css redéfinit les neutres mais pas la famille --accent, qui gardait donc l'encre claire sur fond sombre, avec un contraste insuffisant.

Dans l'application, l'accent est posé par le serveur en data-accent. La documentation est un site statique : poser cet attribut aurait obligé à surcharger aussi le gabarit base.html de Material. Le bloc @media (prefers-color-scheme: dark) { :root:not([data-theme]) { … } } reprend donc en dur les cinq valeurs de l'accent encre sombre du design system. Ce sont les seules valeurs hexadécimales de la feuille, et un commentaire indique d'où elles viennent pour qu'on les mette à jour avec les tokens.

Des polices auto-hébergées, avec une exception au build

Par défaut, Material charge Roboto depuis Google Fonts à chaque affichage. theme.font: false supprime ce chargement. Public Sans et IBM Plex Mono viennent des fichiers du design system copiés par le hook et déclarés par fonts.css : un lecteur de la documentation n'envoie aucune requête à Google.

La seule exception a lieu au build, pas à l'affichage. Le plugin social, qui génère les images d'aperçu Open Graph, télécharge Public Sans depuis Google Fonts pour dessiner le texte des cartes. C'est pourquoi fonts.google.com et fonts.gstatic.com restent dans l'allowlist (infra/firewall/baseline-domains.txt). Ce téléchargement est fait par la machine de build, jamais par le navigateur du lecteur.

Un écart assumé : des cibles de 40 px

La fiche du design system demande des cibles d'au moins 44 px. Dans la documentation, les boutons du sélecteur de thème et les liens de la barre latérale font 40 px : c'est la taille retenue pour le sélecteur (décision DC7 du ticket #302), et les liens de navigation (min-height: 40px dans kirexo-docs.css) l'ont reprise. L'écart est volontaire et limité à la documentation. Les écrans de l'application gardent leurs 44 px.

Des blocs de code qui reviennent à la ligne

Material fait défiler horizontalement les blocs de code trop larges. Or une zone qui défile sans pouvoir recevoir le focus n'est pas atteignable au clavier : le premier audit axe de la doc l'a relevé (règle scrollable-region-focusable). Plutôt que de rendre chaque bloc focusable, ce qui aurait demandé un script, kirexo-docs.css fait revenir le code à la ligne (white-space: pre-wrap, overflow-wrap: anywhere). Une longue commande se lit sur plusieurs lignes au lieu d'une seule, mais tout le code reste lisible, au clavier comme sans JavaScript. Le contrôle et la liste des corrections sont dans la référence du job quality:docs-a11y.

Voir aussi