🖼️ Gestion des images

Les images dans Kutsum sont gérées de manière à offrir une expérience optimale tant pour les enseignants que pour les élèves, notamment en ce qui concerne le support du mode sombre.

Images sensibles au thème (Theme-aware images)

Pour garantir que les images des questions soient lisibles aussi bien en mode clair qu'en mode sombre, Kutsum utilise une convention de nommage simple.

Convention de nommage

Si une image possède une variante spécifique pour le mode sombre, elle doit être nommée avec le suffixe .dark avant l'extension.

  • Image standard (mode clair) : mon-image.svg
  • Variante sombre : mon-image.dark.svg

L'application détectera automatiquement la présence de la variante sombre et l'affichera lorsque l'utilisateur est en mode sombre.

Fonctionnement technique

  1. Synchronisation : Le script de synchronisation des images (sync-images.ts) détecte les fichiers .dark et les copie dans le dossier public de l'application, mais les exclut de l'index de la base de données pour qu'ils n'apparaissent pas comme des choix séparés dans le sélecteur d'images.
  2. Affichage : Le composant ThemeAwareImage (utilisé partout dans l'application) surveille le thème actuel. S'il détecte que l'utilisateur est en mode sombre, il tente de charger la version .dark.
  3. Fallback : S'il n'y a pas de variante sombre (ou si le chargement Ă©choue), l'application affiche l'image standard.

Recommandations

  • SVG : PrivilĂ©giez le format SVG pour les schĂ©mas et diagrammes.
  • Contraste : Assurez-vous que vos images standard sont lisibles sur fond clair et que vos images .dark sont lisibles sur fond sombre.
  • Poids : Optimisez la taille de vos images pour garantir des temps de chargement rapides.

Règles strictes de nommage et métadonnées (convention canonique)

À partir de la convention de base ci‑dessus, Kutsum suit une convention canonique stricte pour les fichiers et les métadonnées YAML. Respecter ces règles est obligatoire : tout fichier qui ne correspond pas au motif doit être rejeté au moment du build ou de l'import.

Format canonique de fichier

Canonical format

<ref>.<theme>.<format>

Exemple

geo-europe-political.light.webp geo-europe-political.dark.webp

<ref> — Identifiant logique de l'image

  • ReprĂ©sente le concept d'image (pas le fichier lui‑mĂŞme)
  • Doit ĂŞtre globalement unique et stable dans le temps
  • UtilisĂ© partout dans le contenu et la base de donnĂ©es

Règles pour ref

  • uniquement minuscules
  • caractères autorisĂ©s : a–z, 0–9, -
  • pas d'espaces, pas d'underscores, pas d'accents
  • kebab-case
  • descriptif mais concis

Exemples valides

  • geo-europe-political
  • math-quadratic-function-graph
  • bio-human-skull-labeled

<theme> — variante UI

Valeurs autorisées

  • light
  • dark

<format> — format de fichier

Valeurs autorisées

  • webp (par dĂ©faut)
  • png (exceptionnel)
  • svg (vecteur seulement)

Validation (regex)

^[a-z0-9]+(-[a-z0-9]+)*\.(light|dark)\.(webp|png|svg)$

Toute image ne respectant pas ce motif doit être rejetée lors du build ou de l'import.

Métadonnées YAML

Chaque concept d'image doit être décrit dans un fichier YAML. Le ref y figure, sans thème ni format.

Structure minimale

ref: geo-europe-political
title: Political map of Europe
description: Map of Europe with countries shown in distinct colors
disciplines: [geography, history]
tags: [Europe, countries, map, political]
author: alexis
variants:
   light: true
   dark: true

Règles YAML

  • ref ne doit pas inclure de thème ni de format
  • ref doit respecter la convention de nommage des fichiers
  • variants doit reflĂ©ter les fichiers rĂ©ellement prĂ©sents
  • chaque image doit au minimum avoir une variante light
  • le YAML est la source Ă©ditoriale de vĂ©ritĂ© — le système se base sur ces fichiers

Référence dans le contenu

Pour insérer une image en contenu, utiliser la référence :

[image: geo-europe-political]

L'application sélectionne automatiquement la variante light ou dark selon le thème de l'utilisateur.

Principe de conception

Le nom de fichier est un détail d'implémentation. Le ref est le contrat.

Ajout d'images à la base de données

Les images utilisées dans les questions sont gérées de manière centralisée pour assurer la qualité et la cohérence. Aucune image personnelle n'est autorisée - seules les images validées et curatées peuvent être ajoutées.

Processus d'ajout

  1. Soumission : Les images peuvent ĂŞtre soumises via GitLab ou Tchap pour validation par les administrateurs.

  2. Format et spécifications :

    • Format prĂ©fĂ©rĂ© : SVG (vectoriel, s'adapte Ă  toutes les rĂ©solutions)
    • Format alternatif : WebP avec rĂ©solution maximale de 800px
    • Domaines : Les images doivent ĂŞtre dans le domaine public
    • Thèmes : Si possible, fournir deux versions :
      • Version claire : nom-image.svg ou nom-image.webp
      • Version sombre : nom-image.dark.svg ou nom-image.dark.webp
    • SVG sans variante sombre : Les couleurs seront automatiquement inversĂ©es par le frontend pour le mode sombre

  3. Métadonnées : Chaque image doit être accompagnée d'un fichier YAML de description contenant :

    • Titre
    • Description
    • Tags
    • Niveaux scolaires
    • Discipline

  4. Validation : Les administrateurs valident la qualité, la pertinence pédagogique et le respect des droits avant ajout à la base.

  5. Intégration : Une fois validées, les images sont ajoutées au dossier questions/images/ et synchronisées en base via le script sync-images.ts.

Avantages du système centralisé

  • QualitĂ© garantie : Toutes les images sont validĂ©es pour leur pertinence et leur qualitĂ©.
  • AccessibilitĂ© : Disponibles pour tous les enseignants une fois en base.
  • Maintenance : Mises Ă  jour et corrections centralisĂ©es.
  • Performance : Optimisation automatique et mise en cache.
Dernière mise à jour:
Contributors: alexisflesch