epic(ux): mode débutant / expert global (progressive disclosure)

[bmatge]

Audit UX 2026-05-26 — la recommandation transverse T-2 propose un toggle « Mode débutant / Mode expert » global qui résoudrait structurellement l'écart entre les deux personas. Epic structurant : pose la grille commune pour tous les futurs masquages « trop technique pour P1 », et conditionne plusieurs issues des autres epics (notamment EPIC 2 — masquage Méthode HTTP / En-têtes / Chemin en mode débutant, et EPIC 4 — constructeur visuel forcé en mode débutant).

La décision technique est posée dans ADR-027 — Mode débutant / expert global (UX progressive disclosure) (statut accepted, 2026-05-27) :

• Périmètre : 4 cibles — apps/sources, apps/builder, apps/dashboard, guide/
• Persistance : localStorage + sync DB (pattern tour_state v6 ; nouvelle migration v7, endpoint /api/expertise-mode)
• API : event bus + helpers TS dans @dsfr-data/shared/ui/expertise-mode.ts, + document.body.dataset.expertise pour les masquages CSS purs
• Défaut au 1er accès : bannière onboarding DSFR fr-notice (« [Mode guidé (recommandé)] [Mode avancé] »)
• Naming UX : « Mode guidé » / « Mode avancé » (beginner / expert côté code)
• Mode avancé : wording « libellé naturel (libellé technique) »
• Discoverability : liens contextuels « Mode avancé pour voir les options de … » à côté des sections masquées

Findings couverts (rapport d'audit)

• T-2 (transverse) — Adopter une stratégie de progressive disclosure « Débutant / Avancé » globale
• M-B-6 — Builder : toutes les sections collapsibles sont fermées par défaut (ouvrir auto la section suivante quand la précédente est complétée)

Sous-issues

(liens ajoutés après création des enfants)

Critères d'acceptation

• Module packages/shared/src/ui/expertise-mode.ts exporte getMode(), setMode(mode), onChange(callback), met à jour document.body.dataset.expertise.
• Composant <expertise-toggle> Web Component placé dans le header DSFR via app-header.ts.
• Migration DB v7 + colonne users.expertise_mode VARCHAR(10), endpoint GET/PUT /api/expertise-mode, sync identique au pattern tour_state.
• Bannière onboarding fr-notice au tout 1er accès (détectée par localStorage.getItem('dsfr-data:expertise-mode') === null), choix mémorisé après le 1ᵉʳ clic.
• En mode guidé : Sources masque Méthode HTTP / En-têtes / Chemin ; Builder masque DataBox, Normalisation, Facettes, Mode de génération ; tous les liens contextuels « Mode avancé pour voir … » présents.
• Auto-ouverture de la section suivante du Builder dès que la précédente est complétée (couvre M-B-6).
• Pour les utilisateurs déjà actifs au déploiement : mode initial = expert (zéro régression).

Référence

• ADR : ~/Documents/Obsidian/30-Knowledge/ADR/ADR-027-mode-debutant-expert-global-ux-progressive-disclosure.md
• Rapport d'audit : audit-ui-2026-05-26/rapport-audit-ux.md §T-2, §M-B-6
• Plan epic/issues : ~/.claude/plans/je-veux-que-tu-vectorized-raven.md EPIC 6
• Pattern de référence : users.tour_state (migration v6, endpoint /api/tour-state)

[bmatge]

Sous-issues

• feat(shared): module expertise-mode (event bus + persistance + composant toggle) [ADR-027] #203 — feat(shared): module expertise-mode (event bus + persistance + composant toggle) [ADR-027] ← bloquant pour 6.2, 6.3
• feat(sources): appliquer mode débutant — masquer Méthode HTTP/En-têtes/Chemin [ADR-027] #204 — feat(sources): appliquer mode débutant — masquer Méthode HTTP/En-têtes/Chemin [ADR-027]
• feat(builder): appliquer mode débutant — masquer DataBox, Normalisation, Facettes, Mode de génération [ADR-027] #205 — feat(builder): appliquer mode débutant — masquer DataBox, Normalisation, Facettes, Mode de génération [ADR-027]
• feat(builder): auto-ouverture de la section suivante quand la précédente est complétée [M-B-6] #206 — feat(builder): auto-ouverture de la section suivante quand la précédente est complétée [M-B-6]

Ordre de livraison recommandé : #203 d'abord, puis #204 / #205 / #206 en parallèle.
Lien fort avec EPIC 2 (#195, #196, #197 — wording préalable) et EPIC 4 (#200 — constructeur visuel forcé en mode guidé).

[bmatge]

🅿️ PARKED — User testing required first

Décision prise en fin de session 2026-05-27 : le chantier « mode débutant / expert global » est trop structurant pour être lancé sans vrai test utilisateur avec des personas réels (P1 contributrice non-tech / P2 data analyst). L'approche actuelle de l'audit est uniquement la perspective de l'auditeur (le sub-agent ui-auditor) qui se met dans la peau des personas — mais ce n'est pas un test terrain.

Sous-issues fermées not planned

• feat(shared): module expertise-mode (event bus + persistance + composant toggle) [ADR-027] #203 module expertise-mode (event bus + migration DB v7 + endpoint + composant toggle)
• feat(sources): appliquer mode débutant — masquer Méthode HTTP/En-têtes/Chemin [ADR-027] #204 Sources apply mode débutant (masquer Méthode HTTP / En-têtes / Chemin)
• feat(builder): appliquer mode débutant — masquer DataBox, Normalisation, Facettes, Mode de génération [ADR-027] #205 Builder apply mode débutant (masquer DataBox / Normalisation / Facettes / Mode de génération)

Sous-issue détachée (gardée indépendamment)

• feat(builder): auto-ouverture de la section suivante quand la précédente est complétée [M-B-6] #206 M-B-6 auto-ouverture section suivante — indépendant du mode débutant/expert, peut vivre seul comme petit progressive disclosure

Pour le futur

Avant de réouvrir ce chantier :

1. Faire passer 3-5 utilisateurs P1 (contributeurs non-tech) ET 3-5 P2 (data analysts) sur l'app dans son état actuel post-audit (les 7 PRs UX livrées en session 2026-05-27).
2. Observer où ils décrochent, ce qu'ils cherchent, ce qu'ils ignorent.
3. Reformuler la décision UX progressive disclosure à la lumière de ces observations. Peut-être que la cible n'est pas « 2 modes globaux » mais une autre approche (presets, onboarding contextuel, parcours guidés, etc.).

L'ADR [[ADR-027-mode-debutant-expert-global-ux-progressive-disclosure|ADR-027]] reste accepted comme proposition technique mais sa mise en œuvre est suspendue à ce feedback utilisateur. Si l'approche change radicalement, l'ADR sera superseded par une nouvelle.

Statut : OPEN avec label status:parked — ne pas confondre avec « actif ».