Theming

Objectif

La personnalisation doit fonctionner à deux niveaux : configuration rapide avec quelques couleurs de marque, ou remplacement précis de chaque token.

Résolution d'un thème

Niveaux de tokens

1. Primitifs : valeurs brutes comme les palettes, espacements et rayons.
2. Sémantiques : rôle d'une valeur, par exemple background ou danger.
3. Composants : décisions propres à Button, Input ou Modal.

Un composant doit utiliser --sia-primary, jamais une couleur brute comme --sia-blue-600.

Mode simple prévu

const theme = createTheme({
  colors: {
    primary: "#2563eb",
    secondary: "#7c3aed",
    accent: "#f59e0b",
    neutral: "#64748b"
  }
});

La palette et les états hover, active, subtle, border et foreground seront générés automatiquement. La génération perceptuelle en OKLCH est prévue, mais n'est pas encore implémentée.

Mode avancé prévu

const theme = createTheme({
  semanticTokens: {
    background: "#fafafa",
    primary: "#0057d9"
  },
  components: {
    button: { radius: "9999px" }
  }
});

État actuel

@sia-ui/tokens fournit actuellement :

• primitives pour les valeurs brutes ;
• lightTheme et darkTheme pour les rôles sémantiques ;
• toCssVariables pour générer les variables CSS sans répétition ;
• SiaProvider pour injecter un thème React.

<SiaProvider colorMode="dark" theme={{ primary: "#7c3aed" }}>
  <App />
</SiaProvider>

Le texte posé sur un ton

Chaque ton plein a son texte : --sia-primary-foreground, et désormais --sia-secondary-, --sia-info-, --sia-success-, --sia-warning- et --sia-danger-foreground. Une pastille solid, un bouton danger, une étape terminée et les classes .sia-tone--* les lisent ; plus aucun blanc n'est écrit en dur.

Leur valeur est calculée, pas choisie : readableOn(fond) rend le blanc tant qu'il atteint un contraste de 3:1 — le seuil WCAG des composants d'interface et des grands textes —, l'encre du thème sinon. Un rouge de suppression garde son texte blanc ; l'ambre, le vert et le bleu ciel du mode sombre, trop clairs pour du blanc, prennent l'encre. Une couleur de marque qui change garde un texte lisible sans qu'on y pense, et readableOn sert aussi aux tons qu'un projet ajoute.

Ton	Mode clair	Mode sombre
primary, secondary, danger	blanc	encre
info, success, warning	encre	encre

Des noms de variables uniques

toCssVariables et themeVariables écrivent les mêmes noms, en kebab-case : primaryForeground devient --sia-primary-foreground. toCssVariables écrivait --sia-primaryForeground, que les composants ne lisaient pas — un thème passé à SiaThemeProvider restait sans effet sur ces rôles. Les deux partagent désormais cssVarName.

Priorité des valeurs

valeur par défaut
< thème clair ou sombre
< thème utilisateur
< configuration du composant
< propriété locale

La validation automatique des contrastes WCAG et les scopes de thème locaux sont également prévus.