Form Designer — Maquettes UX

Rappel ADR-007 : le Form Designer est un must au MVP — exigence commerciale bloquante pour le marché tunisien et plus largement MENA.

Ce document fige les parcours utilisateurs et les wireframes de référence pour l’équipe d’ingénierie et de design. Les mockups sont donnés en ASCII + SVG inline : à traduire en Figma haute fidélité au kickoff, sans déformer la structure.

---

1. Personas et parcours

1.1 Acteurs

Persona	Rôle	Usage Form Designer
Admin tenant (DSI banque)	Gouvernance	Valide, publie, gère les versions
Intégrateur CSM VitaKYC	Mise en place	Construit les premiers formulaires
Compliance officer banque	Conformité	Revue des champs obligatoires (KYC, FATCA indicia)
Client final	Runtime	Remplit le formulaire généré (mobile / desktop)

1.2 Deux surfaces UX

---

2. Back-office — architecture de la page

2.1 Vue globale de l’éditeur

┌──────────────────────────────────────────────────────────────────────────────────┐
│ VitaKYC · Form Designer          [Version 2.1 · Draft]     [👁 Preview]  [🚀 Publier]│
├──────────────────────────────────────────────────────────────────────────────────┤
│ ┌─────────────┐  ┌──────────────────────────────────────┐  ┌──────────────────┐ │
│ │   PALETTE   │  │             CANVAS (canvas)          │  │   PROPRIÉTÉS     │ │
│ │             │  │                                      │  │                  │ │
│ │ Texte       │  │ ┌─ Étape 1 · Identité ────────────┐  │  │ Champ sélectionné│ │
│ │ Nombre      │  │ │                                 │  │  │                  │ │
│ │ Date        │  │ │  [Texte] Prénom           *     │  │  │ Libellé (FR)     │ │
│ │ Date nais.  │  │ │  [Texte] Nom              *     │  │  │ [Prénom________] │ │
│ │ Email       │  │ │  [Date naiss.] Naissance  *     │  │  │                  │ │
│ │ Téléphone   │  │ │  [Drop] Nationalité       *     │  │  │ Libellé (AR)     │ │
│ │ Dropdown    │  │ │                                 │  │  │ [الاسم_________] │ │
│ │ Radio       │  │ └─────────────────────────────────┘  │  │                  │ │
│ │ Checkbox    │  │                                      │  │ Libellé (EN)     │ │
│ │ Fichier     │  │ ┌─ Étape 2 · Document identité ──┐  │  │ [First name____] │ │
│ │ Doc. KYC    │  │ │                                 │  │  │                  │ │
│ │ Selfie      │  │ │  [Doc KYC] Passeport/CNI  *     │  │  │ Obligatoire  [x] │ │
│ │ Signature   │  │ │  [Dropdown] Pays émission *     │  │  │ Visible si...    │ │
│ │ Consent.    │  │ │                                 │  │  │ [Règle de visibil│ │
│ │ Indicia US  │  │ └─────────────────────────────────┘  │  │  ité simple....] │ │
│ │             │  │                                      │  │                  │ │
│ │ + Custom    │  │ [ + Ajouter une étape ]              │  │ Validation        │ │
│ │             │  │                                      │  │ - Min length: 2   │ │
│ └─────────────┘  └──────────────────────────────────────┘  │ - Regex: [A-Za-z] │ │
│                                                             │                  │ │
│                                                             └──────────────────┘ │
└──────────────────────────────────────────────────────────────────────────────────┘
 Tabs : [Champs]  [Règles]  [Étapes]  [Branding]  [Traductions]  [Historique]

Zones :

• Palette (gauche, 220 px) : catalogue de champs drag-drop, groupes repliables (Identité, Adresse, Documents, Consentement, Indicia FATCA, Custom).
• Canvas (centre, fluide) : zone d’édition WYSIWYG, rendu fidèle à l’aperçu mobile/web.
• Propriétés (droite, 320 px) : panneau contextuel du champ sélectionné.
• Barre supérieure : identité du formulaire, version en édition, CTA Preview / Publier.
• Onglets : basculement entre Champs, Règles globales, Étapes, Branding, Traductions, Historique.

2.2 Palette — groupes de champs standards

Groupe	Champs
Identité	Texte, Texte long, Nombre, Date, Date de naissance, Nationalité (dropdown ISO 3166), Pays (dropdown), Genre (radio)
Coordonnées	Email, Téléphone (avec indicatif), Adresse structurée, Code postal
Documents & biométrie	Document KYC (auto-route OCR), Selfie (auto-route liveness + face match), Justificatif domicile, Upload fichier générique
Conformité	Consentement (horodaté), Indicia FATCA (US birth / US address / US phone / US signatory / US joint account / Standing instructions US), PEP auto-déclaration, Source de fonds
Choix	Dropdown, Radio, Checkbox, Boutons toggle
Signature	Signature (canvas + e-signature W-8/W-9 via provider)
Custom	Champ libre défini par le tenant (type + règle)

2.3 Panneau Propriétés — détail

• Libellés par langue : champs séparés FR / AR / EN, indicateur visuel si une traduction manque (icône ⚠).
• Validation : constructeur visuel (ex : age >= 18 via 2 dropdowns + input), pas de DSL brut pour l’admin lambda, mais l’expression DSL est visible en bas (« mode avancé »).
• Mapping KYC : chaque champ doit être mappé à une propriété canonique VitaKYC (ex : first_name, last_name, dob, nationality, us_person_indicator) pour pipeline downstream (OCR, AML, TCR). Le designer refuse la publication si un champ non mappé n’est pas de type « Custom ».

2.4 Onglet Règles — orchestration conditionnelle

┌──────────────────────────────────────────────────────────┐
│ Règles du formulaire · 4 règles définies                 │
├──────────────────────────────────────────────────────────┤
│                                                          │
│ R1 · Afficher « Justificatif US »                        │
│       SI  us_birth == true  OU  us_address == true       │
│       ALORS  visible = true                              │
│       SINON  visible = false                             │
│ [✏ Éditer]  [🗑 Supprimer]                                │
│                                                          │
│ R2 · Étape optionnelle « Source des fonds »              │
│       SI  montant_operation > 10 000 TND                 │
│       ALORS  étape_source_fonds = required               │
│ [✏ Éditer]  [🗑 Supprimer]                                │
│                                                          │
│ R3 · Passer directement à étape 4                        │
│       SI  type_client == "entreprise"                    │
│       ALORS  skip_steps = [2, 3]                         │
│ [✏ Éditer]  [🗑 Supprimer]                                │
│                                                          │
│ R4 · Bloquer soumission                                  │
│       SI  age < 18  ALORS  block = true                  │
│       message = "Client mineur non éligible"             │
│                                                          │
│ [ + Ajouter une règle ]                                  │
└──────────────────────────────────────────────────────────┘

Règles simples : champ OP valeur (OP ∈ ==, !=, <, >, <=, >=, in, contains, matches) combinables par ET / OU. Actions : visible, required, skip_step, block, prefill.

2.5 Onglet Étapes — structure séquentielle

Vue pipeline des étapes, réordonnables (drag handle). Chaque étape a :

• Un titre (FR / AR / EN).
• Un statut : requis / optionnel / conditionnel.
• Une condition de visibilité (lien avec onglet Règles).
• Un compteur de champs.
• Un indicateur de couverture traductions (FR ✓ / AR ✓ / EN ⚠).

2.6 Onglet Branding

• Logo (upload SVG / PNG transparent ≥ 200×60 px).
• Couleur primaire + couleur d’accent (palette HSL).
• Police (Inter par défaut, IBM Plex Sans Arabic pour arabe).
• Prévisualisation temps réel.
• Domaine white-label : kyc.{client}.{domaine}.
• Email de support affiché en fin de parcours.

2.7 Onglet Traductions

Table compacte :

Clé	FR	AR	EN	Statut
step_1_title	Identité	الهوية	Identity	✅
field_dob_label	Date de naissance	تاريخ الميلاد	Date of birth	✅
field_us_birth_label	Lieu de naissance aux États-Unis ?	—	Born in the United States?	⚠ AR manquante
error_required	Champ obligatoire	حقل إلزامي	Required field	✅

Bouton Export CSV / Import CSV pour traducteurs externes. Bouton Traduction IA (optionnel) avec drapeau « à réviser ».

2.8 Onglet Historique

Version 2.1 · Draft    (en cours)         [👁 voir] [📝 continuer]
Version 2.0 · Published · 14 jours        [👁] [⏮ restaurer] [📊 stats]
Version 1.5 · Published · 42 jours        [👁] [⏮]
Version 1.4 · Archived · 3 mois           [👁]
Version 1.0 · Archived · 5 mois           [👁]

Chaque version conserve : auteur, date, diff par rapport à la précédente (ajout/suppression/modif de champs, règles, libellés), % de champs traduits par langue, nb de soumissions en prod si publiée.

---

3. Preview — aperçu multi-device

┌─────────────────────────────────────────────────────────────────┐
│ Preview Form · Version 2.1-draft         [📱 Mobile] [💻 Desktop]│
│                                           [🌐 FR]  [🌐 AR]  [🌐 EN]│
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│          ┌─ Mobile 390 px ──┐   ┌─ Desktop 1280 px ─────────┐   │
│          │ ● ● ●            │   │                           │   │
│          │                  │   │  Formulaire affiché       │   │
│          │  Bonjour 👋       │   │  identique, largeur       │   │
│          │  Étape 1/4       │   │  maximale 720 px          │   │
│          │                  │   │                           │   │
│          │  Prénom          │   │  [Prénom_______________]  │   │
│          │  [______________]│   │  [Nom__________________]  │   │
│          │                  │   │  ...                      │   │
│          │  Nom             │   │                           │   │
│          │  [______________]│   │  [ Continuer → ]          │   │
│          │                  │   │                           │   │
│          │  [ Suivant ]     │   │                           │   │
│          └──────────────────┘   └───────────────────────────┘   │
│                                                                  │
│  ℹ La preview n'envoie rien ; elle joue les règles localement.  │
└─────────────────────────────────────────────────────────────────┘

En mode Arabe RTL, le layout est miroir natif :

• Labels à droite, champs à gauche.
• Icônes de flèches inversées (suivant vers la gauche).
• Nombres peuvent s’afficher en chiffres arabes ou hindi selon la préférence tenant.

---

4. Workflow de publication

Un formulaire ne peut pas être publié sans :

1. Un mapping KYC défini pour chaque champ non custom.
2. Les traductions FR + AR + EN complètes pour chaque libellé et message d’erreur (sauf si la langue est désactivée par le tenant).
3. Un consentement GDPR/LCB-FT explicite en dernière étape (horodatage + hash).
4. Une signature (si exigée par le segment client).

---

5. Runtime — rendu côté client (SDK Web)

5.1 Écran client mobile type

┌──────────────────────┐
│  🏦  Banque Exemple  │   ← logo tenant (branding)
│                       │
│  ●●●○  Étape 2/4     │   ← progress bar
│                       │
│  Document d'identité  │   ← titre étape (FR/AR/EN)
│                       │
│  Prenez en photo      │
│  le recto de votre    │
│  pièce d'identité     │
│                       │
│  ┌─────────────────┐  │
│  │                 │  │   ← zone de capture
│  │  📷  TAP        │  │
│  │                 │  │
│  └─────────────────┘  │
│                       │
│  [ Retour ] [ Suivant]│
│                       │
│  🔒 VitaKYC           │   ← footer VitaKYC ou blanc
└──────────────────────┘

5.2 Intégration par le tenant

<!-- Embed 1-liner -->
<vitakyc-form
  api-key="pk_live_abc"
  form-id="fr-retail-2025"
  locale="fr"
  external-ref="CLIENT-42"
  on-complete="handleComplete">
</vitakyc-form>

<script src="https://cdn.vitakyc.io/sdk/v1/vitakyc-sdk.js"></script>

Le SDK :

• Charge la définition JSONB de la version active via GET /v1/forms/:id/active.
• Rend dynamiquement l’UI (React Shadow DOM pour isolation CSS).
• Évalue les règles en local (même DSL que le designer).
• Upload chaque document au fil du parcours (pas d’attente finale).
• Déclenche les briques biométriques (liveness, face match) selon les étapes.
• Émet des événements JS (onStepChange, onSuccess, onError, onCancel).
• En déconnexion, sauvegarde l’état local (IndexedDB) et reprend à la reconnexion.

5.3 Support RTL arabe

• Détection automatique via locale="ar" ou <html dir="rtl">.
• CSS logique (margin-inline-start, padding-inline-end) au lieu de left/right.
• Icônes directionnelles miroirées (flèches, chevrons).
• Nombres : Latin par défaut, option chiffres arabes indo-arabes (٠-٩) pour tenants Golfe / Égypte.
• Calendrier Hijri en option pour les sélecteurs de date (inutilisé en KYC en général, mais disponible pour formulaires produits).

---

6. Données — schéma stocké

Référence architecture technique §5.2 — tables supplémentaires :

table: form_definition
  form_id            UUID PK
  tenant_id          UUID FK
  code               VARCHAR(64)  -- ex: 'fr-retail-2025'
  name               VARCHAR(255)
  description        TEXT
  status             ENUM('draft','published','archived')
  created_by, created_at

table: form_version
  version_id         UUID PK
  form_id            UUID FK
  version_no         VARCHAR(16)  -- "2.1"
  schema             JSONB        -- {steps:[{fields:[...]}], rules:[...], branding:{}}
  translations       JSONB        -- {fr:{...}, ar:{...}, en:{...}}
  mapping            JSONB        -- {first_name:"step1.field2", ...}
  published_at       TIMESTAMPTZ
  published_by       UUID FK user
  is_active          BOOLEAN

table: form_submission
  submission_id      UUID PK
  tenant_id          UUID FK
  form_version_id    UUID FK
  case_id            UUID FK kyc_case
  data               JSONB        -- valeurs saisies (PII chiffrées via envelope)
  locale             CHAR(5)      -- ex: 'ar-TN'
  device             JSONB        -- user-agent, screen, network
  submitted_at

---

7. Métriques et analytics

• Drop-off par étape : barre horizontale par étape montrant le % qui n’a pas continué.
• Temps médian par champ : identifie les champs qui frictionnent.
• Taux d’erreurs de validation par champ : flag les règles mal formulées.
• Conversion par langue : comparer FR / AR / EN.
• A/B testing (V1) : deux versions publiées simultanément, répartition configurable, KPI auto.

---

8. Accessibilité (WCAG 2.1 AA)

• Navigation clavier complète (Tab, Enter, Escape).
• Focus visible (outline custom 2 px couleur d’accent).
• Labels liés à leurs inputs (aria-labelledby).
• Messages d’erreur en aria-live="polite".
• Contraste ≥ 4,5:1 (texte) et 3:1 (icônes et UI).
• Testé avec NVDA (Windows) + VoiceOver (iOS).

---

9. Checklist de mise en œuvre MVP

• Palette de 15 types de champs standards + groupe Custom
• Canvas drag-drop (React DnD)
• Panneau propriétés contextuel
• Constructeur de règles visuel (5-8 opérateurs, actions visible/required/skip/block)
• Traductions FR / AR / EN + RTL preview
• 5 templates pré-livrés (banque retail MENA, fintech wallet, crédit/leasing, assurance, crypto)
• Versioning + publish workflow avec validation bloquante
• SDK Web qui consomme la définition JSONB et s’adapte
• Analytics drop-off de base (4 KPI)
• A/B testing reporté à V1

---

10. Livrables design

Pour l’équipe design (Figma) :

1. Design system VitaKYC : tokens (couleurs, typo, espacements), composants de base (Button, Input, Select, Stepper, Toast), variants sombre/clair.
2. Back-office Designer : 24 écrans key frames (éditeur, règles, étapes, branding, traductions, preview, publish modal, historique).
3. Runtime client : 18 écrans (accueil, étape générique, capture doc, selfie, entretien, récap, succès, erreurs).
4. Composants RTL : version miroir des écrans clés.
5. Guide styles pour intégration tenant (branding vars).
6. Prototype cliquable Figma pour démo prospects.

---

Document de référence pour la V0 MVP. À enrichir avec les captures Figma au fur et à mesure du design.