tailwind-palette-kit

Module de gestion des palettes de couleurs pour Tailwind CSS - Créez, personnalisez et appliquez des palettes de couleurs dynamiquement via CLI ou API programmatique.

Fonctionnalités principales

• Interface en ligne de commande (CLI) pour la gestion des palettes
• API programmatique complète pour l'intégration dans vos applications
• Génération automatique de nuances (50 → 950) à partir d'une couleur de base
• Plusieurs modes de génération : perception ou linéaire
• Persistance des palettes via adaptateurs (fichier JSON côté Node ou LocalStorage côté navigateur)
• Injection automatique dans la configuration Tailwind (no-op sécurisé dans le navigateur)
• Synchronisation en temps réel avec Tailwind v4
• Support des frameworks UI (React, Vue, etc.)
• Événements pour l'intégration en temps réel

Compatibilité Tailwind CSS v4 et PostCSS

Important : Pour Tailwind CSS v4+ et PostCSS 8+

• N’ajoutez jamais @tailwindcss/postcss dans votre package.json (ce package n’existe pas officiellement).
• Ne référencez pas explicitement tailwindcss comme plugin dans votre configuration PostCSS.
• Laissez Tailwind gérer la configuration PostCSS automatiquement (il suffit d’avoir tailwind.config.js et d’importer tailwindcss dans votre CSS).
• Si vous voyez un message d’erreur demandant d’installer @tailwindcss/postcss, vérifiez que vous utilisez bien la version stable de Tailwind v4 et que votre config PostCSS ne référence pas tailwindcss comme plugin.

Ce module ne modifie que le fichier tailwind.config.js et ne touche jamais à la configuration PostCSS.

Installation

npm install tailwind-palette-kit

Guide d'utilisation

Le module propose trois façons d'interagir avec les palettes de couleurs :

1. Interface en ligne de commande (CLI)

La CLI permet de gérer facilement vos palettes via le terminal :

# Exécuter la CLI sans installation globale
npx tailwind-palette create primary "#3B82F6" --type perception --position 500

# Mettre à jour une palette existante
npx tailwind-palette update primary --color "#2563EB" --type linear --position 400

# Renommer une palette
npx tailwind-palette rename primary main-blue

# Lister toutes les palettes
npx tailwind-palette list

# Supprimer une palette
npx tailwind-palette delete primary

# Voir l'aide
npx tailwind-palette --help

💡 Si vous préférez une utilisation globale, installez le package avec npm install -g tailwind-palette-kit puis utilisez directement la commande tailwind-palette dans votre terminal.

Options disponibles pour create/update :

• --position : Position de la couleur de base (50-950, défaut: 500)

2. API programmatique

Pour une intégration dans vos applications et la création d'interfaces utilisateur personnalisées :

import { paletteAPI, PaletteTypes } from 'tailwind-palette-kit';

// Création de palette
await paletteAPI.createPalette('primary', '#3B82F6', PaletteTypes.PERCEPTION, 500);

// Mise à jour
await paletteAPI.updatePalette('primary', {
  baseColor: '#2563EB',
  type: PaletteTypes.LINEAR,
  position: 400
});

// Renommage
await paletteAPI.renamePalette('primary', 'main-blue');

// Suppression
await paletteAPI.deletePalette('main-blue');

// Récupération des palettes
const allPalettes = paletteAPI.getAllPalettes();
const onePalette = paletteAPI.getPalette('primary');

// Prévisualisation sans sauvegarde
const previewColors = paletteAPI.previewPaletteColors('#3B82F6', PaletteTypes.PERCEPTION, 500);

// Écoute des changements
paletteAPI.on('palettesUpdated', (colors) => {
  console.log('Palettes mises à jour:', colors);
});

3. Utilisation avec Tailwind

Le module s'intègre automatiquement avec Tailwind CSS. Configuration minimale requise :

// tailwind.config.js
/** @type {import('tailwindcss').Config} */
export default {
  content: ['./index.html', './src/**/*.{js,ts,jsx,tsx}'],
  theme: {
    extend: {
      colors: {} // Les palettes seront injectées ici automatiquement
    }
  },
  plugins: []
}

Les palettes sont automatiquement synchronisées avec Tailwind à chaque modification :

// Exemple d'utilisation dans votre code
<div class="bg-primary-500 text-primary-50">
  Le texte utilise la couleur la plus claire de la palette primary
  sur un fond de la couleur de base de la palette primary
</div>

4. Persistance et stockage

Le module s'appuie sur des adaptateurs de stockage configurables :

• Node.js / CLI : FileSystemStorage persiste les palettes dans src/data/palettes.json (format JSON ci-dessous).
• Navigateur : LocalStorageAdapter sauvegarde les palettes dans window.localStorage.
• Adaptateur personnalisé : implémentez load() et save(payload) puis fournissez-le à paletteAPI.useStorage().

Format JSON attendu (utilisé par défaut côté Node) :

{
  "version": "1.0.0",
  "palettes": {
    "primary": {
      "baseColor": "#3B82F6",
      "type": "perception",
      "position": 500,
      "colors": {
        "50": "#EFF6FF",
        "100": "#DBEAFE",
        "950": "#172554"
      }
    }
  }
}

import { paletteAPI, LocalStorageAdapter } from 'tailwind-palette-kit';

// Exemple navigateur : persistance automatique dans LocalStorage
paletteAPI.useStorage(new LocalStorageAdapter());

// Exemple Node : injecter une intégration Tailwind personnalisée si nécessaire
paletteAPI.setTailwindIntegration(async (colors) => {
  // Ecrire les couleurs ailleurs (API REST, BDD, etc.)
});

5. Événements disponibles

L'API émet plusieurs événements que vous pouvez écouter :

// Écouter les mises à jour de palettes
paletteAPI.on('palettesUpdated', (colors) => {
  console.log('Nouvelles couleurs:', colors);
});

// Les événements sont émis après chaque :
// - Création de palette
// - Mise à jour de palette
// - Renommage de palette
// - Suppression de palette

6. Types de palettes

Deux algorithmes de génération sont disponibles :

• perception : Génère des nuances basées sur la perception humaine
• linear : Génère des nuances de manière linéaire

La position (50-950) détermine où la couleur de base sera placée dans la palette.

Exemple Vite + Tailwind CSS v4 (ESM)

Un projet de démonstration prêt à l'emploi est disponible dans examples/vite-tailwind-v4. Il valide :

• l'import ESM direct depuis un projet Vite 5 ;
• la compatibilité avec [email protected] et le plugin officiel @tailwindcss/vite ;
• la persistance des palettes dans localStorage avec mise à jour d'une interface graphique minimale.

Pour lancer le build de vérification :

cd examples/vite-tailwind-v4
npm install
npm run build

Astuce : exécutez npm run test:browser depuis la racine du repo pour lancer ces étapes automatiquement.

Le bundle obtenu est dépourvu de dépendances Node (fs, path, etc.), ce qui garantit la compatibilité navigateur sans polyfill.

7. Exemples d'utilisation avancée

Création d'une interface utilisateur personnalisée

import { paletteAPI, PaletteTypes } from 'tailwind-palette-kit';

class ColorPaletteManager {
  constructor() {
    // Écouter les changements
    paletteAPI.on('palettesUpdated', this.handlePalettesUpdate.bind(this));
    
    // Charger les palettes initiales
    this.palettes = paletteAPI.getAllPalettes();
  }

  handlePalettesUpdate(colors) {
    // Mettre à jour l'interface utilisateur
    this.updateUI(colors);
  }

  async createNewPalette(name, color) {
    try {
      // Prévisualiser d'abord
      const preview = paletteAPI.previewPaletteColors(color);
      
      // Si l'aperçu est satisfaisant, créer la palette
      await paletteAPI.createPalette(name, color);
      
      this.showSuccess(`Palette ${name} créée !`);
    } catch (error) {
      this.showError(error.message);
    }
  }
}

Intégration avec un framework UI

// React exemple
import { useEffect, useState } from 'react';
import { paletteAPI } from 'tailwind-palette-kit';

function PaletteEditor({ paletteName }) {
  const [palette, setPalette] = useState(null);
  const [preview, setPreview] = useState(null);

  useEffect(() => {
    // Charger la palette
    setPalette(paletteAPI.getPalette(paletteName));

    // Écouter les mises à jour
    paletteAPI.on('palettesUpdated', (colors) => {
      setPalette(colors[paletteName]);
    });
  }, [paletteName]);

  const handleColorChange = (color) => {
    // Prévisualisation en direct
    setPreview(paletteAPI.previewPaletteColors(color));
  };

  const handleSubmit = async (color) => {
    await paletteAPI.updatePalette(paletteName, { baseColor: color });
  };

  return (
    <div>
      <ColorPicker onChange={handleColorChange} onSubmit={handleSubmit} />
      <PalettePreview colors={preview || palette?.colors} />
    </div>
  );
}

Utilisation avec un système de thèmes

import { paletteAPI } from 'tailwind-palette-kit';

class ThemeManager {
  constructor() {
    this.themes = {
      light: {
        primary: '#3B82F6',
        secondary: '#10B981'
      },
      dark: {
        primary: '#60A5FA',
        secondary: '#34D399'
      }
    };
  }

  async switchTheme(themeName) {
    const theme = this.themes[themeName];
    
    // Mettre à jour toutes les palettes pour le thème
    await Promise.all([
      paletteAPI.updatePalette('primary', { baseColor: theme.primary }),
      paletteAPI.updatePalette('secondary', { baseColor: theme.secondary })
    ]);
  }
}

Architecture du module

Le module est organisé en plusieurs composants clés :

Core

• PaletteManager.js : Gestion des palettes et persistance
• PaletteAPI.js : API publique avec support des événements
• tailwindIntegration.js : Intégration avec Tailwind CSS

CLI

• cli/index.js : Interface en ligne de commande

Utils

• colorGenerator.js : Algorithmes de génération des couleurs
• paletteManager.js : Utilitaires de manipulation des palettes

Data

• palettes.json : Stockage persistant des palettes

Contribution

Les contributions sont les bienvenues ! N'hésitez pas à :

• Ouvrir des issues pour les bugs ou suggestions
• Proposer des pull requests
• Améliorer la documentation

Licence

MIT - Voir le fichier LICENSE