wasely/ui-max

UI Max

Prioriser la convivialité du produit plutôt que les effets décoratifs. Choisir le système cohérent le plus simple qui satisfait le besoin ; ne pas accumuler de bibliothèques de composants.

Commencer par le produit

Avant de modifier le code :

1. Inspecter le framework, le routeur, le système CSS, la bibliothèque de composants, les bibliothèques d'icônes et d'animations, la stack de formulaires, les design tokens, le mode sombre et les motifs établis.
2. Définir l'objectif de l'utilisateur, le flux de travail principal, la hiérarchie de l'information, les actions primaires et secondaires, les états requis, les surfaces responsives et le comportement clavier.
3. Réutiliser dans cet ordre : les composants locaux, les primitives de design-système existantes, shadcn/ui, Radix UI, 21st.dev, une bibliothèque d'extension spécialisée, une implémentation personnalisée.
4. Conserver un système UI stable existant. Ne jamais introduire un système complet concurrent pour un seul composant attrayant.

Choisir une base

Pour les nouvelles interfaces produit React, par défaut :

React + TypeScript + Tailwind CSS
shadcn/ui -> Primitives Radix UI
Icônes Lucide
Motion pour React uniquement si utile
React Hook Form + Zod pour les formulaires substantiels
TanStack Table uniquement pour les comportements avancés de tableau

Ne pas imposer cette stack dans des projets disposant d'un système établi ou dans des projets Vue/Svelte. Utiliser les bibliothèques natives de l'écosystème.

Classifier la surface avant de sélectionner des ajouts :

• Interface produit de base : shadcn/ui + Radix UI + Tailwind CSS.
• Interface produit IA : ajouter Cult UI uniquement pour les motifs réels de workflows IA ; utiliser Motion Primitives pour les transitions retenues.
• Page marketing : utiliser 21st.dev pour la structure, Magic UI de manière sélective, et Aceternity uniquement pour les sections à fort impact réel.
• Application dense en données : ajouter TanStack Table lorsque le tri, le filtrage, la pagination, la sélection, la visibilité, la virtualisation ou les modèles de données complexes le justifient.
• Micro-interaction : utiliser Motion Primitives ou Motion. Utiliser UIverse uniquement après une revue d'accessibilité et de maintenabilité.

Lire references/component-selection.md lors du choix, de l'installation ou de l'approvisionnement de bibliothèques/composants, de la comparaison d'alternatives ou de la recherche de motifs visuels.

Implémenter de manière cohérente

Normaliser chaque composant réutilisé ou copié selon :

• les tokens de couleur sémantiques du projet
• les échelles de typographie, d'espacement, de rayon et d'ombre
• la famille d'icônes
• les conventions d'accessibilité
• le comportement responsive
• les thèmes clair et sombre

Utiliser des tokens sémantiques plutôt que des valeurs codées en dur éparpillées. Garder les contrôles associés proches ; séparer les sections non liées ; éviter les cartes imbriquées injustifiées ; utiliser des listes/tableaux pour la comparaison et des cartes pour des éléments individuellement actionnables et hétérogènes. Garder les actions primaires évidentes et les actions destructrices éloignées des actions courantes.

Utiliser une police d'interface et une famille d'icônes, sauf si l'identité de marque exige autrement. Utiliser le mouvement uniquement pour communiquer l'état, la hiérarchie, la continuité, la cause/effet, la progression ou le focus. Respecter prefers-reduced-motion.

Lire references/design-standards.md avant une implémentation visuelle substantielle, un travail responsive, une conception d'états, des formulaires, des tableaux ou un travail d'accessibilité.

Couvrir les états réels

Pour l'UI asynchrone ou pilotée par les données, considérer :

• le chargement initial et l'actualisation en arrière-plan
• les résultats vides et les correspondances de recherche nulles
• les états de succès, d'avertissement, d'erreur et d'échec partiel
• les états désactivés et hors ligne
• les permissions ou intégrations manquantes
• les données obsolètes

Préférer les squelettes lorsque la structure est connue. Faire en sorte que les erreurs disent ce qui a échoué, pourquoi si connu, si le travail est préservé et ce qui le résout. Ne jamais utiliser de données fictives dénuées de sens, d'analyses factices, d'activité d'agent fabriquée ou de contrôles non fonctionnels dans un produit fini.

Nettoyer l'UI existante

Auditer la duplication, l'espacement, les couleurs, la typographie, les variantes, les icônes, la disposition imbriquée, les utilitaires répétés, la réactivité, l'accessibilité, le code/les dépendances inutilisés, la surcharge d'animations et les états manquants.

Consolider les primitives répétées ou porteuses de comportement telles que les boutons, les entrées, les badges de statut, les boîtes de dialogue, les menus, les onglets, les en-têtes de page, les états vides/erreur/chargement, les éléments de barre latérale et les lignes de projet. Ne pas abstraire du balisage ponctuel sans bénéfice en termes de cohérence, logique, réutilisation ou test.

Tokeniser les valeurs répétées. Supprimer les wrappers inutiles, les cartes imbriquées, les séparateurs décoratifs, les étiquettes répétées, les actions/statuts redondants, les descriptions excessives et les mouvements injustifiés.

Valider le rendu produit

Vérifier :

• HTML sémantique, noms accessibles, étiquettes, ordre de tabulation logique, fonctionnement au clavier, focus des boîtes de dialogue, focus visible et contraste
• chargement, états vides, désactivés, erreur, succès, texte long et confirmation destructive
• mises en page étroites et larges sans coupure, tableaux illisibles, décalage de mise en page ou débordement horizontal
• comportement en mouvement réduit, thèmes clair/sombre et navigation responsive
• formateur, lint, TypeScript, tests, build de production et sortie console

Tester à 320, 375, 768, 1024, 1280 et 1440 px le cas échéant. Pour les extensions de navigateur, tester également les largeurs de popup autour de 320–420 px et les panneaux latéraux autour de 320–600 px.

Inspecter l'UI réellement rendue aux largeurs étroites et larges avant de déclarer la tâche terminée. Utiliser une boucle d'écran ou le workflow de validation visuelle existant du projet ; confirmer les surfaces spécifiques à la plateforme sur la cible réelle.

Rapporter le travail UI

Lorsqu'on vous demande de concevoir ou de reconstruire une page, fournir des sections concises pour :

1. Interprétation du produit : objectif, flux de travail principal, information clé, action principale.
2. Plan des composants : structure, composants réutilisables, base, ajouts spécialisés, comportement responsive, états importants.
3. Implémentation : code fonctionnel dans la stack existante.
4. Validation : accessibilité, réactivité, états, comportement clavier, cohérence des design tokens et revue visuelle du rendu.

Ne pas retourner un catalogue de bibliothèques sauf si l'utilisateur demande des options.