Aller au contenu

Design system : tokens, thèmes et accent

Référence du design system (DS) de Kirexo : où vivent les fichiers, comment le thème clair/sombre et l'accent d'instance sont pilotés, quelles variables CSS sont disponibles, et quelles contraintes d'accessibilité sont garanties. Pour le raisonnement derrière l'accent rendu côté serveur, voir l'explication Pourquoi un accent d'instance piloté serveur.

Fichiers du DS et emplacements

Le dossier design-system/ porte la livraison de référence du DS ; l'application, elle, sert les fichiers de assets/ et public/. Le régime n'est pas le même pour tous les fichiers, et c'est ce tableau qui fait foi :

Rôle Fichier de design-system/ Fichier servi Régime
Feuille de tokens et composants design-system/kirexo-ds.css assets/styles/kirexo-ds.css Source de vérité amont. La copie servie n'en diffère que par l'import des polices (voir ci-dessous).
Script d'accent + logomark design-system/accent.js assets/js/accent.js Source de vérité amont, copie adaptée (voir ci-dessous).
Favicon et manifest design-system/favicon/ public/favicon/ Source de vérité amont, copiée telle quelle.
Feuille des écrans design-system/screens.css assets/styles/screens.css La feuille servie fait foi. C'est elle qu'on modifie.
Script de thème clair/sombre — assets/js/theme.js Propre à l'application, sans amont.

Le dossier public/favicon/ contient : favicon.ico, favicon-16.png, favicon-32.png, favicon-48.png, favicon-180.png, favicon-192.png, favicon-512.png, favicon-mono-512.png, safari-pinned-tab.svg, site.webmanifest.

La feuille des écrans se modifie dans assets/styles/, pas dans design-system/

Les classes d'écran naissent avec les écrans : chaque nouvel écran de l'application en ajoute. assets/styles/screens.css porte donc des dizaines de familles que design-system/screens.css ne connaît pas (.bo-dash*, .bo-tag*, .bo-plugin-*, .editor-*, .user-menu__*, .ud-*, .dest*…).

La règle projet (.claude/skills/_shared/design-system.md) désigne d'ailleurs kirexo-ds.css et accent.js — et eux seuls — comme la source de vérité amont. Traiter design-system/screens.css comme telle et « resynchroniser » depuis lui supprimerait le style de la moitié des écrans.

accent.js est une copie adaptée

Contrairement au favicon copié tel quel, assets/js/accent.js est dégraissé de la persistance et de la ré-application de l'accent depuis localStorage présentes dans la source. La raison est expliquée dans Pourquoi un accent d'instance piloté serveur.

kirexo-ds.css servie : un seul écart, l'import des polices

La copie servie remplace l'@import distant vers Google Fonts par un @import url('./fonts.css') local. Ce n'est pas une préférence : depuis un conteneur dont le réseau est internal, chaque nom externe coûte le plein timeout DNS — le @import distant se payait en secondes sur chaque page. Les polices sont auto-hébergées, le pourquoi et la procédure de régénération vivent dans assets/styles/fonts.css.

Thème clair/sombre — data-theme

Le thème est porté par l'attribut data-theme sur <html>, avec deux valeurs admises :

Valeur Effet
light Palette claire (valeur par défaut, équivalente à :root dans assets/styles/kirexo-ds.css)
dark Palette sombre

Le rendu serveur pose data-theme="light" par défaut. Le script assets/js/theme.js ajuste ensuite la valeur côté client :

  • il lit la clé localStorage kirexo-theme (préférence locale du visiteur) ;
  • en l'absence de préférence enregistrée, il suit prefers-color-scheme ;
  • il bascule l'attribut data-theme sur <html> en conséquence.

Le thème est donc une préférence par visiteur, persistée dans le navigateur.

Ce mécanisme ne vaut que pour l'application (back-office, espace utilisateur, accueil public de la plateforme), qui exécute du JavaScript. Les sites publics servis par le plugin web ne posent pas data-theme et n'exécutent aucun script (CSP script-src 'none') : leur bascule clair/sombre est purement CSS, via @media (prefers-color-scheme: dark), et suit le réglage système du visiteur sans sélecteur. data-theme, quand il est présent, l'emporte sur cette media query. Voir l'explication Pourquoi le thème reste une préférence locale.

Accent d'instance — data-accent

L'accent est porté par l'attribut data-accent sur <html> et rendu côté serveur. Les six valeurs admises correspondent aux cases de l'enum App\Entity\Enum\AccentColor (src/Entity/Enum/AccentColor.php) :

Valeur (data-accent) Libellé FR (AccentColor::label())
encre Encre (valeur par défaut)
bordeaux Bordeaux
foret Forêt
prune Prune
rouille Rouille
graphite Graphite

Contrairement au thème, l'accent n'est pas une préférence par visiteur : c'est un réglage d'instance, partagé par tous. Voir Pourquoi un accent d'instance piloté serveur.

Fonction Twig platform_accent()

La valeur de data-accent est injectée par la fonction Twig platform_accent(), utilisée dans templates/base.html.twig :

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

La fonction est exposée par src/Twig/PlatformAccentExtension.php et déléguée à src/Twig/Runtime/PlatformAccentRuntime.php. Le runtime lit le réglage via SettingRepositoryInterface (src/Repository/SettingRepositoryInterface.php) : il retourne la valeur de l'accent du singleton Setting, ou la valeur par défaut (encre) si le singleton n'a pas encore été initialisé.

Entité Setting et enum AccentColor

L'accent est persisté par l'entité singleton App\Entity\Setting (src/Entity/Setting.php) — une seule ligne en base, dans la table setting. Elle porte une propriété accent typée par l'enum AccentColor, stockée via le mapping Doctrine enumType.

L'enum App\Entity\Enum\AccentColor (src/Entity/Enum/AccentColor.php) est un backed enum string exposant deux méthodes :

Méthode Rôle
label(): string Libellé FR affichable (Encre, Bordeaux, Forêt, Prune, Rouille, Graphite)
default(): self (statique) Valeur par défaut centralisée — AccentColor::Encre

L'accès au singleton se fait par SettingRepositoryInterface :

  • getSingleton(): ?Setting — lecture (peut être null avant initialisation) ; utilisé par le runtime Twig ;
  • getOrCreate(): Setting — lecture-ou-création, jamais null ; réservé aux mutations. Consommé par src/Controller/AppAdminSettingsController.php (la page Réglages, /admin/reglages) et par les deux services d'écriture src/Service/Settings/AccentUpdater.php et src/Service/Settings/ClaudeApiKeyUpdater.php ;
  • save(Setting $setting, bool $flush = true): void — persistance.

Variables CSS principales

Les couleurs et la typographie passent exclusivement par des variables CSS définies dans assets/styles/kirexo-ds.css. Aucune valeur hexadécimale en dur dans un template ou une CSS applicative.

Variable Rôle
var(--ink) Couleur de texte principale
var(--ink-2) Texte secondaire
var(--ink-3) Texte discret (méta, dates, aides, fil d'Ariane, placeholders). Discret, mais informatif : contraste ≥ 4,5:1 sur les fonds neutres et les fonds teintés du DS (voir Contrastes garantis).
var(--field-border) Bord des champs de formulaire .input, .textarea, .select. Contraste ≥ 3:1 sur --paper, --surface et --surface-2.
var(--surface) Surface principale
var(--surface-2), var(--surface-3) Surfaces secondaires
var(--paper) Fond de page
var(--line), var(--line-2) Bordures et séparateurs décoratifs (filets, cartes, contours de boutons secondaires). Contraste faible, à ne pas employer pour délimiter un composant d'interface ni pour du texte.
var(--accent) Couleur d'accent (dérivée de data-accent)
var(--accent-hover) Accent au survol
var(--accent-ink) Texte sur fond d'accent
var(--accent-soft), var(--accent-line) Accent atténué et bordure d'accent
var(--font-serif) Typo des corps d'article (Newsreader)
var(--font-sans) Typo de l'interface (Public Sans)

Chaque variable est redéfinie pour [data-theme="dark"] : changer data-theme suffit à basculer toute la palette. Les valeurs sombres sont déclarées une seule fois sous forme de variables --d-* dans :root (--d-ink-3, --d-field-border…), consommées à la fois par [data-theme="dark"] et par le repli @media (prefers-color-scheme: dark) du site public.

La palette e-mail recopie certains tokens en hexadécimal

src/Twig/Runtime/EmailPaletteRuntime.php matérialise les neutres clairs (--surface-2, --surface, --ink, --ink-2, --ink-3, --line) et les six accents clairs (--accent, --accent-ink, --accent-soft) en valeurs hexadécimales, les clients mail ne lisant pas les variables CSS. tests/Unit/Twig/Runtime/EmailPaletteRuntimeTest.php compare ces constantes au thème clair de assets/styles/kirexo-ds.css : modifier l'un de ces tokens sans reporter la valeur dans le runtime fait échouer la CI. Le même test vérifie que les couples employés par les gabarits d'e-mail restent ≥ 4,5:1 (voir Couples vérifiés par la gate). Le pourquoi est expliqué dans E-mails au design system.

Classes d'écran — Édition d'article

L'écran d'édition d'article (espace utilisateur) habille son markup via des classes définies dans la feuille des écrans servie, assets/styles/screens.css. Toutes s'appuient exclusivement sur les variables CSS du DS — aucun hex en dur, donc thème clair/sombre et les six accents sont gérés automatiquement par les tokens.

Classe Rôle
.article-edit Wrapper de la page de l'éditeur (colonne centrée, espacements verticaux).
.article-editor Hôte de l'éditeur Milkdown : corps d'article rendu en var(--font-serif), sur var(--surface) bordé et ombré.
.article-toolbar Barre de formatage au-dessus de l'éditeur. Les boutons sont ciblés par le sélecteur descendant .article-toolbar button (cibles ≥ 44px, anneau :focus-visible préservé) ; l'état actif est porté par .article-toolbar button[aria-pressed="true"] (fond var(--accent), texte var(--accent-ink)).
.article-status Zone d'état de l'enregistrement automatique (autosave), annoncée en aria-live. Hauteur minimale fixe pour éviter le décalage de mise en page. L'élément (templates/user/article/_status.html.twig) porte aussi aria-keyshortcuts="Control+S Meta+S" et un title qui documentent le raccourci d'enregistrement à la demande ; aucun style ne leur est associé.
.article-actions Conteneur des formulaires du cycle de vie de l'article (publier, republier, corbeille…).
.article-unpublish Formulaire de dépublication inline. Le couple label/champ URL est habillé en .field / .input pour la parité visuelle avec le form theme du DS (le champ est du HTML écrit à la main, les classes y sont posées explicitement).

Le hook JS .js-article-editor (attaché via data-controller) n'est pas une cible de style : aucune règle CSS ne lui est attachée.

Classes d'écran — Back-office (réglages, articles, analyse IA)

Les écrans d'administration (tableau de bord, réglages, détail d'article, panneau d'analyse IA, plugins) sont habillés par des classes préfixées bo- définies dans la feuille des écrans servie, assets/styles/screens.css. Comme partout dans le DS, elles s'appuient exclusivement sur les variables CSS : thème clair/sombre et les six accents sont gérés automatiquement par les tokens.

Familles de classes

Famille Écran Rôle
.bo-settings__api, .bo-field Réglages (templates/admin/settings.html.twig) Section « Clé API Claude » sous l'accent (.bo-settings__api) et wrapper label/champ d'un formulaire (.bo-field). L'<input> lui-même est habillé en .input par le form theme du DS, pas par .bo-field.
.bo-dash*, .bo-stat* Tableau de bord (templates/admin/dashboard.html.twig) En-tête (.bo-dash__head), sous-titre (__sub), bloc de liste (__list, __list-title, __count) et état vide (__empty). Les tuiles de filtre par statut d'analyse sont des .bo-stat, en variantes --link et --accent, avec l'état is-active.
.bo-table, .bo-articles*, .bo-row-link, .bo-tag* Table d'articles du tableau de bord Table (.bo-table .bo-articles), extrait tronqué (.bo-articles__excerpt), lien de ligne étendu à toute la cellule par un ::after en inset: 0 (.bo-row-link), et badge d'état d'analyse (.bo-tag--ok / --muted, avec sa pastille .bo-tag__dot).
.bo-article-show* Détail d'article (templates/admin/article/show.html.twig) Conteneur de lecture et ses parties : en-tête (__head), méta auteur/date (__meta), corps publié en var(--font-serif) (__body), section d'analyse (__analysis), note clé API absente (__hint).
.bo-analysis* Panneau analyse IA (templates/admin/article/_analysis.html.twig) Form déclencheur (__form), rapport en carte (__report), avertissement non juridique (__disclaimer), résumé (__summary), chips de thèmes (__themes), grille de conformité (__grid), horodatage (__date).
.bo-plugins, .bo-plugin-* Plugins (templates/admin/plugins.html.twig) Liste des plugins disponibles et de leur état d'activation.
.bo-users*, .bo-invitations*, .bo-table-wrap, .bo-action*, .bo-note*, .bo-disclosure*, .bo-inventory*, .bo-callout*, .bo-btn-purge* Comptes et invitations (templates/admin/users/, templates/admin/invitations/) Voir Composants de la gestion des comptes.

Il n'existe pas d'écran d'index d'articles côté admin

L'admin gère les comptes, jamais le contenu : le seul inventaire d'articles qu'elle expose est celui du tableau de bord, en lecture, adossé au suivi de l'analyse de conformité. Il n'y a ni création, ni édition, ni publication d'article dans le back-office.

Une famille .bo-articles-index* (__head, __lead, __empty) subsiste dans design-system/screens.css : elle n'a aucun consommateur — ni template, ni feuille servie. C'est un résidu de la maquette d'origine, pas une famille utilisable.

Composants de la gestion des comptes

Les écrans de gestion des comptes et des invitations (templates/admin/users/, templates/admin/invitations/) utilisent les composants ci-dessous, regroupés dans le bloc /* === Ticket 245 — finition comptes === */ de assets/styles/screens.css. Ils n'emploient que des variables du DS, aucune opacity, et ne retirent jamais :focus-visible.

Classe Élément Rôle et déclarations clés
.bo-users, .bo-invitations <section> de chaque écran Conteneurs d'écran (min-width: 0). .bo-invitations__head aligne le titre et le bouton Inviter.
.bo-table-wrap <div role="region" tabindex="0" aria-labelledby="…"> autour de chaque <table> Seul ce conteneur défile horizontalement (overflow-x: auto; max-width: 100%), jamais le body. Focalisable au clavier, avec anneau :focus-visible (2px solid var(--focus)). Le nom de la région est la <caption class="sr-only"> du tableau.
.bo-users__table, .bo-invitations__table <table class="bo-table …"> Cellules, en-têtes (white-space: nowrap) et bordures var(--line).
.bo-actions Groupe d'actions d'une ligne ou d'un formulaire display: flex; flex-wrap: wrap; gap: var(--s-2), position: relative; z-index: 1 pour passer au-dessus d'un overlay .bo-row-link. .bo-actions .btn porte min-height: 44px (le .btn-sm du DS fait 34 px).
.bo-action[aria-disabled="true"] <button type="button"> hors formulaire, rendu par _denied_action.html.twig Action affichée mais inopérante, focalisable. Bordure pointillée var(--line-2), fond transparent, cursor: not-allowed, min-height: 44px. Le libellé est en var(--ink-2) (6,8:1 en clair, 7,2:1 en sombre) : ce choix date d'avant le relèvement de --ink-3, quand ce dernier passait encore sous 4,5:1 ; il est conservé pour garder le libellé au niveau des autres actions. L'état inopérant est porté par le pointillé et le curseur, jamais par une opacité.
.bo-action__reason <span> relié au bouton par aria-describedby Raison du refus, issue du Voter : var(--t-xs), var(--ink-2), max-width: 28ch.
.bo-note-row, .bo-note, .bo-note__meta Seconde ligne <tr class="bo-note-row"><td colspan> sous un compte Motif de modération : fond var(--surface-2), texte var(--ink-2), var(--t-sm), max-width: 70ch. .bo-note__meta porte l'action, l'auteur et la date.
.bo-disclosure (+ > summary, __list) <details> natif, sans open, sans JavaScript Encart des comptes supprimés et « Historique des motifs (n) ». summary : min-height: 44px, cursor: pointer, anneau :focus-visible.
.bo-users-deleted Combinée à .bo-disclosure sur l'encart des comptes supprimés Encart bordé var(--line), var(--r-lg), fond var(--surface). Ne redéfinit pas le summary.
.bo-inventory (+ __list) <dl> de _inventory.html.twig Inventaire quantitatif des écrans de suppression et de suppression définitive, en grille dt / dd. Aucun contenu d'article : des nombres, des libellés de présence publique et des rôles.
.bo-effects, .bo-notice Liste des effets (désactivation), notice au-dessus d'un champ justification Texte secondaire var(--ink-2), var(--t-sm).
.bo-callout--danger Encadré d'avertissement des écrans de suppression et de suppression définitive border: 1px solid var(--danger), fond var(--danger-soft), texte var(--ink), var(--r-lg), max-width: 70ch.
.bo-callout--purge Ajoutée à .bo-callout--danger sur l'écran de suppression définitive border-width: 2px.
.bo-callout__title Titre d'un encadré (« Effacement irréversible ») font-weight: 700, color: var(--danger).
.bo-btn-purge (+ __icon) Lien de l'encart et bouton de soumission de la suppression définitive Variante pleine : fond var(--danger), texte var(--paper), font-weight: 600, icône SVG aria-hidden="true". Survol : color-mix(in oklab, var(--danger) 85%, var(--ink)). Contraste mesuré : 7,1:1 en clair, 6,97:1 en sombre.

.bo-callout--danger et .bo-callout--purge n'ont pas de classe de base

Les deux encadrés sont des modificateurs autonomes : il n'existe pas de classe .bo-callout. .bo-callout--danger porte à lui seul tout l'habillage, .bo-callout--purge ne fait que l'épaissir et ne s'emploie qu'avec lui. .bo-callout__title est la seule autre classe de la famille.

Suppression logique et suppression définitive : jamais la couleur seule

La suppression logique utilise .btn.btn-danger (contour) et un .bo-callout--danger qui annonce « rien n'est détruit ». La suppression définitive utilise .btn.bo-btn-purge (plein), le libellé complet « Supprimer définitivement », une icône propre et un encadré .bo-callout--danger.bo-callout--purge titré « Effacement irréversible ». Aucun de ces boutons n'est .btn-primary.

Les états des comptes (Actif, Désactivé) et des invitations (En attente, Expirée) réutilisent .bo-tag--ok et .bo-tag--muted, avec puce .bo-tag__dot et texte. Le fil d'Ariane de ces écrans est une liste ordonnée (.bo-breadcrumb ol), séparateurs posés par li + li::before.

Badges de risque .bo-risk--*

Le panneau d'analyse IA affiche un niveau de risque sous forme de badge. Le modificateur reprend la valeur de l'enum App\Entity\Enum\RiskLevel (src/Entity/Enum/RiskLevel.php) — d'où l'underscore de a_verifier. Chaque niveau mappe vers un couple de tokens sémantiques :

Classe Niveau (RiskLevel) background color
.bo-risk — (badge de base) — —
.bo-risk--aucun None (aucun) var(--surface-2) var(--ink-2)
.bo-risk--faible Low (faible) var(--ok-soft) var(--ok)
.bo-risk--a_verifier ToVerify (a_verifier) var(--warn-soft) var(--warn)
.bo-risk--eleve High (eleve) var(--danger-soft) var(--danger)

aucun est volontairement neutre (gris --ink-2, « rien à signaler ») et non vert : le vert --ok est réservé à faible (risque présent mais mineur).

Préfixe de classes admin : bo-

Les classes propres à l'espace d'administration (back-office) utilisent le préfixe bo- (ex. bo-space__main), jamais ad- — un préfixe ad- est fréquemment bloqué par les bloqueurs de publicité. L'espace utilisateur utilise des classes sans préfixe bo-.

Contraintes RGAA

Le DS garantit plusieurs règles d'accessibilité, à ne jamais contourner :

  • Anneau de focus — l'anneau :focus-visible n'est jamais retiré. La règle vit dans assets/styles/kirexo-ds.css.
  • Lien d'évitement — un skip-link .skip-link (« Aller au contenu ») est le premier enfant du <body> dans templates/base.html.twig et cible #main. Le <main> des layouts utilisateur et admin porte donc id="main".
  • Cibles tactiles ≥ 44px — les composants interactifs du DS (.btn, .input…) garantissent une hauteur minimale de 44px. Le .btn-sm compact (34px) est porté à 44px dans les groupes .bo-actions et par .bo-action[aria-disabled="true"].
  • Action inopérante — une action refusée reste un <button type="button"> focalisable avec aria-disabled="true", jamais l'attribut disabled, et sa raison lui est reliée par aria-describedby (voir Composants de la gestion des comptes).
  • Contrastes — tout texte atteint 4,5:1 et tout bord de composant d'interface 3:1 (voir ci-dessous).

Contrastes garantis

Les tokens de couleur sont dimensionnés pour satisfaire le critère RGAA 3.2 (texte ≥ 4,5:1) et le critère RGAA 3.3 / WCAG 1.4.11 (composants d'interface ≥ 3:1). Valeurs définies dans assets/styles/kirexo-ds.css :

Token Clair Sombre (--d-*) Usage Contraste mesuré
--ink-3 #62666E #969CA7 Texte discret Clair : ≥ 4,5:1 sur --paper, --surface, --surface-2, --surface-3 et sur les fonds teintés (--accent-soft des six accents, --ok-soft, --warn-soft, --danger-soft), minimum mesuré 4,68:1. Sombre : ≥ 4,8:1 sur tous les fonds sombres.
--field-border #80868F #737985 Bord de .input, .textarea, .select ≥ 3:1 sur --paper, --surface et --surface-2, dans les deux thèmes. Sur --paper : 3,67:1 (clair), 4,29:1 (sombre) ; sur --surface et --surface-2 : ≥ 3,36:1.
--line-2 #D2D6DB #373D47 Filets décoratifs uniquement ≈ 1,46:1 en clair : insuffisant pour un composant d'interface, d'où --field-border.

Règles d'emploi qui en découlent :

  • --ink-3 reste du texte informatif. Méta, dates, aides, fil d'Ariane et placeholders (.input::placeholder, .textarea::placeholder) l'utilisent : il ne doit jamais descendre sous 4,5:1, quel que soit le fond du DS sur lequel il est posé.
  • Un champ se délimite par --field-border, pas par --line-2. Au survol, le bord passe en var(--ink-3) ; au focus, en var(--accent) avec un halo.
  • --accent-ink s'emploie uniquement sur --accent, jamais sur --accent-soft. Sur --accent-soft, il tombe à environ 1,2:1 dans les deux thèmes et pour les six accents. C'était le cas du terme surligné de la recherche (.ud-search-mark, assets/styles/pages/espace.css), désormais en var(--ink). Un texte posé sur --accent-soft utilise --ink, --ink-2 ou --ink-3 (couples de la gate).
  • Une barre de défilement stylée par l'auteur est un composant d'interface. Elle perd l'exemption des composants natifs et sa poignée doit atteindre 3:1 : elle passe en var(--field-border).
  • Le lien actif de la navigation admin (.bo-nav a[aria-current="page"], dans assets/styles/screens.css) a un fond var(--accent) et un texte en var(--accent-ink), jamais en blanc fixe : le blanc tombait à 2,42:1 sur les accents du thème sombre, qui sont clairs. Le fond accent ne suffit pas à signaler l'état : sur le fond --s-bg de la barre latérale, il descend à 1,22:1 en thème clair (accent graphite). L'item actif porte donc un repère non coloré : une barre ::before en border-left: var(--s-1) solid var(--s-ink), placée dans la gouttière gauche, hors de la pastille. Elle n'est adjacente qu'à --s-bg et mesure 13,87:1, constant quels que soient le thème et l'accent. Positionnée en absolute, elle ne décale pas l'item et ne chevauche pas l'anneau de focus ; tracée en bordure, elle reste visible en mode forced-colors. Le compteur .count de l'item actif passe en fond var(--s-bg) et texte var(--s-ink) (13,87:1).

Valeurs antérieures

Avant ce relèvement, --ink-3 valait #898E97 (clair) et #757B86 (sombre), sous 4,5:1, et les champs étaient bordés en --line-2.

--ink-3 clair a ensuite valu #666B74 : suffisant sur --paper, --surface et --surface-2, mais sous 4,5:1 sur --danger-soft (4,35:1), sur --surface-3 (4,48:1) et sur l'--accent-soft des accents bordeaux (4,40:1), rouille (4,44:1) et prune (4,48:1). Il est passé à #62666E quand la gate de contraste a étendu la vérification aux fonds teintés.

Couples vérifiés par la gate

La gate tests/Unit/Assets/ContrastTokensTest.php lit assets/styles/kirexo-ds.css, reconstitue la palette de chaque combinaison thème × accent (clair et sombre, six accents, soit douze combinaisons), résout les var() et calcule le contraste WCAG de chaque couple déclaré. Un couple sous son seuil fait échouer la CI ; le message d'échec nomme le thème, l'accent, le couple, le ratio mesuré et le seuil. Aucune valeur hexadécimale n'est recopiée dans le test : seuls les noms de tokens y figurent.

Familles de couples vérifiés :

Famille Texte ou bord Fond Seuil
Encres sur fonds neutres --ink, --ink-2, --ink-3 --paper, --surface, --surface-2, --surface-3 4,5:1
Bord de champ --field-border --paper, --surface, --surface-2 3:1
Accents --accent-ink --accent 4,5:1 (mesuré ≥ 5,3:1 pour les six accents dans les deux thèmes)
Accents --accent --paper, --surface, --surface-2 4,5:1 (mesuré ≥ 5,3:1 pour les six accents dans les deux thèmes)
Fonds teintés --ink, --ink-2, --ink-3 --accent-soft, --ok-soft, --warn-soft, --danger-soft 4,5:1
Fonds teintés --accent --accent-soft 4,5:1
Fonds teintés --ok, --warn, --danger chacun sur son propre fond : --ok-soft, --warn-soft, --danger-soft 4,5:1
Libellés d'état sur carte --warn, --danger --surface 4,5:1

Ajouter un couple : ajouter une ligne à la constante COUPLES de tests/Unit/Assets/ContrastTokensTest.php, avec les clés text (token du texte ou du bord), background (token du fond), min (seuil : 4.5 pour un texte, 3.0 pour un composant d'interface) et why (motif, repris dans le message d'échec). Les deux tokens s'écrivent par leur nom (--ink-3), jamais par leur valeur. Le couple est alors vérifié dans les douze combinaisons.

La gate vérifie aussi que les identifiants des blocs [data-accent] de la feuille correspondent aux cas de l'enum App\Entity\Enum\AccentColor, et que design-system/kirexo-ds.css (source amont) résout chaque token de la table à la même valeur que la feuille servie.

La palette e-mail est vérifiée contre le thème clair de la même feuille par tests/Unit/Twig/Runtime/EmailPaletteRuntimeTest.php : égalité des constantes avec le CSS, puis contraste ≥ 4,5:1 de accentInk sur accent et de ink2 sur accentSoft pour chaque accent, et de ink, ink2, ink3 sur surface et paper (voir l'avertissement La palette e-mail recopie certains tokens en hexadécimal).

Exceptions et indicateurs d'état

Règle de qualification appliquée aux bords et repères du DS : un contrôle (champ, zone éditable, bascule, piste d'interrupteur, lien focalisable isolé) ou un indicateur d'état atteint 3:1 contre ses couleurs adjacentes ; un conteneur, un séparateur ou un contenu est décoratif.

Bouton secondaire (.btn-secondary) — bordé en var(--line-2) dans assets/styles/kirexo-ds.css, sous 3:1. Exception assumée : le bouton est identifié par son libellé en var(--ink), qui satisfait le seuil texte. Aucun bord ≥ 3:1 n'est exigé quand le texte identifie le composant.

--field-border hors des champs — le bord des contrôles qui ne sont pas des champs réutilise --field-border ; il n'existe pas de token dédié de type --control-border. Composants concernés :

Composant Fichier Propriété Contraste mesuré
.theme-toggle (sélecteur de thème) assets/styles/kirexo-ds.css et assets/styles/screens.css border Clair : 3,67:1 sur --paper, 3,36:1 sur --surface-2. Sombre : 3,51:1 sur --surface-2.
.skip-link (lien d'évitement) assets/styles/kirexo-ds.css border Couples --field-border de la gate.
.article-editor--boxed (éditeur encadré) assets/styles/screens.css border Couples --field-border de la gate.
.dest-switch (piste éteinte de l'interrupteur de destination) assets/styles/screens.css background Pastille --surface sur la piste, et piste sur la carte --surface : 3,67:1 (clair), 3,94:1 (sombre).
.editor-link-popin input (champ d'URL de la popin de lien) assets/styles/screens.css border Couples --field-border de la gate.
.ud-card (carte d'article de la frise, un <button>) assets/styles/pages/espace.css border (en tirets pour un brouillon, via border-style: dashed) Couples --field-border de la gate.
.ud-fold-summary (ligne-résumé d'un carnet plié, un <button>) assets/styles/pages/espace.css border Couples --field-border de la gate.
.ud-field input (champs « Titre » et « Tagline » de la modale de carnet) assets/styles/pages/espace.css border, fond var(--surface) comme .input Couples --field-border de la gate.
.ud-search (champ de recherche ; l'<input> interne est sans bord) assets/styles/pages/espace.css border Couples --field-border de la gate.
.ud-search-row:hover (survol d'un résultat de recherche, un <button>) assets/styles/pages/espace.css border-color (bord transparent au repos) Couples --field-border de la gate.
Poignée de défilement de .ud-timeline (frise, région tabindex="0") assets/styles/pages/espace.css scrollbar-color sur .ud-timeline, background de .ud-timeline::-webkit-scrollbar-thumb Couples --field-border de la gate.

Au survol, .ud-card (.ud-stop:hover .ud-card) et .ud-fold-summary passent en var(--ink-3), comme les champs du DS : le survol reste distinct du repos et dépasse 4,5:1 sur --surface. Les deux règles de la poignée de frise portent la même couleur, car Chromium ignore les pseudo-éléments ::-webkit-scrollbar* dès que scrollbar-color est défini.

.theme-toggle est déclaré dans les deux feuilles : assets/app.js importe screens.css après kirexo-ds.css, la déclaration de screens.css est donc celle appliquée. Les deux portent --field-border.

Tokens de la barre latérale admin (--s-*) — --s-bg, --s-ink, --s-ink2, --s-line et --s-hover sont déclarés sur .bo-side dans assets/styles/screens.css. La barre latérale reste sombre dans les deux thèmes : ces valeurs sont des constantes, indépendantes du thème et de l'accent. La gate ne les vérifie pas, car elle ne lit que assets/styles/kirexo-ds.css. Mesures de référence :

Texte ou repère Fond Contraste
--s-ink --s-bg 13,87:1
--s-ink2 --s-bg 6,41:1
--s-ink --s-hover 12,19:1

--s-line borde des éléments décoratifs (étiquette .bo-brand .tag, filet du pied de barre). Toute modification du bloc .bo-side ou d'une valeur --s-* impose de remesurer ces trois couples et de mettre ce tableau à jour.

Repères d'état :

  • Bouton pressé du sélecteur de thème (.theme-toggle__btn[aria-pressed="true"]) — le fond --surface sur --surface-2 ne suffit pas (≈ 1,1:1). Le bouton actif porte un anneau intérieur box-shadow: inset 0 0 0 1px var(--field-border), qui ne modifie pas la taille du bouton et reste distinct de l'anneau de focus.
  • Accent coché dans les réglages admin (.bo-accent, templates/admin/settings.html.twig) — l'état coché est signalé par un bord var(--accent), ≥ 5,3:1 sur --surface (couple de la gate). Chaque label.bo-accent porte data-accent mais pas data-theme : la bascule [data-theme="dark"][data-accent] posée sur <html> ne l'atteint pas. La règle [data-theme="dark"] .bo-accent[data-accent] rebascule --accent, --accent-soft et --accent-line sur leurs variantes --da-*, pour que pastille et bord coché prennent la teinte sombre.
  • Item actif de la navigation admin — voir la puce « Le lien actif de la navigation admin » de Contrastes garantis.

Exemptions (WCAG 1.4.11) :

  • Glyphe de marque (.bo-brand .glyph) — logotype, exempté. Son texte passe néanmoins en var(--accent-ink), comme .wordmark .glyph ; le contraste de son fond --accent sur --s-bg n'est pas exigé.
  • Composant inactif (.bo-action[aria-disabled="true"]) — bord pointillé --line-2, exempté en tant que composant inactif. Son libellé reste en var(--ink-2) et sa raison est fournie en texte (voir Composants de la gestion des comptes).
  • Pastilles doublées d'un libellé — les pastilles de canal (.bo-chan, .ud-plugin-label) et d'état de plugin (.plugin-state-dot) sont aria-hidden et toujours accompagnées d'un libellé texte (.bo-plugin-label dans templates/admin/plugins.html.twig, .plugin-state-text dans templates/components/PluginToggle.html.twig). Elles sont décoratives.

Cas décoratifs et exemptions

Les sélecteurs ci-dessous restent en var(--line) ou var(--line-2) (ou affichent un repère sous 3:1) parce qu'ils ne délimitent aucun contrôle. Ils sont qualifiés selon la règle de Exceptions et indicateurs d'état : conteneur, séparateur, étiquette non interactive, repère doublé d'un texte ou élément aria-hidden. Le raisonnement qui fonde cette règle est développé dans la page d'explication du design system.

Espace utilisateur

Sélecteur Fichier Raison
.ud-notebook, .ud-preview, .ud-modal, .ud-notebook-menu-list, .ud-domain-row, .ud-sp-row, .ud-theme-row, .ud-capabilities assets/styles/pages/espace.css Conteneurs : carte de carnet, modale d'aperçu, <dialog> de carnet, panneau du menu ⋯ (ses entrées n'ont pas de bord), lignes de liste, panneau des capacités. Les contrôles qu'ils contiennent portent leur propre bord.
.ud-tabbar, .ud-preview-excerpt, .ud-notebook-menu-list hr, .ud-sp-divider, .ud-theme-help, .ud-css-editor, .ud-capabilities-disclosure assets/styles/pages/espace.css Séparateurs. .ud-sp-divider est un <li role="presentation"> doublé d'un libellé texte ; la saisie de .ud-css-editor se fait dans un textarea.input, déjà en --field-border.
.ud-ch, .ud-today-lbl, .ud-capability-list li assets/styles/pages/espace.css Étiquettes non interactives (<span>, <li>).
.ud-track::before, .ud-today assets/styles/pages/espace.css Repères de frise : axe horizontal, et repère vertical « Aujourd'hui » doublé du libellé .ud-today-lbl.
.ud-theme-choice assets/styles/pages/espace.css Cadre de groupement d'un choix de thème. Le contrôle est le radio natif visible, qui l'identifie ; l'état coché est porté par le radio et par un bord var(--accent) (≥ 5,3:1).
.ud-blank-icon, .ud-notebook-mark assets/styles/pages/espace.css Pastilles aria-hidden="true" (--accent sur --accent-soft), décoratives.

Thèmes publics

Sélecteur Fichier Raison
Filets .site-header, .site-card, .site-article-footer, .site-pagination, .site-footer ; pre, hr, th/td du corps src/Plugin/Web/themes/default/theme.css Séparateurs de mise en page, bloc de code et cellules. pre et table sont des conteneurs à défilement horizontal : leur bord n'identifie pas un contrôle.
Filet .site-card ; pre, th/td du corps src/Plugin/Web/themes/classic/theme.css Filet entre articles, bloc de code, cellules. Les autres filets du thème sont en var(--ink).
Filets .site-article-footer, .site-footer ; blockquote (border-left), th/td du corps src/Plugin/Web/themes/minimal/theme.css Filets, citation, cellules.
code du corps src/Plugin/Web/themes/default/theme.css, src/Plugin/Web/themes/classic/theme.css, src/Plugin/Web/themes/minimal/theme.css Sans bord ; texte var(--ink) sur var(--surface-2) lorsqu'un fond est posé, couple de la gate.

Aucun contrôle n'est bordé dans les thèmes publics : les liens de navigation et de pagination n'ont pas de bord, le lien d'évitement est le .skip-link du DS et le focus est l'anneau global. Les thèmes ne redéfinissent aucun token (ni variable --*, ni hexadécimal) : ils héritent des valeurs vérifiées par la gate, accent d'instance et repli sombre prefers-color-scheme compris.

DS de base

Sélecteur Fichier Raison
.tag, .chan, .card, .notice, .topbar, .section, .swatch, .spec-row assets/styles/kirexo-ds.css Éléments non interactifs : étiquettes, pastilles de canal, surfaces, bandeau, sections et lignes de spécification.

Chrome de revue du DS

Sélecteur Fichier Raison
.accent-picker (dont .accent-picker .sw) assets/styles/kirexo-ds.css Sélecteur d'accent de la page de revue du DS, absent des templates produit.
.accent-picker .sw[aria-pressed="true"]::after assets/styles/kirexo-ds.css Point central en background: #fff avec mix-blend-mode: difference. C'est un fond, pas une couleur de texte, dans le même chrome de revue hors produit.
.switcher (dont .switcher .seg) assets/styles/screens.css Sélecteur d'écran des maquettes du DS, absent des templates produit.

Chargement des assets

Les CSS et les scripts du DS sont importés depuis assets/app.js :

import './bootstrap.js';
import './styles/app.css';
import './styles/kirexo-ds.css';
import './styles/screens.css';
import './js/accent.js';
import './js/theme.js';
import './js/user-menu.js';

app.js est le seul entrypoint injecté dans templates/base.html.twig via {{ importmap('app') }}. Cet appel injecte automatiquement les <link> des CSS importés — il ne faut donc pas lier kirexo-ds.css une seconde fois via asset() (double chargement). Les trois scripts sont chargés sur toute page héritant du layout par les import relatifs d'app.js, qu'AssetMapper suit et versionne seul. Deux d'entre eux — accent et theme — sont en plus déclarés dans importmap.php comme modules importables (sans entrypoint), ce qui les rend adressables par un specifier nu ; user-menu.js ne l'est pas, et n'en a pas besoin.

Certaines pages ajoutent leur propre feuille scopée en empilant un second entrypoint — {{ importmap(['app', 'espace']) }} sur /u, par exemple.

Voir aussi