Semantic Colors

Installation

Tailwind 4

Importer le CSS dans le fichier CSS Tailwind principal :

@import '../components/tailwind/semantic-colors/style.css';

Tailwind 3

Importer SemanticColors depuis le fichier components/tailwind/semantic-colors/tailwind3/index.ts dans la configuration Tailwind :

import { SemanticColors } from './src/components/tailwind/semantic-colors';
 
const tailwindConfig = {
   // configuration Tailwind
   theme: {
      extend: {
         colors: semanticColors,
      },
   },
};
 
export default tailwindConfig;

Puis importer le CSS dans le fichier CSS Tailwind principal :

@import '../components/tailwind/semantic-colors/tailwind3/style.css';

Ou copier coller le contenu du fichier style.css dans le fichier CSS Tailwind principal.

Personnalisation

Ajouter / modifier les variables CSS selon vos besoins.

Conventions

En dehors des shades, les tokens sémantiques utilisent une convention simple de couleurs d'arrière-plan et de premier plan. La variable background définit la couleur de fond du composant, tandis que la variable foreground détermine la couleur du texte.

Chaque token est une variable de background excepté pour les tokens avec le suffixe -foreground qui sont des variables de couleur de texte.

Les tokens sémantique

Token de branding

Les tokens de branding sont utilisés pour les éléments clés de l'interface utilisateur qui représentent la marque, tels que les boutons principaux, les liens et les accents. Ils sont conçus pour attirer l'attention et guider les utilisateurs vers des actions importantes.

Tokens de statut

Les tokens de statut sont utilisés pour indiquer des états spécifiques dans l'interface utilisateur, tels que le succès, l'information, l'avertissement et le danger. Idéal pour les alertes, les notifications et les messages d'erreur.

Les tokens de shade

Neutral : la référence tonale

Décrit une échelle de gris (ou quasi-gris) servant de base au contraste, aux séparateurs, aux fonds génériques. Ce shade sert de référence tonale, il n'est pas destiné à être utilisé directement mais plutot consommé par les d'autres tokens (surface, border, muted, outline, etc.), et ne varie pas en dark mode.

Surface

Décrit les différentes couches de surface dans l'interface utilisateur, allant des fonds légers aux fonds plus sombres. Ces tokens sont utilisés pour créer de la profondeur et de la hiérarchie visuelle. Le shade est inversé en dark mode pour s'adapter aux différents contextes d'utilisation.

Exemple d'utilisation des shades surface pour créer des cartes imbriquées avec différents niveaux de profondeur :

Les tokens d'UI

Background et Foreground et headings

Accent et Accent Foreground

Border, Ring et Input

Muted et Muted Foreground

Règles globales

Par défaut, certaines règles CSS sont appliquées globalement avec les jetons sémantiques dans l'interface utilisateur.

Par exemple, les bordures et les contours ont des couleurs définies sur border et ring. Ainsi, il n'est pas nécessaire de spécifier ces couleurs manuellement pour chaque élément : border sera coloré par défaut avec border-border et les contours avec outline-ring/50.

De même, le fond et la couleur du texte du body sont définis avec les jetons background et foreground.

@layer base {
  * {
    @apply border-border outline-ring/50 accent-accent;
  }
  body {
    @apply bg-background text-foreground;
  }
}

Tailwind-Merge

Tailwind-Merge est utilisé pour fusionner les classes Tailwind et gérer les conflits de classes. Par exemple, si vous appliquez à un élément à la fois text-sm et text-xl, tailwind-merge garantira que seule la dernière classe appliquée est prise en compte.

Cependant, il est important de noter que tailwind-merge ne gère pas les conflits entre les classes utilitaires et les classes personnalisées définies dans le fichier CSS des tokens sémantiques.

Exemple : Si les classes suivantes sont présentes text-xl text-danger, Tailwind-Merge ne sait pas que danger est un token de couleur et peut le considérer lors de l'application d'une taille de texte, supprimant alors text-xl.

Par conséquent, il est nécessaire de renseigner ces classes et leur contexte d'application pour que la fusion se fasse correctement. Cela implique de modifier la fonction cn() pour étendre sa configuration.

Exemple de configuration étendue de Tailwind-Merge

import { type ClassValue, clsx } from 'clsx';
import { extendTailwindMerge } from 'tailwind-merge';
 
import { customTwMergeConfig } from './twMergeConfig'; // La configuration étendue
 
export const extendedTwMerge = extendTailwindMerge(customTwMergeConfig);
 
export function cn(...inputs: ClassValue[]) {
  return extendedTwMerge(clsx(inputs));
}

import tailwindConfig from '../../tailwind.config'; // Récupérer la configuration Tailwind si disponible
import { extractAllColorKeys } from './tailwind';
 
export const customTailwind = {
  ...tailwindConfig.theme.extend,
};
 
// Fonction pour extraire toutes les clés de couleur, y compris les variantes
export const extractAllColorKeys = (colors: Record<string, unknown>): string[] => {
  const colorKeys: string[] = [];
 
  for (const [colorName, colorValue] of Object.entries(colors)) {
    if (typeof colorValue === 'object' && colorValue !== null && !Array.isArray(colorValue)) {
      // Si c'est un objet (ex: surface: { 50: '...', 100: '...', ... })
      for (const variant of Object.keys(colorValue)) {
        if (variant === 'DEFAULT') {
          // Pour DEFAULT, on utilise juste le nom de la couleur (ex: 'primary' au lieu de 'primary-DEFAULT')
          colorKeys.push(colorName);
        } else {
          // Pour les autres variantes (50, 100, foreground, etc.)
          colorKeys.push(`${colorName}-${variant}`);
        }
      }
    } else {
      // Si c'est une couleur simple (ex: danger: '...', primary: '...')
      colorKeys.push(colorName);
    }
  }
 
  return colorKeys;
};
 
const customColors = extractAllColorKeys(customTailwind.colors || {});
 
export const customTwMergeConfig = {
  extend: {
    classGroups: {
      // Étend les groupes de couleurs existants avec les tokens personnalisées
      'text-color': [{ text: customColors }],
      'bg-color': [{ bg: customColors }],
      'border-color': [{ border: customColors }],
      'decoration-color': [{ decoration: customColors }],
      'outline-color': [{ outline: customColors }],
      'ring-color': [{ ring: customColors }],
      'ring-offset-color': [{ 'ring-offset': customColors }],
      'shadow-color': [{ shadow: customColors }],
      'accent-color': [{ accent: customColors }],
      'caret-color': [{ caret: customColors }],
      'divide-color': [{ divide: customColors }],
      'from-color': [{ from: customColors }],
      'via-color': [{ via: customColors }],
      'to-color': [{ to: customColors }],
    },
  },
};