Spécifier l'interface : maquettes annotées, user stories et critères d'acceptation

Spécifier l'interface, c'est décrire les écrans de façon assez précise pour que le développeur sache quoi coder, le testeur quoi vérifier et le client quoi valider : exigences ergonomiques vérifiables, maquettes annotées avec leurs données, leurs règles, leurs comportements et leurs états, user stories accompagnées de critères d'acceptation qui couvrent aussi l'ergonomie. Ce chapitre montre comment écrire chacun de ces éléments pour Prêt'Matos, comment les relier entre eux et comment faire valider l'interface.

La partie interface d'un cahier des charges

Le cahier des charges décrit le besoin et ses contraintes. Sa partie consacrée à l'interface contient, selon la taille du projet, tout ou partie des éléments suivants :

Dans un projet agile comme Prêt'Matos, ces éléments ne sont pas tous écrits d'avance : les exigences générales et l'arborescence le sont au début, les maquettes et les critères d'acceptation de chaque écran juste avant le sprint où il sera développé.

Écrire des exigences ergonomiques vérifiables

« Intuitive », « ergonomique », « moderne », « accessible » : ces mots expriment une attente, mais personne ne peut dire à la recette s'ils sont respectés. Une exigence ergonomique utile précise qui, quoi, dans quelles conditions et comment on le vérifie (écrire une exigence vérifiable).

La maquette annotée

Une maquette montre un état de l'écran à un instant. Pour qu'elle serve de spécification, on l'annote : des repères numérotés sur l'écran, et dans la marge, ce que l'image ne dit pas.

Une annotation précise vaut mieux qu'une maquette de plus. « Les réservations sont triées par date » laisse deux questions : laquelle (retrait ou retour) et dans quel sens ? « Tri par date de retrait croissante » n'en laisse aucune.

Les états d'un écran

Un écran qui affiche des données n'a pas un seul aspect. Les maquettes oublient souvent ses autres états, et le développeur les invente alors en dernière minute, ou pas du tout : un écran blanc pendant le chargement, une liste vide sans explication, une erreur muette.

Les formulaires ont aussi leurs états (vierge, en cours de saisie, en erreur, en cours d'envoi, envoyé) et chaque composant les siens (normal, survolé, focus, désactivé). Le design system les décrit une fois pour toutes ; la maquette de chaque écran ne dessine que ceux qui lui sont propres.

User stories et critères d'acceptation qui vérifient l'ergonomie

Une user story dit ce que veut l'utilisateur ; ses critères d'acceptation disent quand elle est terminée. Pour que l'ergonomie soit vérifiée, elle doit figurer dans ces critères : le message exact, l'emplacement du focus, l'état après l'action, le comportement au clavier. Voici la story 6 de Prêt'Matos, « En tant que salarié, je veux voir et annuler mes réservations afin de libérer le matériel quand je n'en ai plus besoin », au format Étant donné / Quand / Alors :

# language: fr
Fonctionnalité: Annuler une réservation

  Scénario: Annuler une réservation à venir
    Étant donné que Julie a réservé VP-01 du 24 au 26 mars 2027
    Et que nous sommes le 15 mars 2027
    Quand Julie choisit « Annuler » sur cette réservation dans « Mes réservations »
    Alors une confirmation affiche « Annuler la réservation de VP-01 du 24/03 au 26/03 ? »
    Et elle propose les boutons « Annuler la réservation » et « Garder la réservation »

  Scénario: Confirmer l'annulation
    Étant donné que la confirmation d'annulation de VP-01 est affichée
    Quand Julie choisit « Annuler la réservation »
    Alors la réservation disparaît du groupe « À venir »
    Et le message « Réservation de VP-01 du 24/03 annulée. » s'affiche et est annoncé aux lecteurs d'écran
    Et VP-01 apparaît disponible du 24 au 26 mars dans le catalogue

  Scénario: Renoncer à l'annulation au clavier
    Étant donné que la confirmation d'annulation de VP-01 est affichée
    Quand Julie appuie sur la touche Échap
    Alors la confirmation se ferme et la réservation est conservée
    Et le focus revient sur le bouton « Annuler » de cette réservation

  Scénario: Une réservation commencée ne s'annule pas
    Étant donné que Julie a retiré PC-07 le 12 mars 2027
    Quand elle affiche « Mes réservations » le 15 mars 2027
    Alors PC-07 apparaît dans le groupe « En cours » avec la mention « À rendre le 18/03 »
    Et aucune action « Annuler » n'est proposée pour PC-07

Ces scénarios servent trois fois : ils lèvent les ambiguïtés avant le développement (que devient le focus ? que dit le message ?), ils deviennent les cas du cahier de recette, et ils peuvent être automatisés dans un test de bout en bout (Playwright). L'anomalie A-03 de la recette de Prêt'Matos, une réservation refusée sans message, n'aurait pas passé la revue si le critère d'acceptation avait donné le message exact.

La Definition of Done de l'équipe, commune à toutes les stories, ajoute les vérifications d'ergonomie qui valent partout :

• l'écran correspond à la maquette validée, avec tous ses états ;
• les textes sont ceux de la liste des messages, sans faute ;
• tout se fait au clavier, avec un focus visible ;
• l'écran a été vérifié à 360 pixels de large et avec un zoom à 200 % ;
• les contrastes des nouveaux éléments ont été mesurés ;
• l'outil automatique d'accessibilité ne signale aucune erreur.

Relier exigences, maquettes, stories, cas d'utilisation et tests

Chaque élément de la spécification doit pouvoir être relié aux autres : c'est la traçabilité. Elle permet de vérifier qu'aucune exigence n'est oubliée et de savoir quoi retester quand un écran change.

Le diagramme de cas d'utilisation et sa description textuelle disent ce que le système fait pour chaque acteur ; les maquettes disent comment l'acteur le fait à l'écran ; les critères d'acceptation disent comment on le vérifie. Les trois se répondent : un scénario d'erreur de la description textuelle (« le matériel est déjà réservé ») doit avoir son message sur la maquette et son critère d'acceptation.

Faire valider l'interface

La validation se fait en deux temps.

Avant le développement, la Product Owner (ou le client) valide les maquettes et les critères d'acceptation. Présente-les par tâche, note les remarques, fais une nouvelle version et obtiens un accord explicite, daté : un courriel, un commentaire dans l'outil de maquettage, une ligne dans le compte rendu de réunion. C'est la version de référence.

Après le développement, la recette vérifie que l'application est conforme : chaque critère d'acceptation est rejoué, les exigences ergonomiques sont mesurées (le test chronométré de l'ENF-05, l'audit de l'ENF-06). Les écarts deviennent des anomalies, avec leur gravité.

Exercices

# language: fr
Fonctionnalité: Enregistrer un retour par scan

  Scénario: Le matériel scanné est en prêt
    Étant donné que PC-07 est en prêt chez Julie depuis le 12 mars 2027
    Et que l'écran « Enregistrer un retour » est affiché
    Quand Noah scanne l'étiquette de PC-07
    Alors l'écran affiche « PC-07, prêté à Julie Lefèvre depuis le 12/03 »
    Et la date de retour est pré-remplie avec la date du jour
    Et le choix de l'état « Bon état » est proposé par défaut

  Scénario: Le matériel scanné n'est pas en prêt
    Étant donné que VP-01 n'est pas en prêt
    Quand Noah scanne l'étiquette de VP-01
    Alors le message « VP-01 n'est pas en prêt : vérifiez l'étiquette ou cherchez le matériel par son numéro. » s'affiche
    Et le champ de recherche reçoit le focus
    Et aucun retour n'est enregistré