giuseppe-trisciuoglio/tailwind-design-system

Que fait tailwind-design-system ?

Compétence pour créer et gérer un Design System avec Tailwind CSS et shadcn/ui. À utiliser pour définir des jetons de design, configurer un thème avec des variables CSS, construire une bibliothèque de composants UI cohérente, initialiser une configuration de design system ou encapsuler des composants shadcn/ui en primitives de design system.

Vue d'ensemble

Cette compétence aide les développeurs à mettre en place et gérer un Design System robuste en utilisant Tailwind CSS et shadcn/ui. Elle automatise les tâches répétitives liées à la configuration des tokens, du thème et des composants.

Fonctionnalités principales

• Définition des jetons de design (couleurs, typographie, espacements, etc.)
• Configuration du thème avec variables CSS
• Création d'une bibliothèque de composants UI cohérente
• Initialisation de la configuration du design system
• Encapsulation des composants shadcn/ui en primitives réutilisables

Prérequis

• Node.js version 18 ou ultérieure
• Un projet utilisant Tailwind CSS (version 3 ou ultérieure)
• shadcn/ui installé et configuré
• React et TypeScript

Installation

npm install -g @giuseppe-trisciuoglio/tailwind-design-system

Ou utilisez directement via npx :

npx @giuseppe-trisciuoglio/tailwind-design-system init

Utilisation

Démarrer un nouveau projet

ds init

Cette commande crée la structure de base du design system :

• design-tokens/ – Dossier contenant les jetons de design
• theme/ – Configuration du thème avec variables CSS
• components/ – Composants UI de base
• tailwind.config.js – Fichier de configuration Tailwind étendu

Définir des jetons de design

Créez un fichier design-tokens/colors.js :

module.exports = {
  primary: {
    50: '#f0fdf4',
    100: '#dcfce7',
    // ... autres nuances
  },
  secondary: {
    50: '#fef2f2',
    100: '#fee2e2',
    // ... autres nuances
  },
}

Configurer le thème

Générez les variables CSS dans theme/theme.css en exécutant :

ds generate-theme

Cela produit un fichier CSS comme suit :

:root {
  --color-primary-50: #f0fdf4;
  --color-primary-100: #dcfce7;
  /* ... */
  --font-sans: 'Inter', sans-serif;
  --spacing-unit: 4px;
}

Créer des composants UI

Exécutez la commande suivante pour créer un composant Button :

ds add-component button

Cela génère un fichier components/Button.tsx avec du code prêt à l'emploi :

import * as React from 'react';
import { cva, type VariantProps } from 'class-variance-authority';
import { cn } from '@/lib/utils';

const buttonVariants = cva(
  'inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50',
  {
    variants: {
      variant: {
        default: 'bg-primary text-primary-foreground shadow hover:bg-primary/90',
        destructive: 'bg-destructive text-destructive-foreground shadow-sm hover:bg-destructive/90',
        outline: 'border border-input bg-background shadow-sm hover:bg-accent hover:text-accent-foreground',
        secondary: 'bg-secondary text-secondary-foreground shadow-sm hover:bg-secondary/80',
        ghost: 'hover:bg-accent hover:text-accent-foreground',
        link: 'text-primary underline-offset-4 hover:underline',
      },
      size: {
        default: 'h-9 px-4 py-2',
        sm: 'h-8 rounded-md px-3 text-xs',
        lg: 'h-10 rounded-md px-8',
        icon: 'h-9 w-9',
      },
    },
    defaultVariants: {
      variant: 'default',
      size: 'default',
    },
  }
);

export interface ButtonProps
  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
    VariantProps<typeof buttonVariants> {}

const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
  ({ className, variant, size, ...props }, ref) => {
    return (
      <button
        className={cn(buttonVariants({ variant, size, className }))}
        ref={ref}
        {...props}
      />
    );
  }
);
Button.displayName = 'Button';

export { Button, buttonVariants };

Encapsuler des composants shadcn/ui

Encapsulez un composant shadcn/ui en primitive du design system :

ds wrap shadcn-button --as Button

Cela crée un wrapper dans components/primitives/Button.tsx qui utilise le composant shadcn/ui mais permet d'ajouter des styles ou comportements personnalisés.

Configuration globale

Créez un fichier design-system.config.js à la racine du projet :

module.exports = {
  tokensPath: './design-tokens',
  themePath: './theme',
  componentsPath: './components',
  cssVariables: true,
  shadcn: {
    enabled: true,
    stylesPath: './styles/globals.css',
  },
  plugins: [],
};

Commandes

Commande	Description
ds init	Initialise la structure du design system
ds generate-theme	Génère les variables CSS à partir des tokens
ds add-component <name>	Ajoute un nouveau composant UI
ds wrap <component>	Encapsule un composant existant en primitive
ds list	Liste tous les composants du design system
ds build	Compile le design system dans /dist

Exemples d'utilisation

1. Nouveau projet : ds init crée toute la structure nécessaire.
2. Ajout d'un bouton : ds add-component button génère un composant prêt à l'emploi.
3. Mise à jour du thème : modifiez les tokens dans design-tokens/, puis exécutez ds generate-theme.
4. Wrapper shadcn : ds wrap shadcn-card --as Card crée une primitive réutilisable.

Bonnes pratiques

• Gardez vos jetons de design séparés de la logique métier.
• Utilisez les variables CSS pour un theming dynamique.
• Testez chaque composant dans isolation avant de l'intégrer.
• Documentez les props et les variants de chaque composant.

Dépannage

Si vous rencontrez des problèmes :

• Assurez-vous que Node.js >= 18 est installé (node --version).
• Vérifiez que votre fichier tailwind.config.js inclut bien le chemin vers theme/theme.css.
• Si les composants shadcn/ui ne s'affichent pas correctement, vérifiez que styles/globals.css importe bien @tailwind base, @tailwind components, et @tailwind utilities.
• Consultez les issues GitHub pour plus d'aide.

Ressources supplémentaires

• Documentation Tailwind CSS
• Documentation shadcn/ui
• Référence des jetons de design

Contribution

Les contributions sont les bienvenues ! Veuillez soumettre des pull requests ou signaler des problèmes sur le dépôt GitHub.

Licence

MIT