Keep/_bmad-output/planning-artifacts/memory-echo-connections-ux-specification.md

---
specificationType: 'feature-ux-design'
featureName: 'Memory Echo Connections Management'
project: Keep
author: Sally (UX Designer) & Ramez
date: '2026-01-10'
status: 'draft'
version: '1.0'
---

# UX Design Specification - Memory Echo Connections Management

**Project:** Keep (Memento)
**Feature:** Gestion Évoluée des Connexions Memory Echo
**Author:** Sally (UX Designer) & Ramez
**Date:** 2026-01-10
**Version:** 1.0

---

## Table des Matières

1. [Executive Summary](#executive-summary)
2. [Context & Problem Statement](#context--problem-statement)
3. [User Personas & Scenarios](#user-personas--scenarios)
4. [Design Principles](#design-principles)
5. [User Flow Diagrams](#user-flow-diagrams)
6. [Interface Specifications](#interface-specifications)
7. [Interaction Design](#interaction-design)
8. [Visual Design Specifications](#visual-design-specifications)
9. [Technical Considerations](#technical-considerations)
10. [Implementation Roadmap](#implementation-roadmap)
11. [Success Metrics](#success-metrics)

---

## Executive Summary

### Vision

Transformer Memory Echo d'une feature "push only" (notifications uniquement) à un système **interactif de gestion des connexions**, permettant aux utilisateurs de visualiser, comprendre et agir sur les relations sémantiques entre leurs notes.

### Objectifs Principaux

1. **Visibilité permanente** - Les connexions ne disparaissent plus après un clic
2. **Exploration flexible** - L'utilisateur peut voir les connexions à différents niveaux de détail
3. **Actions intelligentes** - Fusion et gestion des notes similaires
4. **Scalabilité** - Fonctionne de 2 à 22+ connexions sans surcharger l'interface

### Philosophie de Design

**"Révélation Progressive" (Progressive Disclosure)**

> Les informations et actions apparaissent graduellement, du plus simple au plus détaillé, selon le besoin de l'utilisateur.

- **Niveau 1** : Indicateur visuel discret
- **Niveau 2** : Vue d'ensemble rapide (overlay)
- **Niveau 3** : Détails et actions complètes (éditeur)

---

## Context & Problem Statement

### État Actuel

**Memory Echo (Phase 1)** :
- ✅ Détection automatique des connexions sémantiques
- ✅ Notifications push quand nouvelles connexions
- ✅ Modal temporaire pour voir 2 notes côte à côte
- ✅ Feedback utilisateur (pouces haut/bas)

**Limites Identifiées** :

1. **Modal éphémère** - Le modal se ferme et on perd la vue
2. **Pas de vue globale** - Impossible de voir toutes les connexions d'une note
3. **Actions limitées** - Pas de fusion ou gestion des notes similaires
4. **Pas scalable** - Avec 22 notes similaires, le modal actuel est inadapté

### Scénario Problème

> Ramez a créé 22 notes sur "Project X" depuis 3 mois. Memory Echo détecte toutes ces connexions. Il clique sur "View Connection", voit 2 notes dans un modal... puis le modal se ferme. Il doit cliquer à nouveau pour voir les 2 notes suivantes. Il n'a PAS de vue globale. Il ne peut PAS fusionner ces 22 notes facilement. C'est fastidieux.

### Besoins Utilisateur

**Primary Use Case** :
"Je veux voir toutes les notes connexes d'un coup, comprendre les relations, et décider quoi faire (fusionner, garder séparé, etc.)"

**Secondary Use Cases** :
- Explorer les connexions sans obligation d'action
- Fusionner intelligemment des notes dupliquées
- Comprendre pourquoi deux notes sont connectées
- Naviguer rapidement entre notes connexes

---

## User Personas & Scenarios

### Persona Principal : Ramez

**Profile** :
- Développeur intermédiaire
- Utilise Keep quotidiennement pour notes techniques
- Beaucoup de notes sur des sujets similaires
- Veut de l'efficacité, pas de la friction

**Motivations** :
- "Je ne veux pas perdre de temps à chercher mes notes"
- "Si j'ai 3 fois la même info, je veux fusionner"
- "Montre-moi ce qui est pertinent, cache le reste"

**Frustrations Actuelles** :
- Modal qui disparaît trop vite
- Pas de vue globale des connexions
- Fusion manuelle chronophage

### User Journey

#### Journey 1 : Découverte de Connexions Multiples

```
1. Ramez ouvre Keep
   → Voir badge "⚡ 12 connexions" sur une note

2. Il clique sur le badge
   → Overlay s'ouvre avec liste des 12 notes connexes

3. Il parcourt la liste
   → Voit similarité % pour chaque note

4. Il décide de voir plus en détail
   → Clique "Voir côte à côte" sur 3 notes

5. Modal s'ouvre avec les 3 notes
   → Il comprend les relations

6. Il décide de fusionner
   → Clique "Fusionner intelligemment"

7. Preview de la fusion
   → Il valide

8. Fusion réussie !
   → Les 3 notes originales archivées
   → Nouvelle note combinée créée
```

#### Journey 2 : Exploration Sans Action

```
1. Ramez ouvre une note dans l'éditeur

2. En bas, section "⚡ Notes Connexes (8)"

3. Il parcourt les connexions
   → Clique sur une note connexe

4. Cette note s'ouvre dans un nouvel onglet/panel
   → Il compare les deux

5. Il décide de NE PAS fusionner
   → Ferme la note connexe

6. Il continue d'explorer
   → Clique sur une autre connexion

7. Il revient à sa note originale
   → Continuer son travail
```

---

## Design Principles

### 1. **Révélation Progressive**

Les informations apparaissent graduellement :
- Toujours visible : Badge discret sur les notes
- Au clic : Overlay avec liste des connexions
- En éditor : Section permanente avec détails

### 2. **Non-Intrusif**

La feature ne gêne pas l'utilisation normale :
- Badge visible mais pas dominant
- Overlay se ferme facilement
- Section dans l'éditor peut être réduite

### 3. **Contextuel**

Les actions sont au bon endroit :
- Dans la grille → Quick view (overlay)
- Dans l'éditeur → Actions détaillées
- Dans le modal → Fusion intelligente

### 4. **Scalable**

Fonctionne avec peu ou beaucoup de connexions :
- 2-3 connexions : Affichage direct
- 4-10 connexions : Liste avec pagination
- 11+ connexions : Liste + filtres + tri

### 5. **Performant**

Rapide et fluide :
- Lazy loading des connexions
- Pagination si besoin
- Pas de rechargement de page

---

## User Flow Diagrams

### Flow 1 : Découverte depuis la Grille

```
┌─────────────────────────────────────────────────────────────┐
│                    GRILLE PRINCIPALE                         │
│                                                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │   Note A     │  │   Note B     │  │   Note C     │     │
│  │              │  │              │  │              │     │
│  │ ⚡ 5 connex.  │  │              │  │ ⚡ 12 connex. │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
└─────────────────────────────────────────────────────────────┘
                        │
                        ▼
             Clic sur badge "⚡ 5 connex."
                        │
                        ▼
┌─────────────────────────────────────────────────────────────┐
│                    OVERLAY CONNEXIONS                        │
│                                                             │
│  ⚡ Notes Connexes (5)                                [X]   │
│  ┌─────────────────────────────────────────────────────┐  │
│  │ 📝 Note A1 - Related Topic               94%        │  │
│  │ [Voir] [Voir côte à côte ▼]                         │  │
│  ├─────────────────────────────────────────────────────┤  │
│  │ 📝 Note A2 - Similar Content            89%        │  │
│  │ [Voir] [Voir côte à côte ▼]                         │  │
│  └─────────────────────────────────────────────────────┘  │
│                                                             │
│  [Voir tout côte à côte]                                    │
└─────────────────────────────────────────────────────────────┘
                        │
            ┌───────────┴───────────┐
            ▼                       ▼
     Clic "Voir"           Clic "Voir côte à côte"
            │                       │
            ▼                       ▼
    Ouvre note              MODAL COMPARAISON
    dans éditeur            (2-3 notes côte à côte)
                                    │
                                    ▼
                            Actions:
                            - Fusionner
                            - Voir note
                            - Fermer
```

### Flow 2 : Gestion dans l'Éditeur

```
┌─────────────────────────────────────────────────────────────┐
│                       ÉDITEUR DE NOTE                        │
│                                                             │
│  ┌───────────────────────────────────────────────────────┐ │
│  │  📝 Ma Note                                            │ │
│  │                                                       │ │
│  │  [Contenu de la note...]                             │ │
│  │                                                       │ │
│  │                                                       │ │
│  └───────────────────────────────────────────────────────┘ │
│                                                             │
│  ┌───────────────────────────────────────────────────────┐ │
│  │  ⚡ Notes Connexes (5)                        [−]      │ │
│  │  ┌─────────────────────────────────────────────────┐  │ │
│  │  │ 📝 Note A1 - Related Topic           94%       │  │ │
│  │  │ [Voir] [Fusionner ▼]                          │  │ │
│  │  └─────────────────────────────────────────────────┘  │ │
│  │  ┌─────────────────────────────────────────────────┐  │ │
│  │  │ 📝 Note A2 - Similar Content          89%       │  │ │
│  │  │ [Voir] [Fusionner ▼]                          │  │ │
│  │  └─────────────────────────────────────────────────┘  │ │
│  │                                                       │ │
│  │  [Tout voir côte à côte] [Tout fusionner...]        │  │
│  └───────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```

### Flow 3 : Fusion Intelligente

```
┌─────────────────────────────────────────────────────────────┐
│                     MODAL FUSION                             │
│                                                             │
│  🔗 Fusion Intelligente                                     │
│  ┌─────────────────────────────────────────────────────┐  │
│  │  Sélection: 3 notes                                 │  │
│  │                                                     │  │
│  │  ┌──────────────────────┐                           │  │
│  │  │ 📝 Note 1            │                           │  │
│  │  │ "Meeting about..."   │                           │  │
│  │  └──────────────────────┘                           │  │
│  │             +                                       │  │
│  │  ┌──────────────────────┐                           │  │
│  │  │ 📝 Note 2            │                           │  │
│  │  │ "Discussed..."       │                           │  │
│  │  └──────────────────────┘                           │  │
│  │             +                                       │  │
│  │  ┌──────────────────────┐                           │  │
│  │  │ 📝 Note 3            │                           │  │
│  │  │ "Project X..."       │                           │  │
│  │  └──────────────────────┘                           │  │
│  │             =                                       │  │
│  │  ┌──────────────────────┐                           │  │
│  │  │ 📝 NOTE FUSIONNÉE    │  ← Preview IA            │  │
│  │  │ "Team meeting about  │                           │  │
│  │  │  Project X: discussed│                           │  │
│  │  │  deadlines and..."   │                           │  │
│  │  └──────────────────────┘                           │  │
│  └─────────────────────────────────────────────────────┘  │
│                                                             │
│  Options:                                                   │
│  ☑ Archiver les notes originales                           │
│  ☑ Conserver les tags de toutes les notes                  │
│                                                             │
│  [Annuler]  [Modifier manuellement]  [Confirmer la fusion] │
└─────────────────────────────────────────────────────────────┘
```

---

## Interface Specifications

### Composant 1 : Badge de Connexions (Grille)

**Emplacement** : Coin inférieur droit de chaque note card dans la grille Masonry

**Apparence** :
```
┌─────────────────────────────┐
│  Titre de la note           │
│                             │
│  Contenu de la note...      │
│                             │
│  ⚡ 5 connexions    ◀─────── Badge
└─────────────────────────────┘
```

**Spécifications** :
- **Couleur** : Fond ambre/or clair (`bg-amber-100 dark:bg-amber-900/30`)
- **Texte** : "⚡ X connexions" en ambre foncé (`text-amber-700 dark:text-amber-400`)
- **Icône** : ⚡ (Sparkles de Lucide-react)
- **Police** : xs (12px), font-weight normal
- **Border-radius** : rounded-md
- **Padding** : px-2 py-1
- **Position** : absolute bottom-2 right-2
- **Z-index** : 10 (au-dessus du contenu)
- **États** :
  - **Normal** : Opacité 100%
  - **Hover** : Opacité 100%, cursor pointer, bordure ambre
  - **Disabled/Aucune connexion** : Non affiché

**Interaction** :
- Click → Ouvre l'overlay des connexions
- Hover → Léger zoom + tooltip "Voir les connexions"

**Condition d'affichage** :
- Si 1+ connexions → Afficher le badge
- Si 0 connexions → Masquer

### Composant 2 : Overlay Connexions

**Type** : Modal/Dialog centré

**Dimensions** :
- Largeur : max-w-2xl (672px)
- Hauteur : max-h-[80vh]
- Position : fixed inset-0, centré

**Structure** :
```
┌─────────────────────────────────────────────────┐
│  ⚡ Notes Connexes (12)                  [X]    │
├─────────────────────────────────────────────────┤
│  🔍 [Filtrer...]   [Tri par: similarité ▼]     │
├─────────────────────────────────────────────────┤
│  ┌───────────────────────────────────────────┐  │
│  │ 📝 Note connexe 1          94%    [▾]     │  │
│  │ Preview du contenu...                     │  │
│  │ [Voir] [Voir côte à côte ▼]              │  │
│  └───────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────┐  │
│  │ 📝 Note connexe 2          89%    [▾]     │  │
│  │ Preview du contenu...                     │  │
│  │ [Voir] [Voir côte à côte ▼]              │  │
│  └───────────────────────────────────────────┘  │
│                                                  │
│  [< 1 2 3 4 5 >] (pagination si 10+ connexions)  │
├─────────────────────────────────────────────────┤
│     [Voir tout côte à côte]                     │
└─────────────────────────────────────────────────┘
```

**Spécifications** :

**Header** :
- Titre : "⚡ Notes Connexes (X)"
- Bouton close (X) en haut à droite
- Icône ⚡ en ambre

**Filtres et Tri** (optionnel, visible si 7+ connexions) :
- Input recherche : filtrer par titre/contenu
- Dropdown tri : "Plus similaire", "Plus récent", "Plus ancien"

**Liste des connexions** :
- Chaque connexion = carte avec :
  - Titre de la note connexe (gras, cliquable)
  - Badge pourcentage de similarité (coins haut à droite)
  - Preview du contenu (line-clamp-2, 2 lignes max)
  - Tags/labels si présents
  - Dropdown menu [▾] :
    - "Voir cette note"
    - "Voir côte à côte"
    - "Fusionner avec..."
    - "Masquer cette connexion"
  - Boutons rapides :
    - [Voir] → Ouvre la note dans l'éditeur
    - [Voir côte à côte ▼] → Menu : sélectionner 2-3 notes à comparer

**Pagination** :
- Si > 10 connexions : afficher 10 par page
- Pagination en bas : [< 1 2 3 4 5 >]

**Footer** :
- Bouton principal : [Voir tout côte à côte]
- Ouvre modal avec toutes les connexions (max 5)

### Composant 3 : Modal Comparaison Côte à Côte

**Dimensions** :
- Largeur : max-w-6xl (896px) pour 2 notes, max-w-7xl (1024px) pour 3 notes
- Hauteur : max-h-[90vh]

**Layout** : Grid avec 2 ou 3 colonnes selon sélection

**Structure** :
```
┌─────────────────────────────────────────────────────────────┐
│  ⚡ Comparaison de Notes                           [X]       │
│  Ces notes sont connectées par 94% de similarité            │
├─────────────────────────────────────────────────────────────┤
│  💡 Insight: "Ces notes traitent toutes du même            │
│  sujet sous des angles complémentaires..."                  │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────────────┐  ┌─────────────────────┐          │
│  │ 📝 Note 1           │  │ 📝 Note 2           │          │
│  │ [Titre]             │  │ [Titre]             │          │
│  │                     │  │                     │          │
│  │ [Contenu...]        │  │ [Contenu...]        │          │
│  │                     │  │                     │          │
│  │                     │  │                     │          │
│  │                     │  │                     │          │
│  └─────────────────────┘  └─────────────────────┘          │
│  [Cliquez pour ouvrir]    [Cliquez pour ouvrir]            │
├─────────────────────────────────────────────────────────────┤
│  [← Ajouter une note]              [Fusionner tout ▼]      │
└─────────────────────────────────────────────────────────────┘
```

**Spécifications** :

**Header** :
- Titre : "⚡ Comparaison de Notes"
- Sous-titre : "Ces notes sont connectées par X% de similarité"
- Pourcentage affiché en ambre

**Section Insight IA** (optionnelle) :
- Fond ambre clair
- Icône 💡
- Texte explicatif généré par l'IA
- "Ces notes traitent toutes du même sujet..."

**Grille de notes** :
- Layout : `grid grid-cols-2 gap-6` (2 notes) ou `grid grid-cols-3 gap-4` (3 notes)
- Chaque note :
  - Bordure fine
  - Hover : bordure ambre, curseur pointer
  - Titre en gras (couleur distincte par note)
  - Contenu avec `line-clamp-8` (8 lignes max)
  - Bas de carte : "Cliquez pour ouvrir"

**Footer** :
- Bouton gauche : [← Ajouter une note] (si < 3 notes)
- Bouton droit : [Fusionner tout ▼]
  - Dropdown : "Fusionner intelligemment", "Fusionner manuellement"

### Composant 4 : Section Connexions (Éditeur)

**Emplacement** : En bas de l'éditeur de note, après le contenu

**États** :
- **Ouvert** : Affiche toutes les connexions
- **Réduit** : Affiche juste le header

**Structure - État Ouvert** :
```
┌───────────────────────────────────────────────────────────┐
│  📝 Ma Note                                                │
│  [Éditeur...]                                             │
├───────────────────────────────────────────────────────────┤
│  ⚡ Notes Connexes (5)                            [−]     │
│  ┌─────────────────────────────────────────────────────┐  │
│  │ 📝 Note A1 - Related Topic               94%       │  │
│  │ [Preview...]                                       │  │
│  │ [Voir] [Fusionner ▼]                              │  │
│  └─────────────────────────────────────────────────────┘  │
│  ┌─────────────────────────────────────────────────────┐  │
│  │ 📝 Note A2 - Similar Content              89%       │  │
│  │ [Preview...]                                       │  │
│  │ [Voir] [Fusionner ▼]                              │  │
│  └─────────────────────────────────────────────────────┘  │
│                                                           │
│  [Tout voir côte à côte] [Tout fusionner...]             │
└───────────────────────────────────────────────────────────┘
```

**Structure - État Réduit** :
```
┌───────────────────────────────────────────────────────────┐
│  ⚡ Notes Connexes (5)                            [+]     │
└───────────────────────────────────────────────────────────┘
```

**Spécifications** :
- Header avec bouton [−]/[+] pour réduire/ouvrir
- Même layout que l'overlay, mais intégré dans l'éditeur
- Pas de bouton close (X)
- Scrollable si beaucoup de connexions
- Sticky header si scroll

### Composant 5 : Modal Fusion Intelligente

**Dimensions** :
- Largeur : max-w-3xl (768px)
- Hauteur : auto (adaptable au contenu)

**Structure** :
```
┌─────────────────────────────────────────────────────────────┐
│  🔗 Fusion Intelligente                                     │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐  │
│  │  📝 Notes à fusionner                               │  │
│  │  ┌───────────────────────────────────────────────┐  │  │
│  │  │ ☑ Note 1: "Meeting about Project X"          │  │  │
│  │  │    Created: Jan 5, 2026                       │  │  │
│  │  ├───────────────────────────────────────────────┤  │  │
│  │  │ ☑ Note 2: "Discussed deadlines..."            │  │  │
│  │  │    Created: Jan 8, 2026                       │  │  │
│  │  ├───────────────────────────────────────────────┤  │  │
│  │  │ ☑ Note 3: "Project X deliverables"            │  │  │
│  │  │    Created: Jan 10, 2026                      │  │  │
│  │  └───────────────────────────────────────────────┘  │  │
│  │                                                     │  │
│  │  [+ Ajouter une note]                              │  │
│  └─────────────────────────────────────────────────────┘  │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐  │
│  │  💬 Prompt de fusion (optionnel)                    │  │
│  │  [Instruction optionnelle pour l'IA...]            │  │
│  │                                                     │  │
│  │  [Générer la fusion]                                │  │
│  └─────────────────────────────────────────────────────┘  │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐  │
│  │  📝 Preview de la note fusionnée                    │  │
│  │  ┌───────────────────────────────────────────────┐  │  │
│  │  │ "Team meeting about Project X: discussed     │  │  │
│  │  │  deadlines and deliverables. Key points:..." │  │  │
│  │  │                                               │  │  │
│  │  │                                               │  │  │
│  │  └───────────────────────────────────────────────┘  │  │
│  │                                                     │  │
│  │  [Modifier manuellement]                            │  │
│  └─────────────────────────────────────────────────────┘  │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐  │
│  │  Options de fusion                                   │  │
│  │  ☑ Archiver les notes originales                    │  │
│  │  ☑ Conserver tous les tags                          │  │
│  │  ☐ Conserver la note la plus récente comme titre    │  │
│  │  ☐ Créer un rétrolien vers les notes originales     │  │
│  └─────────────────────────────────────────────────────┘  │
│                                                             │
│  [Annuler]  [Modifier manuellement]  [✓ Confirmer la fusion] │
└─────────────────────────────────────────────────────────────┘
```

**Spécifications** :

**Section 1 : Sélection des notes**
- Liste avec checkboxes (toutes cochées par défaut)
- Chaque note : titre + date de création
- Hover : preview du contenu (tooltip)
- Bouton [+ Ajouter une note] pour en inclure d'autres

**Section 2 : Prompt (optionnel)**
- Input textarea pour instruction personnalisée
- Exemple : "Garder le style formel de la note 1"
- Par défaut : vide = l'IA fait de son mieux

**Bouton [Générer la fusion]** :
- Appelle l'IA pour générer la note fusionnée
- Show loading spinner pendant génération
- Preview apparaît dans la section suivante

**Section 3 : Preview**
- Zone de texte éditable
- Peut être modifiée manuellement
- Syntax highlighting/markdown support
- Scrollable si long contenu

**Section 4 : Options**
- Checkboxes pour comportement post-fusion
- Toutes cochées par défaut (sauf exception)

**Actions footer** :
- **[Annuler]** : Ferme le modal, annule tout
- **[Modifier manuellement]** : Focus sur la preview, désactive le bouton "Générer"
- **[✓ Confirmer la fusion]** : Crée la nouvelle note, archive les originaux

---

## Interaction Design

### Interactions Badge Connexions

**États** :
1. **Normal** : Badge visible, statique
2. **Hover** :
   - Opacity: 100% → 100% (pas de changement)
   - Transform: scale(1.05)
   - Border: 1px solid ambre
   - Cursor: pointer
   - Tooltip: "Voir les X connexions"
3. **Active** : Click → ouvre overlay

**Transitions** :
- Duration: 150ms
- Easing: ease-out
- Properties: transform, border-color

**Feedback** :
- Click : Overlay apparaît avec fade-in + slide-up (200ms)

### Interactions Overlay

**Ouverture** :
- Animation : fade-in (0% → 100%) + scale(0.95 → 1)
- Duration : 200ms
- Easing : ease-out
- Backdrop : bg-black/50 avec backdrop-blur-sm

**Fermeture** :
- Click sur X ou backdrop
- Animation : fade-out + scale(1 → 0.95)
- Duration : 150ms
- Escape key : ferme aussi

**Scroll** :
- Si > 5 connexions : overflow-y-auto
- Scrollbar stylisée (ambre)
- Max-height : 60vh

**Hover sur une connexion** :
- Background : hover:bg-gray-50 dark:hover:bg-zinc-800
- Border-left : 3px solid ambre
- Transform: translateX(4px)
- Duration: 150ms

### Interactions Modal Comparaison

**Clic sur une note** :
- Ouvre la note dans l'éditeur
- Ferme le modal
- Toast: "Note ouverte"

**Bouton [← Ajouter une note]** :
- Ouvre dropdown avec les autres connexions
- Max 3 notes dans le modal

**Bouton [Fusionner tout ▼]** :
- Dropdown : "Fusionner intelligemment", "Fusionner manuellement"
- "Fusionner intelligemment" → Ouvre modal fusion intelligente
- "Fusionner manuellement" → Ouvre modal d'édition de fusion

### Interactions Modal Fusion

**Génération IA** :
- Click [Générer la fusion]
- Button → loading state avec spinner
- Toast: "Génération en cours..."
- Après 2-3s : Preview apparaît
- Toast: "Fusion générée !"

**Modification manuelle** :
- Click [Modifier manuellement]
- Focus sur textarea de preview
- Button désactivé : [Générer la fusion]
- Button activé : [Confirmer la fusion]

**Confirmation** :
- Click [✓ Confirmer la fusion]
- Loading state sur le bouton
- API call pour créer la note
- Archives des notes originales
- Modal ferme
- Toast: "✓ Notes fusionnées avec succès !"
- Éditeur s'ouvre avec la nouvelle note

### Interactions Section Éditeur

**Toggle Ouvert/Réduit** :
- Click sur [−] ou [+]
- Animation : slide-up / slide-down
- Duration : 200ms
- Easing : ease-in-out
- Icon transition : rotate(0deg) ↔ rotate(180deg)

**Scroll** :
- Section scrollable indépendamment
- Header sticky en haut
- Max-height : 300px

---

## Visual Design Specifications

### Palette de Couleurs

**Primary (Amber/Memory Echo)** :
- `amber-50` : bg-amber-50 (sous-fonds très clairs)
- `amber-100` : bg-amber-100 (badges, cards)
- `amber-200` : border-amber-200 (bordures légères)
- `amber-400` : text-amber-400 (texte secondaire dark mode)
- `amber-500` : text-amber-500 (texte principal)
- `amber-600` : bg-amber-600 (boutons primary)
- `amber-700` : text-amber-700 (texte dark mode)
- `amber-900/30` : bg-amber-900/30 (badges dark mode)
- `amber-950/20` : bg-amber-950/20 (sous-fonds dark mode)

**Neutral (Gray/Zinc)** :
- Utiliser la palette existante de l'appli
- `gray-50`, `gray-100`, ..., `gray-900`
- `zinc-50`, `zinc-100`, ..., `zinc-900` (dark mode)

**Sémantique** :
- Success (fusion réussie) : `green-600`
- Error (erreur fusion) : `red-600`
- Warning (confirmation action) : `yellow-600`

### Typographie

**Familles** : Utiliser les fonts de l'appli (probablement Inter ou system-ui)

**Tailles** :
- Badge : text-xs (12px)
- Titre note : text-base (16px), font-semibold
- Preview contenu : text-sm (14px)
- Similarity % : text-xs (12px), font-medium
- Insight IA : text-sm (14px)

**Weights** :
- Regular : 400
- Medium : 500
- Semibold : 600
- Bold : 700

### Espacements

**Badges** : px-2 py-1 (8px horizontal, 4px vertical)
**Cards connexions** : p-3 (12px padding)
**Modal** : p-6 (24px padding)
**Sections** : gap-3, gap-4 entre éléments

### Icônes

**Source** : Lucide React
**Tailles** :
- Small : h-3 w-3, h-4 w-4
- Medium : h-5 w-5
- Large : h-6 w-6

**Icônes utilisées** :
- ⚡ Sparkles : connexions Memory Echo
- 💡 Lightbulb : insights IA
- 🔗 Link : fusion
- 👁️ Eye : voir
- ✏️ Edit : modifier
- ✓ Check : confirmer
- ✕ X : fermer/annuler
- ▼ ChevronDown : dropdowns
- ▲ ChevronUp : toggle ouvert
- ➕ Plus : ajouter
- ➔ ArrowRight : navigation

### Ombres & Bordures

**Ombres** :
- Badge : shadow-sm
- Card : shadow
- Modal : shadow-xl

**Bordures** :
- Badge : border-amber-200
- Card : border-gray-200 dark:border-zinc-700
- Modal : border-gray-200

**Border-radius** :
- Badge : rounded-md (4px)
- Card : rounded-lg (8px)
- Modal : rounded-lg (8px)

---

## Technical Considerations

### Performance

**Lazy Loading** :
- Charger les connexions au clic sur le badge
- Pas précharger toutes les connexions de toutes les notes
- Pagination pour 10+ connexions

**Caching** :
- Cache les connexions récupérées (session storage)
- Invalider le cache quand une note est modifiée
- TTL : 5 minutes

**API Calls** :
- Endpoint : `/api/ai/echo/connections?noteId={id}`
- Response format :
```json
{
  "connections": [
    {
      "noteId": "xxx",
      "title": "Note connexe",
      "content": "Preview...",
      "similarity": 0.94,
      "insight": "Ces notes sont..."
    }
  ],
  "total": 12
}
```

### Responsive Design

**Mobile** :
- Badge : toujours visible en bas à droite
- Overlay : full-screen au lieu de modal centré
- Modal comparaison : grid 1 colonne au lieu de 2-3
- Section éditeur : collapsée par défaut

**Tablet** :
- Similar to desktop
- Réduire largeur modale (max-w-xl au lieu de max-w-2xl)

**Desktop** :
- Spécifications détaillées ci-dessus

### Accessibility

**ARIA Labels** :
- Badge : `aria-label="Voir les 5 connexions de cette note"`
- Overlay : `role="dialog" aria-modal="true"`
- Boutons : `aria-label` descriptifs

**Keyboard Navigation** :
- Tab : naviguer entre les connexions
- Enter/Space : sélectionner une connexion
- Escape : fermer overlay/modal
- Arrow keys : naviguer dans la liste

**Screen Readers** :
- Annoncer "5 connexions disponibles"
- Lire la similarité en pourcentage
- Annoncer les actions disponibles

**Focus Management** :
- Ouverture overlay : focus sur première connexion
- Fermeture : focus retourne sur le badge
- Modal fusion : focus sur première checkbox

### États & Gestion d'État

**États nécessaires** :
```typescript
interface ConnectionsState {
  // Overlay
  isOverlayOpen: boolean
  selectedNoteId: string | null

  // Modal comparaison
  isComparisonModalOpen: boolean
  comparisonNotes: string[] (max 3)

  // Modal fusion
  isFusionModalOpen: boolean
  selectedNotesForFusion: string[]
  fusionPreview: string | null
  isGeneratingFusion: boolean

  // Section éditeur
  isConnectionSectionExpanded: boolean

  // Données
  connections: Connection[]
  isLoadingConnections: boolean
}
```

**Events** :
- `onOpenConnections` : ouvrir overlay
- `onCloseConnections` : fermer overlay
- `onSelectConnection` : sélectionner une connexion
- `onOpenComparison` : ouvrir modal comparaison
- `onOpenFusion` : ouvrir modal fusion
- `onGenerateFusion` : générer fusion IA
- `onConfirmFusion` : confirmer fusion
- `onToggleSection` : toggle section éditeur

### Error Handling

**Cas d'erreur** :
1. **Échec chargement connexions** :
   - Message : "Impossible de charger les connexions"
   - Action : bouton "Réessayer"

2. **Échec génération fusion** :
   - Message : "Erreur lors de la génération"
   - Action : bouton "Réessayer" ou "Modifier manuellement"

3. **Échec création note fusionnée** :
   - Message : "Erreur lors de la création de la note"
   - Action : conserver dans le modal pour retry

4. **Pas de connexions** :
   - Badge non affiché
   - Message dans section : "Aucune connexion détectée"

---

## Implementation Roadmap

### Phase 1 : Fondations (Semaine 1)

**Sprint 1.1 : Backend API**
- [ ] Créer endpoint `/api/ai/echo/connections`
- [ ] Implémenter la logique de récupération des connexions
- [ ] Ajouter pagination si > 10 connexions
- [ ] Tests unitaires

**Sprint 1.2 : Composant Badge**
- [ ] Créer `ConnectionsBadge.tsx`
- [ ] Intégrer dans `NoteCard.tsx`
- [ ] Gérer l'état de visibilité
- [ ] Tests composant

### Phase 2 : Overlay & Découverte (Semaine 2)

**Sprint 2.1 : Overlay Connexions**
- [ ] Créer `ConnectionsOverlay.tsx`
- [ ] Implémenter la liste des connexions
- [ ] Ajouter filtres et tri
- [ ] Pagination si > 10
- [ ] Animations d'ouverture/fermeture

**Sprint 2.2 : Modal Comparaison**
- [ ] Créer `ComparisonModal.tsx`
- [ ] Grid 2-3 colonnes
- [ ] Insight IA optionnel
- [ ] Actions rapides

### Phase 3 : Éditeur & Actions (Semaine 3)

**Sprint 3.1 : Section Éditeur**
- [ ] Créer `EditorConnectionsSection.tsx`
- [ ] Toggle ouvert/réduit
- [ ] Liste des connexions
- [ ] Actions rapides

**Sprint 3.2 : Modal Fusion (Partie 1)**
- [ ] Créer `FusionModal.tsx`
- [ ] UI de sélection des notes
- [ ] Preview area
- [ ] Options de fusion

### Phase 4 : Fusion Intelligente (Semaine 4)

**Sprint 4.1 : Backend Fusion**
- [ ] Endpoint `/api/ai/echo/merge`
- [ ] Intégrer génération IA (prompt)
- [ ] Créer la note fusionnée
- [ ] Archiver les notes originales

**Sprint 4.2 : Modal Fusion (Partie 2)**
- [ ] Connecter au backend
- [ ] Loading states
- [ ] Error handling
- [ ] Toast notifications

### Phase 5 : Polish & Tests (Semaine 5)

**Sprint 5.1 : UX Refinement**
- [ ] Micro-interactions
- [ ] Animations fluides
- [ ] Responsive design
- [ ] Accessibility audit

**Sprint 5.2 : Testing & Documentation**
- [ ] Tests E2E
- [ ] Tests d'intégration
- [ ] Documentation utilisateur
- [ ] Migration guide

---

## Success Metrics

### Metrics Quantitatives

**Adoption** :
- % d'utilisateurs qui cliquent sur le badge dans les 7 premiers jours
- Nombre moyen de connexions vues par session
- Taux d'utilisation de la fusion

**Engagement** :
- Temps passé dans l'overlay
- Nombre de connexions explorées avant action
- Taux de conversion (vue → action)

**Performance** :
- Temps de chargement des connexions < 500ms
- Temps de génération fusion < 3s
- 0 bugs critiques

### Metrics Qualitatifs

**User Feedback** :
- Feedback positif sur les connexions trouvées
- "Les fusions sont utiles"
- "Je trouve ce que je cherche plus vite"

**UX Quality** :
- L'overlay est intuitif (pas de confusion)
- La fusion donne de bons résultats
- La feature ne gêne pas l'utilisation normale

### Success Criteria

**MVP Success** (Phase 1-2) :
- ✅ Badge visible sur les notes avec connexions
- ✅ Overlay fonctionnel avec liste des connexions
- ✅ Modal comparaison pour 2-3 notes
- ✅ 0 régression bug

**Full Success** (Phase 1-4) :
- ✅ Toutes les fonctionnalités implémentées
- ✅ Fusion intelligente fonctionnelle
- ✅ Section éditeur intégrée
- ✅ 90%+ satisfaction utilisateur

**Stretch Goals** (Phase 5+) :
- Vue mind-map/graph (backlog)
- Fusion en lot (batch merge)
- Connexions transientes (A ↔ B ↔ C)
- Export des connexions en JSON

---

## Conclusion

Cette spécification UX fournit un plan complet pour la gestion évoluée des connexions Memory Echo, en suivant le principe de **révélation progressive** et en respectant la philosophie **"Zéro Prise de Tête"**.

**Points clés** :
- ✅ Visibilité permanente des connexions
- ✅ Exploration flexible à 3 niveaux
- ✅ Actions intelligentes (fusion)
- ✅ Scalable de 2 à 22+ connexions
- ✅ Non-intrusif et performant

La priorisation par phases permet un développement itératif avec des valeur livrables dès la Phase 1.

---

**Document Status** : ✅ Draft v1.0 - Ready for Review
**Next Steps** : Validation avec Ramez, puis implémentation Phase 1

---

*Generated by Sally (UX Designer) & Ramez - Keep Project*
*Date: 2026-01-10*