story-research-zapwall/features/ux-improvements.md

# Améliorations UX - Documentation

**Auteur** : Équipe 4NK
**Date** : 2025-01-27
**Dernière mise à jour** : 2025-01-27 (Amélioration modal paiement + Recherche avec suggestions + Filtres persistants + Navigation clavier complète + ARIA amélioré + Messages d'erreur actionnables)

## Vue d'ensemble

Ce document liste les améliorations UX proposées pour la plateforme zapwall.fr. Ces améliorations visent à optimiser l'expérience utilisateur en minimisant les clics, améliorant le feedback, et rendant l'interface plus intuitive.

## 1. Navigation et minimisation des clics

### Raccourcis clavier globaux
- **`/`** : Focus automatique sur la barre de recherche
- **`Esc`** : Fermer les modals et overlays
- **`Ctrl/Cmd + K`** : Ouvrir une recherche rapide (command palette)
- **Navigation par flèches** : Naviguer entre les articles dans les listes
- **`Tab`** : Navigation séquentielle améliorée avec focus visible

### Actions directes depuis les cartes d'articles
- Bouton "Débloquer" visible directement sur la carte (sans clic supplémentaire)
- Aperçu au survol avec tooltip ou preview expandable
- Lien direct vers l'auteur sans navigation intermédiaire
- Actions contextuelles au clic droit (si pertinent)

## 2. Feedback utilisateur et états de chargement

### Skeleton loaders
- Remplacer les messages "Loading..." par des skeleton loaders pour :
  - Liste d'articles
  - Cartes d'auteurs
  - Contenu d'article
  - Profil utilisateur
- Animation subtile pour indiquer le chargement

### Confirmations visuelles
- **Toast notifications** :
  - Après déblocage réussi d'un article
  - Après publication réussie
  - Après paiement confirmé
  - Après actions importantes (suppression, modification)
- **Indicateur visuel** pour contenu déjà débloqué :
  - Badge "Débloqué" sur les articles
  - Icône de cadenas ouvert
  - Couleur différente ou bordure distinctive
- **Animation de succès** après paiement :
  - Confetti subtil ou animation de validation
  - Message de confirmation clair

### États de progression
- Barre de progression pour paiements en cours
- Indicateur de synchronisation plus visible (actuellement dans le header)
- Feedback immédiat sur les actions :
  - Boutons avec état loading (spinner)
  - Désactivation pendant le traitement
  - Messages d'état contextuels

## 3. Recherche et filtres

### Recherche améliorée ✅ Implémenté
- ✅ **Recherche en temps réel** avec suggestions :
  - Autocomplétion basée sur les titres d'articles (5 suggestions max)
  - Suggestions d'auteurs (3 suggestions max)
  - Historique de recherche récente (5 dernières recherches, affiché quand la recherche est vide)
- ⏳ **Filtres combinables visibles** :
  - Badges actifs montrant les filtres appliqués
  - Compteur de résultats ("X articles trouvés")
  - Indication claire quand aucun résultat
- ✅ **Historique de recherche** :
  - Sauvegarder les recherches récentes dans IndexedDB (service `lib/searchHistory.ts`)
  - Affichage automatique de l'historique quand la recherche est vide
  - ⏳ Afficher les recherches populaires (à implémenter)

### Filtres persistants ✅ Implémenté
- ✅ Sauvegarder les préférences de filtres dans IndexedDB (service `lib/filterPreferences.ts`)
- ✅ Restaurer les filtres au retour sur la page (chargement automatique dans `useHomeState()`)
- ✅ Sauvegarde automatique à chaque modification des filtres
- ⏳ Options de filtres avancés (date, catégorie, auteur combinés) - À implémenter

## 4. Modal de paiement ✅ Implémenté

### Simplification du flux
- ✅ **Bouton "Payer avec Alby" en priorité** :
  - Plus grand et plus visible (variant "success", taille "large")
  - Couleur distinctive (neon-green)
  - Positionné en premier si Alby détecté
- ✅ **Auto-détection d'Alby** :
  - Détecter si Alby est disponible (hook `useAlbyDetection()` avec vérification périodique)
  - Affichage conditionnel du bouton selon la détection
  - Message d'installation affiché si Alby n'est pas installé
- ✅ **Instructions étape par étape** :
  - Guide visuel pour nouveaux utilisateurs (affiché conditionnellement)
  - Étapes numérotées claires (différentes selon présence d'Alby)
  - Instructions traduites (fr/en)
- ⏳ **Option "Se souvenir de ce choix"** :
  - À implémenter (mémorisation de la méthode de paiement préférée)

### Amélioration visuelle
- ✅ **QR code amélioré** :
  - Plus grand (300x300px)
  - Meilleur contraste (fond blanc, bordure cyan avec glow)
  - Bordure distinctive (`border-4 border-neon-cyan/50 shadow-[0_0_20px_rgba(0,255,255,0.3)]`)
- ✅ **Copie d'invoice** :
  - Bouton de copie visible (variant "secondary")
  - Confirmation visuelle immédiate (toast)
  - Copie en un clic
- ✅ **Compte à rebours** :
  - Plus visible (Badge avec format MM:SS)
  - Alerte visuelle quand < 60 secondes (animation pulse, variant "error")
  - Message d'expiration clair

## 5. Accessibilité clavier

### Navigation complète au clavier
- **Tab order logique** :
  - Ordre de tabulation cohérent sur toutes les pages
  - Skip links pour navigation rapide
  - Focus visible sur tous les éléments interactifs
- **Navigation par flèches** :
  - Flèches haut/bas dans les listes d'articles
  - Flèches gauche/droite pour navigation entre sections
  - Enter pour activer les éléments
- **Raccourcis documentés** :
  - Aide accessible via `?` ou `Ctrl/Cmd + /`
  - Modal d'aide avec tous les raccourcis
  - Indication des raccourcis dans les tooltips

### ARIA amélioré ✅ Implémenté
- ✅ **Labels ARIA** :
  - Tous les boutons iconiques ont des labels (liens dans PageHeader, KeyIndicator, NotificationBadgeButton, AuthorFilterButton, ClearButton, Toast close button)
  - Images avec alt text descriptif (déjà présent dans la plupart des composants)
  - Formulaires avec labels associés (déjà présent)
- ✅ **Régions ARIA** :
  - `role="navigation"` pour le header
  - `role="main"` pour le contenu principal
  - `role="search"` pour la barre de recherche (déjà présent)
  - `role="complementary"` pour les filtres (section changée en `<aside>`)
  - `role="contentinfo"` pour le footer
  - `role="tablist"` et `role="tab"` pour CategoryTabs
- ✅ **Annonces screen reader** :
  - `aria-live="polite"` dans ToastContainer (région) et Toast (éléments individuels)
  - `role="alert"` pour les toasts
  - Messages d'erreur annoncés via les toasts
  - Confirmations d'actions annoncées via les toasts

## 6. Gestion d'erreurs

### Messages d'erreur actionnables ✅ Implémenté
- ✅ **Messages clairs** :
  - Langage simple et compréhensible (système de classification dans `lib/errorClassification.ts`)
  - Explication de l'erreur (message d'erreur original préservé)
  - Impact sur l'utilisateur (suggestions contextuelles selon le type d'erreur)
- ✅ **Actions de récupération** :
  - Bouton "Réessayer" pour erreurs réseau, paiement, chargement (affiché automatiquement selon la classification)
  - Bouton "Vérifier la connexion" pour erreurs réseau et chargement (affiché automatiquement)
  - Lien vers documentation pour erreurs de paiement (affiché automatiquement)
- ✅ **Suggestions de solutions** :
  - "Vérifiez votre connexion Internet et réessayez" (erreurs réseau)
  - "Vérifiez votre connexion Alby et assurez-vous d'avoir des fonds suffisants" (erreurs paiement)
  - "Vérifiez que tous les champs requis sont remplis correctement" (erreurs validation)
  - "Impossible de charger les données. Vérifiez votre connexion et réessayez" (erreurs chargement)

### Récupération gracieuse
- **Retry automatique** :
  - Retry avec backoff exponentiel pour erreurs temporaires
  - Indicateur visuel des tentatives
  - Option d'annuler le retry
- **Sauvegarde locale** :
  - Sauvegarder les données en cas d'erreur réseau
  - Reprendre où on s'est arrêté après reconnexion
  - Indication des données en cache

## 7. Performance perçue

### Chargement progressif
- **Pagination ou infinite scroll** :
  - Charger les articles par lots
  - Indicateur de chargement pour les lots suivants
  - Option de pagination classique
- **Lazy loading** :
  - Images chargées à la demande
  - Contenu lourd chargé progressivement
- **Préchargement** :
  - Précharger les articles suivants en arrière-plan
  - Précharger les images des articles visibles

### Transitions fluides
- **Animations subtiles** :
  - Transitions de page (fade, slide)
  - Animations d'apparition des éléments
  - Micro-interactions sur les boutons
- **Feedback visuel immédiat** :
  - Changement d'état instantané sur les interactions
  - Loading states locaux (bouton, carte)
  - Optimistic UI updates quand possible

## 8. Clarté des actions

### Hiérarchie visuelle
- **CTA principaux** :
  - Plus visibles (couleur, taille, position)
  - Contraste élevé
  - Espacement approprié
- **Actions secondaires** :
  - Moins proéminentes
  - Style discret mais accessible
- **États désactivés** :
  - Visuellement distincts
  - Explication du pourquoi (tooltip)

### Contexte et aide
- **Tooltips explicatifs** :
  - Sur les actions complexes
  - Sur les icônes sans label
  - Sur les fonctionnalités avancées
- **Icônes avec labels** :
  - Labels textuels pour toutes les icônes
  - Option d'afficher/masquer les labels
- **Guide de première utilisation** :
  - Tour guidé pour nouveaux utilisateurs
  - Points d'intérêt clairs
  - Option de skip

## 9. Expérience de lecture

### Amélioration de l'affichage
- **Mode lecture** :
  - Largeur optimale pour la lecture
  - Typographie améliorée
  - Espacement des lignes ajustable
  - Taille de police ajustable
- **Navigation dans l'article** :
  - Bouton "Retour en haut" pour longs articles
  - Table des matières pour articles longs
  - Indicateur de progression de lecture
- **Navigation entre articles** :
  - Navigation précédent/suivant dans une série
  - Suggestions d'articles similaires
  - Articles de l'auteur en bas de page

### Partage et engagement
- **Boutons de partage** :
  - Partage vers Nostr
  - Copie du lien
  - Partage vers réseaux sociaux (optionnel)
- **Suggestions** :
  - Articles similaires
  - Articles du même auteur
  - Articles de la même catégorie
- **Indicateur de popularité** :
  - Nombre de déblocages (si public)
  - Badge "Populaire" pour articles avec beaucoup de déblocages

## 10. Profil et publications

### Gestion rapide
- **Actions rapides** :
  - Éditer en un clic depuis la liste
  - Supprimer avec confirmation
  - Dupliquer un article
- **Vue d'ensemble** :
  - Statistiques visuelles (nombre d'articles, déblocages)
  - Graphiques de performance (optionnel)
  - Vue d'ensemble des revenus (si applicable)

### Prévisualisation avant publication
- **Aperçu exact** :
  - Prévisualisation WYSIWYG
  - Vue exacte de l'article tel qu'il apparaîtra
  - Test sur différents formats (mobile, desktop)
- **Validation avant publication** :
  - Checklist de validation
  - Vérification des champs requis
  - Avertissements pour champs manquants

## Priorisation

### Priorité haute
1. Skeleton loaders
2. Toast notifications
3. Indicateur visuel pour contenu débloqué
4. Raccourcis clavier de base (`/`, `Esc`)
5. ✅ Amélioration de la modal de paiement - Implémenté

### Priorité moyenne
6. ✅ Recherche améliorée avec suggestions - Implémenté
7. ✅ Filtres persistants - Implémenté
8. ✅ Navigation clavier complète - Implémenté
9. ✅ ARIA amélioré - Implémenté
10. ✅ Messages d'erreur actionnables - Implémenté

### Priorité basse
11. Mode lecture
12. Partage et engagement
13. Guide de première utilisation
14. Prévisualisation avant publication
15. Chargement progressif avancé

## Notes d'implémentation

- Toutes les améliorations doivent respecter les règles de qualité du projet
- Aucun fallback ne doit être introduit
- Tous les changements doivent être accessibles (ARIA, clavier, contraste)
- Les améliorations doivent minimiser les clics selon les règles du projet
- La documentation doit être mise à jour avec chaque amélioration