template-neumorphism/README.md

🛡️ AEGIS Boilerplate - Neumorphic UI (Vite + React 19 + Tailwind v4)

Un point de départ ultra-performant et esthétique pour la création d'applications web modernes et de tableaux de bord B2B complexes. Ce template intègre un Design System Neumorphique (Soft UI) complet, taillé sur mesure pour des interfaces de cybersécurité haut de gamme.

✨ Fonctionnalités Principales

• ⚡️ Vite & React 19 : Compilation instantanée, HMR ultra-rapide et prise en charge des dernières fonctionnalités React sans forwardRef.
• 🎨 Tailwind CSS v4 : Configuration moderne sans fichier tailwind.config.js, stylisation utilitaire et mode sombre manuel.
• 🎛️ Design System Neumorphique : Kit UI complet (Boutons, Cartes, Inputs, Sidebar, Toggles) basé sur l'extrusion et le creusage de la matière.
• 🌓 Thème Sombre / Clair Synchronisé : Hook useTheme gérant les préférences système et la persistance via localStorage avec des transitions fluides à 300ms.
• 🧩 Architecture Clean : Organisation modulaire, composants agnostiques, et alias absolus (@/).
• 🗄️ Backend Ready : Structure préparée pour l'intégration de PocketBase (Auth, DB, Storage).

---

🛠️ Stack Technique

• Framework : React 19
• Bundler : Vite
• Styling : Tailwind CSS v4
• Routing : React Router v6
• Icônes : Lucide React
• Utilitaires UI : clsx & tailwind-merge (Fonction cn())

---

🚀 Démarrage Rapide

1. Prérequis

Assurez-vous d'avoir Node.js (version 18+) et pnpm installés sur votre machine.

2. Installation

Clonez ce template ou copiez les fichiers, puis installez les dépendances avec pnpm :

pnpm install

3. Lancer le serveur de développement

pnpm dev

L'application sera accessible sur http://localhost:5173. Visitez http://localhost:5173/ui pour consulter la vitrine interactive des composants (UI Showcase).

---

📐 Règle d'Or du Neumorphism

Pour que l'illusion d'optique Neumorphique (3D souple) fonctionne, les composants et le fond de la page DOIVENT avoir exactement la même couleur.

Ce template utilise deux couleurs maîtresses strictes codées en dur dans les composants :

• ☀️ Mode Light : #e8e8e8
• 🌙 Mode Dark : #1e293b

⚠️ Le conteneur racine de toutes vos pages (ex: dans App.tsx ou votre Layout) doit impérativement porter ces classes :

<div className="min-h-screen bg-[#e8e8e8] dark:bg-[#1e293b] text-slate-800 dark:text-slate-100 transition-all duration-300 ease-in-out">
  {/* Vos composants ici */}
</div>

(Note : La classe transition-all duration-300 ease-in-out est indispensable pour que les ombres (box-shadow) s'animent en parfaite synchronisation avec le fond).

---

📂 Architecture des Dossiers

src/
├── components/
│   └── ui/               # UI Kit Neumorphique (Button, Card, Input, Sidebar...)
├── features/             # Logique métier spécifique (ex: auth, serveurs, metrics)
├── hooks/                # Hooks personnalisés (ex: useTheme.ts)
├── pages/                # Écrans de l'application (UiShowcase, Dashboard...)
├── services/             # Appels API, configuration PocketBase
├── utils/                # Fonctions utilitaires (utils.ts avec la fonction cn)
├── App.tsx               # Point d'entrée et Routeur (react-router-dom)
├── index.css             # Styles globaux et configuration Tailwind v4 (@theme)
└── main.tsx              # Rendu React racine

---

🎨 Utilisation du UI Kit

Tous les composants de base sont situés dans src/components/ui/ et utilisent la fonction cn() pour fusionner intelligemment les classes Tailwind.

Bouton (Extrude / Creusé au clic)

import { Button } from "@/components/ui/Button";

<Button variant="primary" onClick={() => alert('Action!')}>
  Sauvegarder
</Button>

Champ de saisie (Inset / Creusé)

import { Input } from "@/components/ui/Input";

<Input 
  label="Adresse Email" 
  type="email" 
  placeholder="contact@gise.be" 
/>

Carte (Plateau surélevé)

import { Card } from "@/components/ui/Card";

<Card>
  <h3 className="font-bold">Informations Serveur</h3>
  <p>Node-01 est opérationnel.</p>
</Card>

---

🔒 Variables d'Environnement

Créez un fichier .env.local à la racine du projet pour stocker vos clés secrètes. Toutes les variables exposées au Frontend React doivent commencer par VITE_.

# .env.local (ignoré par Git)
VITE_PB_URL=[http://127.0.0.1:8090](http://127.0.0.1:8090)
VITE_WEB3FORMS_KEY=votre_cle_api_secrete

📜 Scripts PNPM Disponibles

• pnpm dev : Lance le serveur de développement Vite.
• pnpm build : Compile le projet avec TypeScript et génère les fichiers de production dans dist/.
• pnpm preview : Lance un serveur local pour tester la version de production compilée.
• pnpm add <package> : Pour installer une nouvelle dépendance (équivalent de npm install).
• pnpm add -D <package> : Pour installer une dépendance de développement (équivalent de npm install -D).

---

Conçu avec rigueur par l'équipe GISE pour le projet AEGIS.