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é
localStoragekirexo-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-themesur<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 :
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 êtrenullavant initialisation) ; utilisé par le runtime Twig ;getOrCreate(): Setting— lecture-ou-création, jamaisnull; réservé aux mutations. Consommé parsrc/Controller/AppAdminSettingsController.php(la page Réglages,/admin/reglages) et par les deux services d'écrituresrc/Service/Settings/AccentUpdater.phpetsrc/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-visiblen'est jamais retiré. La règle vit dansassets/styles/kirexo-ds.css. - Lien d'évitement — un skip-link
.skip-link(« Aller au contenu ») est le premier enfant du<body>danstemplates/base.html.twiget cible#main. Le<main>des layouts utilisateur et admin porte doncid="main". - Cibles tactiles ≥ 44px — les composants interactifs du DS (
.btn,.input…) garantissent une hauteur minimale de 44px. Le.btn-smcompact (34px) est porté à 44px dans les groupes.bo-actionset par.bo-action[aria-disabled="true"]. - Action inopérante — une action refusée reste un
<button type="button">focalisable avecaria-disabled="true", jamais l'attributdisabled, et sa raison lui est reliée pararia-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-3reste 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 envar(--ink-3); au focus, envar(--accent)avec un halo. --accent-inks'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 envar(--ink). Un texte posé sur--accent-softutilise--ink,--ink-2ou--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"], dansassets/styles/screens.css) a un fondvar(--accent)et un texte envar(--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-bgde 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::beforeenborder-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-bget mesure 13,87:1, constant quels que soient le thème et l'accent. Positionnée enabsolute, elle ne décale pas l'item et ne chevauche pas l'anneau de focus ; tracée en bordure, elle reste visible en modeforced-colors. Le compteur.countde l'item actif passe en fondvar(--s-bg)et textevar(--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--surfacesur--surface-2ne suffit pas (≈ 1,1:1). Le bouton actif porte un anneau intérieurbox-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 bordvar(--accent), ≥ 5,3:1 sur--surface(couple de la gate). Chaquelabel.bo-accentportedata-accentmais pasdata-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-softet--accent-linesur 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 envar(--accent-ink), comme.wordmark .glyph; le contraste de son fond--accentsur--s-bgn'est pas exigé. - Composant inactif (
.bo-action[aria-disabled="true"]) — bord pointillé--line-2, exempté en tant que composant inactif. Son libellé reste envar(--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) sontaria-hiddenet toujours accompagnées d'un libellé texte (.bo-plugin-labeldanstemplates/admin/plugins.html.twig,.plugin-state-textdanstemplates/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¶
- Pourquoi un accent d'instance piloté serveur — accent (serveur) vs thème (client), cohérence multi-appareils, dégraissage d'
accent.js. - Form theme du design-system — mapping des widgets Symfony vers les composants DS (
.field,.input,.btn…). - Espaces utilisateur et admin — les pages qui héritent des layouts DS.