Créer le thème de votre équipe

Un thème fixe les couleurs, la police, les tailles et les fonds des présentations. C'est un dossier qui contient un manifeste theme.json et une feuille de style SCSS construite sur le paquet @vignettes/theme-kit. Vous écrivez ce dossier et vous le vérifiez dans un studio installé sur votre ordinateur, puis l'exploitant de votre instance le publie. Chaque présentation choisit ensuite le thème par la clé theme de son en-tête.

Installer le studio sur votre ordinateur

Le dépôt GitHub ShallowRed/vignettes contient le studio. Ce dépôt est privé : votre compte GitHub doit pouvoir le lire. mise installe Node 22 et pnpm, puis lance les tâches du dépôt.

git clone https://github.com/ShallowRed/vignettes.git
cd vignettes
mise install
mise run setup

mise run setup écrit le fichier .env, installe les dépendances et crée la base de données locale.

Le studio lit les thèmes dans deux dossiers : themes/, qui contient les thèmes de l'application, dsfr et minimal, et presentations/themes/, qui contient les thèmes de votre instance. Git ignore le dossier presentations/. Si votre instance garde ses présentations et ses thèmes dans un dépôt, clonez ce dépôt sous le nom presentations.

Copier le thème d'exemple

Le thème examples/themes/exemple-marque est un thème complet : il règle les jetons, peint les diapositives de section et décrit sa carte du catalogue. Choisissez le nom de votre thème, en minuscules et avec des tirets, puis copiez l'exemple sous ce nom. Ce nom désigne à la fois le dossier, la clé name du manifeste, le fichier SCSS et la valeur de la clé theme des présentations. Il doit être différent de dsfr et de minimal. Sur cette page, le thème s'appelle mon-equipe :

mkdir -p presentations/themes
cp -R examples/themes/exemple-marque presentations/themes/mon-equipe
mv presentations/themes/mon-equipe/exemple-marque.scss presentations/themes/mon-equipe/mon-equipe.scss

Dans presentations/themes/mon-equipe/theme.json, remplacez exemple-marque par mon-equipe. Le thème peut aussi contenir un dossier assets/, pour ses polices et ses images.

Régler le manifeste

Le manifeste theme.json contient les clés suivantes :

• name est le nom du thème, identique au nom du dossier.
• lang est la langue par défaut des présentations. Avec fr, le moteur applique la typographie française.
• parser est le découpage des diapositives par défaut : heading découpe aux titres, separator aux lignes ---. Une présentation peut choisir l'autre découpage dans son en-tête.
• code choisit les couleurs des blocs de code par défaut : clair, sombre ou nuit.
• reveal contient des réglages de reveal.js, ici l'affichage du numéro de la diapositive.
• preview décrit la carte d'une présentation dans le catalogue : la police, la couleur du titre, la couleur du texte et le fond. Le catalogue dessine cette carte sans charger la feuille du thème. Reportez-y les couleurs de votre thème.

La référence du système de thèmes décrit les autres clés, dont backgrounds, qui associe une image de fond à chaque niveau de titre, et aliases, qui fait correspondre au thème un nom que vos présentations utilisent déjà.

Régler la feuille de style

Les trois premières lignes de mon-equipe.scss chargent le kit de thèmes :

• pkg:@vignettes/theme-kit contient les règles dont les composants ont besoin : la structure des diapositives, la grille des mises en page media-*, les corrections de reveal.js et une valeur par défaut pour chaque jeton. Chaque thème le charge.
• pkg:@vignettes/theme-kit/base applique les neuf jetons de couleur au fond, au texte, aux titres, aux liens, au code en ligne, aux citations, aux puces et aux flèches de navigation, avec la police du système. Un thème qui dessine lui-même ces éléments omet cette ligne.
• pkg:@vignettes/theme-kit/presets/layout donne les tailles de titre et les espacements du DSFR, sans ses couleurs ni sa police. C'est le seul preset du kit. Un thème qui fixe ses propres tailles omet cette ligne.

Régler les jetons

Le bloc :root règle les douze jetons que lisent les composants. Remplacez leurs valeurs par les couleurs de votre équipe :

• --accent est la couleur principale : liens, puces, contour des boîtes d'un diagramme. --accent-soft en est une teinte claire, et --accent-bg une teinte très claire, qui colore le fond du code en ligne et des boîtes d'un diagramme.
• --surface est le fond des diapositives. --surface-contrast est une surface sombre, et --on-contrast la couleur du texte posé sur elle.
• --text-title colore les titres et le texte en gras, --text-default le texte courant, --text-mention les légendes et les petits caractères.
• --border, --radius et --shadow donnent le contour, les coins et l'ombre des boîtes que dessinent les composants.

Un jeton omis prend la valeur par défaut du kit : un gris neutre, avec un accent bleu. Le kit calcule trois jetons de plus à partir des jetons de texte, --on-surface-title, --on-surface-default et --on-surface-mention : un thème ne les règle pas.

Peindre les diapositives de section

Le moteur donne à chaque diapositive une classe selon le niveau de son premier titre : slide-h1 pour la diapositive de titre (#), slide-h2 pour une diapositive de section (##), slide-h3 pour une diapositive de contenu (###). Avec le découpage heading, chaque diapositive ouverte par un titre ## reçoit la classe slide-h2, y compris quand elle contient des paragraphes ou une liste, et le thème la peint comme une section.

Les deux dernières règles de l'exemple peignent les sections avec --surface-contrast :

• La règle .reveal .slide-background.slide-h2 colore l'élément de fond que reveal.js place derrière chaque diapositive. reveal.js donne à cet élément les classes de la diapositive et l'étend à tout l'écran, quelle que soit sa proportion. La règle colore aussi l'export PDF et la vue défilante du téléphone, où reveal.js place cet élément ailleurs dans la page. reveal.js lit sa couleur et ajoute la classe has-dark-background, qui passe ses flèches de navigation en clair.
• La règle .reveal section.slide-h2 passe les jetons de texte et les liens en clair sur la section. Les diapositives verticales rangées sous la section ont leur propre classe et gardent leur texte sombre.

Sur une section, une boîte dessinée par un composant, comme celle d'un diagramme, garde son fond clair et son texte sombre : elle lit les jetons --on-surface-*, calculés pour toute la page.

Pour une image de fond, la clé backgrounds du manifeste associe une image du dossier assets/ à un niveau de titre : "backgrounds": { "h2": "assets/section.png" }.

Partir du thème DSFR

Pour garder la police Marianne, la palette et la mise en forme des composants du DSFR, remplacez les trois lignes du kit et le bloc :root par le paquet @vignettes/theme-dsfr, qui charge lui-même le kit et le preset layout. On règle ses couleurs par ses variables Sass, avant de charger le thème :

@use 'pkg:@vignettes/theme-dsfr/variables' with (
  $dsfr-blue-france-sun-113: #7c2d12,
  $dsfr-blue-france-main-525: #c2410c,
  $dsfr-blue-france-850: #fed7aa,
  $dsfr-blue-france-950: #fff7ed
);
@use 'pkg:@vignettes/theme-dsfr';

Le thème DSFR associe --accent à $dsfr-blue-france-main-525, --accent-soft à $dsfr-blue-france-850 et --accent-bg à $dsfr-blue-france-950, et colore le survol des liens avec $dsfr-blue-france-sun-113. Le fichier _variables.scss liste les variables, et la référence du paquet décrit ses entrées. Pour peindre les diapositives de section, gardez les deux règles de la section précédente.

Choisir la police

Placez les fichiers de la police dans assets/fonts/, puis déclarez-la dans un fichier _fonts.scss du dossier du thème. Le studio sert le dossier assets/ à l'adresse /themes/mon-equipe/assets/ :

@font-face {
  font-family: Equipe;
  font-weight: 400;
  font-display: swap;
  src: url('/themes/mon-equipe/assets/fonts/Equipe-Regular.woff2') format('woff2');
}

Dans mon-equipe.scss, ajoutez @use 'fonts'; aux autres @use, puis appliquez la police aux diapositives :

.reveal {
  font-family: Equipe, system-ui, sans-serif;
}

Pour que la carte du catalogue affiche la même police, ajoutez "fonts": "fonts" dans preview et mettez Equipe en tête de fontFamily. Le studio compile alors _fonts.scss à part pour le catalogue.

Afficher le thème dans le studio local

Lancez le studio :

mise run dev:nuxt

La commande compile les thèmes, puis sert le studio sur http://localhost:3000. Quand vous enregistrez un fichier .scss du thème, le studio le compile de nouveau et recharge la page. Après une modification de theme.json, arrêtez le serveur et relancez la commande.

Ouvrez http://localhost:3000/auth/dev-login?role=owner pour vous connecter sans compte GitHub ni Google : cette adresse répond seulement en développement.

La présentation de contrôle examples/controle-du-theme.md contient chaque rôle de diapositive et chaque élément que colore un thème. Copiez-la, puis remplacez exemple-marque par mon-equipe dans sa clé theme :

cp examples/controle-du-theme.md controle-du-theme.md

Importez ce fichier dans le studio, comme le décrit Importer le fichier dans le studio : le champ « Thème » affiche mon-equipe, et la baguette remplit le champ « Slug » avec controle-du-theme. Publiez la présentation, puis ouvrez http://localhost:3000/slides/controle-du-theme.

Vérifier le thème

Lisez chaque diapositive de la présentation de contrôle, en largeur d'ordinateur puis en 390 pixels de large avec le mode adaptatif des outils de développement du navigateur. La section Checking a theme de la référence liste ce qu'il faut vérifier : le contraste de chaque couple de couleurs, le code en ligne coupé en fin de ligne, les diagrammes sur une diapositive de contenu et sur une section, la vue défilante du téléphone et l'export PDF.

Faire publier le thème

L'exploitant de votre instance publie les thèmes, parce que la commande de publication demande les clés du stockage de l'instance. Il compile le thème dans son propre clone du studio. La feuille de style peut donc charger pkg:@vignettes/theme-kit, pkg:@vignettes/theme-dsfr et les fichiers du dossier du thème, et les polices et les images doivent se trouver dans assets/.

Envoyez-lui :

• le dossier du thème, theme.json, le fichier SCSS, _fonts.scss s'il existe et assets/, en archive, ou par un commit dans le dépôt des présentations de l'instance ;
• le nom du thème, et les noms que vos présentations utilisent déjà s'il doit les reprendre par la clé aliases.

Demandez-lui :

1. de placer le dossier dans presentations/themes/ de son clone du studio ;
2. de lancer mise run theme:push -- mon-equipe, qui compile le thème et liste les fichiers à envoyer sans rien écrire, puis mise run theme:push -- mon-equipe --apply, qui envoie la feuille compilée, les fichiers de assets/ et les réglages du manifeste dans le stockage de l'instance ;
3. de vous prévenir quand la commande affiche ✓ published.

L'instance relit la liste des thèmes publiés au bout d'une minute au plus. Un Propriétaire du studio peut forcer cette lecture par une requête POST /api/admin/themes/reload. Le thème apparaît alors dans le champ « Thème » de la fenêtre « Nouvelle présentation ». Pour l'appliquer à une présentation existante, écrivez theme: mon-equipe dans son en-tête, puis publiez-la.

Pour une nouvelle version du thème, faites la même demande : la commande remplace les fichiers publiés sous le même nom.

Le plugin vignettes-decks de Claude Code contient aussi les règles d'écriture d'un thème : après son installation, commencez la demande par /vignettes-decks:writing-themes.