Personnalisation du thème

Tous les jetons de conception de @lh-ui/react proviennent de @lh-ui/share/theme ; la bibliothèque ne détient aucune copie des jetons. Personnaliser le thème, c'est surcharger ces propriétés personnalisées CSS.

Hiérarchie des jetons

Par priorité croissante, du plus bas au plus élevé :

1. theme.css — jetons de base publiés par @lh-ui/share (--lh-primary-color, etc.)
2. theme-dark.css — variables sombres (mutuellement exclusif avec theme.css, un des deux au choix)
3. themeVars de LhConfigProvider — variables en cascade attachées à l'élément enveloppant
4. Prop themeVars d'un composant — attachée à la racine du composant, elle surcharge tout niveau supérieur

Personnalisation via ConfigProvider

La méthode la plus recommandée : passer themeVars à la racine de l'application, avec des noms de clés sans le préfixe --lh- (ajouté automatiquement en interne) :

import { LhConfigProvider } from '@lh-ui/react'

export default function App() {
  return (
    <LhConfigProvider
      themeVars={{
        'primary-color': '#722ed1',
        'bg-color': '#faf9f7',
        'border-radius-base': '6px',
      }}
    >
      <YourApp />
    </LhConfigProvider>
  )
}

Les variables sont rendues sur l'élément enveloppant sous la forme style="--lh-primary-color: #722ed1; ...", et se propagent en cascade vers le bas.

Jetons disponibles

Clé	Description
primary-color	Couleur principale
gold-color / vermilion-color / jade-color	Couleurs propres au style chinois (doré, 朱砂 (cinabre), jade)
bg-color / text-color / border-color	Couleurs neutres
bg-pattern	URL du motif de fond (par exemple var(--lh-pattern-willow))
bg-pattern-opacity / bg-pattern-color	Opacité et couleur du motif
decoration-color	Couleur d'ornement

Personnalisation d'un composant unique

Tout composant prenant en charge le thème accepte directement themeVars, avec un effet limité au composant lui-même :

<LhButton themeVars={{ 'primary-color': '#13c2c2' }}>Bouton cyan</LhButton>

Il est également possible de configurer plusieurs composants par nom via componentTheme (les noms de clés sont communs aux autres bibliothèques de la famille) :

<LhConfigProvider
  componentTheme={{
    button: { 'primary-color': '#722ed1' },
    input: { 'border-color': '#d9d9d9' },
  }}
>
  <YourApp />
</LhConfigProvider>

Priorité : props du composant lui-même > componentTheme[nom du composant] > themeVars globale.

Motif de fond

Le motif de fond de style chinois est désactivé par défaut. Il s'active via la liste blanche patternComponents : seuls les composants de la liste blanche appliquent le motif global :

<LhConfigProvider
  themeVars={{ 'bg-pattern': 'var(--lh-pattern-willow)' }}
  patternComponents={['dialog', 'card']}
>
  <YourApp />
</LhConfigProvider>

Le motif passé via la prop bgPattern du composant lui-même n'est pas soumis à la liste blanche.

Mise en page rapide avec sx

Certains composants prennent en charge la prop sx, qui exprime les styles de mise en page courants sous forme d'objet (sémantique identique au sx d'emotion / MUI) :

<LhButton sx={{ marginTop: 2, width: '100%' }} block>
  Bouton pleine largeur
</LhButton>

Bascule à l'exécution

Le changement de thème consiste à modifier des variables CSS : il peut donc être entièrement dynamique :

import { useState } from 'react'
import { LhConfigProvider } from '@lh-ui/react'

function App() {
  const [primary, setPrimary] = useState('#1677ff')
  return (
    <LhConfigProvider themeVars={{ 'primary-color': primary }}>
      <input type="color" onChange={(e) => setPrimary(e.target.value)} />
      <YourApp />
    </LhConfigProvider>
  )
}

Assertion de type des variables CSS

Dans le code source, style="{ { '--lh-primary-color': x } } produit une erreur TypeScript (les clés de propriétés personnalisées ne figurent pas dans CSSProperties). Cette bibliothèque traite uniformément la conversion et l'assertion des noms de clés via l'utilitaire cssVarsStyle(), déjà encapsulé dans les composants : l'utilisateur n'a pas à s'en soucier.