Thèmes

core/themes porte l'apparence de tout le projet : le theme.js qui la décrit, les jetons CSS que les composants écrivent, et la bascule clair / sombre. Un composant n'écrit jamais une nuance de palette, seulement un jeton : c'est ce qui permet à un seul fichier de changer l'admin, les pages publiques, les modules, les courriels et les PDF en même temps.

ImportCopier le lien de la section

// Déclaration, dans le theme.js du projet. Module neutre.
import { defineTheme, resolveTheme } from '@fraza/core/themes/define';

// Lecture côté serveur : layout racine, courriels, PDF.
import { ThemeStyle, getTheme, getThemeValues } from '@fraza/core/themes/server';

// Bascule clair / sombre, côté client.
import {
  getStoredTheme, applyTheme, getAllowedModes, getThemeIcon,
  ThemeWatcher, useTheme, THEME_INIT_SCRIPT,
} from '@fraza/core/themes';

@fraza/core/themes est marqué 'use client'. @fraza/core/themes/server ne s'importe que côté serveur. @fraza/core/themes/define n'a aucune dépendance et se charge partout.

APICopier le lien de la section

defineTheme(options)Copier le lien de la section

Toutes les options sont facultatives. Sans elles, l'apparence est celle de la charte : noir, blanc et gris, accent bleu fleuve #2457c5, bouton principal à l'encre, sidebar.

// theme.js
import { defineTheme } from '@fraza/core/themes/define';

export default defineTheme({
  accent: '#0f766e',
  neutral: 'stone',
  chrome: 'dark',
  shell: 'topbar',
  overrides: { light: { canvas: '#f3f2ef' } },
});

Calcul de l'accentCopier le lien de la section

Sans accent, ou avec accent: '#2457c5' écrit en toutes lettres, les jetons d'accent prennent les valeurs exactes de la charte. Sinon, le core les calcule en OKLCH à partir de la couleur donnée :

accent-soft, accent-line, info-soft, info-line et info-ink suivent en CSS, par color-mix().

Déclinaisons des statutsCopier le lien de la section

Les fonds pâles (-soft), les bordures (-line) et les encres (-ink) de danger, success et warning sont des teintes fixes de la charte, pas des mélanges. Un overrides qui change la couleur d'un de ces statuts sans donner ses déclinaisons les reçoit calculées par resolveTheme() :

Une déclinaison écrite dans overrides est gardée telle quelle. Un rouge changé n'hérite donc jamais du fond rose et du texte bordeaux d'un autre rouge.

Quand la couleur donnée est trop pâle, defineTheme écrit un avertissement au démarrage, qui nomme la valeur, son contraste et la valeur retenue. Le démarrage continue :

⚠ defineTheme: `accent` #ffcc00 est trop pâle sur blanc (1.51:1, minimum 4.5:1). #907200 est utilisé en clair.

Ici, #907200 est utilisé en clair et #ffcc00 reste l'accent en sombre. L'avertissement est écrit une fois par environnement qui charge theme.js, Node et edge. Une valeur qui n'est pas une couleur hex, 'blue' par exemple, fait échouer le démarrage.

Calcul du bouton principalCopier le lien de la section

Avec une couleur hex, primary donne primary, primary-hover et primary-fg : le survol, une version plus claire pour le mode sombre (une couleur foncée se perdrait sur le noir), et le texte posé dessus, blanc ou noir selon le contraste. Sans option accent, l'accent est alors tiré de primary par le calcul ci-dessus.

Une valeur hors liste lève au démarrage, avec le nom des valeurs admises. Une faute de frappe ne produit donc jamais un admin illisible en silence.

<ThemeStyle />Copier le lien de la section

À placer dans le <head> du layout racine. Rend deux balises :

1. Un <style> qui ne contient que les jetons dont la valeur diffère des défauts de core.css. Sans theme.js, ou avec un theme.js qui ne porte que les défauts, il n'est pas rendu.
2. Le script anti-flash, qui pose la classe dark sur <html> avant le premier rendu. Il respecte modes et pose data-fraza-modes sur <html> pour les bascules. Sa balise porte l'identifiant fraza-theme-init et les modes dans data-modes, que ThemeWatcher relit quand le script n'a pas été exécuté.

// app/layout.js
import { ThemeStyle } from '@fraza/core/themes/server';

export default function RootLayout({ children }) {
  return (
    <html lang="fr" suppressHydrationWarning>
      <head>
        <ThemeStyle />
      </head>
      <body>{children}</body>
    </html>
  );
}

getTheme() et getThemeValues(mode)Copier le lien de la section

Le thème est enregistré par initializeFraza({ modules, theme }), depuis instrumentation.js. getTheme() le lit. Sans thème enregistré, il renvoie l'apparence par défaut.

getThemeValues('light') renvoie les valeurs hex d'un mode, clés au nom des jetons. Il sert à tout ce qui ne lit pas les variables CSS : un PDF, un style inline de courriel.

import { getThemeValues } from '@fraza/core/themes/server';

function getPdfPalette() {
  const t = getThemeValues('light');
  return { ink: t.fg, muted: t['fg-muted'], rule: t.line, paid: t.success };
}

Les déclinaisons calculées en CSS par color-mix() y sont mélangées contre la surface, au même dosage que core.css. accent-soft vaut 8 % d'accent en clair et 14 % en sombre : #edf2fa et #1b212c avec l'accent par défaut. accent-line vaut 35 %, primary-soft 10 %. info-soft vaut 8 % en clair et 16 % en sombre, info-line 20 % et 30 %, et info-ink vaut info.

Les déclinaisons de danger, success et warning sont des jetons, renvoyés tels quels : danger-soft, danger-line, danger-ink, etc. Les voiles du mode sombre, écrits en rgb(… / 0.15), y sont aplatis sur la surface en hex.

Pour les courriels, @fraza/core/email/templates expose des raccourcis : voir Courriel.

useTheme()Copier le lien de la section

Retourne { theme, toggle, systemIsDark, canToggle } et synchronise l'état avec localStorage et le système au montage.

Le cycle dépend de la préférence système, pour que le premier basculement produise toujours un changement visible :

• Système clair : auto → dark → light → auto
• Système sombre : auto → light → dark → auto

import { useTheme, getThemeIcon } from '@fraza/core/themes';

export function ThemeToggle() {
  const { theme, toggle, canToggle } = useTheme();
  if (!canToggle) return null;
  const Icon = getThemeIcon(theme);
  return <button onClick={toggle}><Icon /></button>;
}

applyTheme(theme) et getStoredTheme()Copier le lien de la section

getStoredTheme() retourne 'light', 'dark' ou 'auto' selon localStorage. applyTheme modifie la classe de <html> et localStorage. Il ne fait rien quand le thème du projet impose un mode.

getThemeIcon(theme)Copier le lien de la section

L'icône du thème système ne dépend pas de la préférence système : un ordinateur dit que l'appareil décide, sans laisser croire à un troisième rendu.

ThemeWatcherCopier le lien de la section

Composant sans rendu qui fait deux choses. FrazaProvider le monte déjà.

Il suit prefers-color-scheme quand aucune préférence n'est stockée, et que le thème offre les deux modes.

Il rejoue le script anti-flash quand celui-ci n'a pas tourné. Next.js rend côté client le document entier d'une page qui appelle notFound() : React insère alors le <script> de <ThemeStyle /> sans l'exécuter. Au montage, si data-fraza-modes est absent de <html>, ThemeWatcher applique la même logique que le script : il lit les modes sur la balise fraza-theme-init, pose data-fraza-modes, puis la classe dark selon le mode imposé, la préférence stockée ou le système. Il le fait avant le premier affichage, donc sans flash. Sur une page rendue par le serveur, l'attribut est déjà là et rien ne se passe.

THEME_INIT_SCRIPTCopier le lien de la section

Ancien script anti-flash, sans connaissance des modes du thème. Il reste exporté pour les projets qui n'ont pas encore adopté <ThemeStyle />, que fraza-doctor signale.

JetonsCopier le lien de la section

Les jetons sont déclarés dans core.css, sous le préfixe --fraza-*, et enregistrés dans Tailwind. Chacun produit les utilitaires habituels : bg-surface, text-fg-muted, border-line, bg-line-soft, bg-field, hover:bg-accent-hover, ring-ring/20, bg-danger/10.

Valeurs par défaut, en clair et en sombre :

Les pourcentages sont ceux de color-mix() avec la couleur pleine. Tous les jetons de couleur, line-soft, field et accent-hover compris, sont acceptés dans overrides.light et overrides.dark. C'est aussi le cas de danger-hover, de danger-solid et des neuf déclinaisons de statut : danger-soft, success-soft, warning-soft, danger-line, success-line, warning-line, danger-ink, success-ink et warning-ink. Les déclinaisons de l'info, de l'accent et de primary ne s'écrivent pas : elles suivent leur couleur.

overrides: {
  light: { danger: '#c81e1e', 'danger-ink': '#7f1414' }, // danger-soft et danger-line calculés
}

Les autres échelles de gris, stone, slate, zinc et gray, suivent la même structure : le fond de page un cran sous le survol, line-soft entre surface-muted et line, field blanc en clair.

font-sans et font-mono, les familles par défaut de Tailwind, pointent aussi sur le thème. Un texte rendu hors de la coquille, dans un menu, une fenêtre ou une notification en portail dans <body>, reste ainsi en IBM Plex. font-ibm-plex-sans et font-ibm-plex-mono restent disponibles pour les gabarits de projets existants. Ils suivent eux aussi l'option font.

core.css pose aussi trois règles de base. color-scheme suit le mode, pour que barres de défilement, calendriers et listes natives passent au sombre. Un :focus-visible par défaut trace l'anneau de 2 px en ring, décalé de 2 px, sur tout lien ou bouton sans recette de focus. La sélection de texte prend l'accent à 22 %.

NotesCopier le lien de la section

Les défauts vivent dans @layer base. Les valeurs de <ThemeStyle />, hors couche, les battent sans dépendre de l'ordre des feuilles dans <head>. Pour la même raison, une redéfinition de --fraza-* dans le CSS du projet l'emporte sur les défauts, mais pas forcément sur <ThemeStyle /> : pour changer la valeur d'un jeton, passer par overrides.

Le thème se lit au rendu, jamais au chargement d'un fichier. Le manifeste des modules lance leur register() avant qu'initializeFraza n'enregistre le thème. Une constante calculée au niveau racine d'un fichier garderait l'apparence par défaut.

Le thème sombre est une classe CSS, pas un état React partagé. La source de vérité est la classe dark sur <html>, posée par le script avant React, ou par ThemeWatcher quand le document est rendu côté client. useTheme la lit au montage plutôt que de l'imposer, ce qui évite un second flash à l'hydratation.

Pour les règles d'usage des jetons, voir Design system.