J'ai été des deux côtés du handoff pendant plus de dix ans. J'ai écrit des briefs en tant que designer et je les ai reçus en tant que développeur. L'écart entre ce que la plupart des designers écrivent et ce dont les développeurs ont besoin pour construire correctement n'est pas causé par le fait que les développeurs ne se soucient pas du design. Le brief est optimisé pour le mauvais lecteur.
À quoi un brief sert réellement
Un brief existe pour donner à un développeur tout ce dont il a besoin pour implémenter la fonctionnalité correctement sans planifier une réunion de suivi. Chaque section qui ne sert pas cet objectif est du bruit qui réduit la probabilité que le développeur lise le document. J'ai arrêté d'assister aux handoffs de revue de design qui étaient vraiment des vitrines du processus de design. Ceux pour lesquels je bloquais du temps étaient ceux où l'auteur avait clairement réfléchi à ce dont j'aurais besoin pour ne pas revenir avec des questions.
Les cinq sections qui comptent
- 1. Spec de comportement : ce qui se passe quand l'utilisateur fait X. Pas à quoi ça ressemble. Ce que ça fait. Couvrir chaque état interactif : hover, focus, active, disabled, loading.
- 2. Cas limites et états d'erreur : états vides, états de chargement, états d'erreur API, messages de validation. Ce sont les parties que les développeurs inventeront si vous ne les spécifiez pas. Des états inventés sont des états incohérents.
- 3. Comportement responsive : breakpoints exacts, quels changements de layout à chaque breakpoint, quels éléments se réordonnent ou se replient. Pas 'mobile-friendly.' Spécifique.
- 4. Inventaire de composants : quels composants existants sont utilisés, lesquels sont nouveaux, noms exacts de composants Figma qui correspondent aux noms de composants Angular.
- 5. Hors scope : lister explicitement ce qui N'EST PAS dans cette implémentation. Ça prévient le scope creep et crée un enregistrement partagé pour les décisions futures.
Les états d'erreur sont non négociables dans les produits financiers
Dans un produit financier, les messages d'erreur ne sont pas du polish UX. Un message d'échec de paiement trop vague se transforme en appel au support plutôt qu'en nouvelle tentative. Un avertissement de découvert ambigu crée du volume au centre d'appels. Quand je dirigeais l'UX de la PWA de carte de crédit chez Wonderlabs, je spécifiais chaque état d'erreur, le texte exact et la condition de déclenchement, et j'ai fait la même chose sur la refonte de la plateforme IRIS chez Strongest Families, où les enjeux étaient différents mais la discipline identique. Si le brief n'a pas ce tableau, l'implémentation aura des messages d'erreur inventés. Le tableau ci-dessous est écrit pour cet article. C'est une illustration, pas une spec d'un produit sur lequel j'ai travaillé.
## Error States: Transfer Form (illustrative)
| State | Trigger | Message | Component |
|-------|---------|---------|----------|
| Required field empty | Submit with empty field | "This field is required" | FormFieldError |
| Amount exceeds balance | amount > accountBalance | "Insufficient funds. Your available balance is $X.XX" | FormFieldError |
| API timeout | Response > 30s | "Something went wrong. Please try again." | InlineAlert (warning) |
| Daily limit exceeded | amount > dailyTransferLimit | "You've reached your daily transfer limit of $X,XXX" | InlineAlert (warning) |
| Invalid recipient account | 422 from API | "We couldn't find an account with that number. Check the details and try again." | FormFieldError |Le comportement responsive nécessite des spécificités
Dire 'mobile-friendly' dans un brief n'est pas une spécification. Spécifiez les breakpoints pour lesquels vous designez. Assurez-vous qu'ils correspondent aux breakpoints définis dans vos design tokens. Documentez quels changements de layout se produisent à chacun et quelles interactions changent. Une barre latérale qui se replie en un bottom sheet à 768px doit être écrite noir sur blanc, pas visible dans les frames Figma seulement si on sait où regarder. Un développeur travaillant à partir d'un brief ne devrait pas avoir à rétro-ingénierer le comportement responsive à partir de comparaisons de frames.
Voici à quoi ça ressemble pour un exemple inventé, une carte de résumé de relevé dans une application de carte de crédit. Aucune des valeurs ci-dessous ne vient d'un produit réel. À 1280px et au-dessus, la carte s'affiche dans une grille à deux colonnes avec les détails du compte à gauche et les boutons d'action empilés à droite. En dessous de 1280px, le layout passe en colonne unique : les boutons d'action passent sous les détails, et la carte va bord à bord avec 16px de padding horizontal. À 375px et en dessous, la carte supprime entièrement l'action secondaire. Le lien 'Voir l'historique' est masqué et accessible uniquement via la page de détail du compte. Cette décision doit être dans le brief. Un développeur qui ne la voit pas va soit afficher le lien quand même et casser le layout, soit le supprimer globalement et casser le desktop.
## Responsive Behavior: Statement Summary Card (illustrative)
| Breakpoint | Layout | Changes |
|------------|--------|---------|
| >= 1280px | 2-column grid | Account details left, actions right |
| 376px to 1279px | 1-column stack | Actions move below details, edge-to-edge card, 16px horizontal padding |
| <= 375px | 1-column, reduced | Hide 'View history' link |Nommage de composants qui fait le pont entre les deux mondes
Je pousse pour aligner les noms de composants Figma avec les noms de composants Angular avant qu'un brief soit écrit. Si le composant Figma s'appelle 'Pill/Status/Success' et le composant Angular est StatusBadge, chaque brief qui référence ce composant crée un problème de traduction. Un nommage incohérent se compose à travers une équipe jusqu'à ce que les handoffs nécessitent un glossaire.
La convention que j'utilise : PascalCase, nom en premier, spécifique plutôt que générique. Pas 'Card' quand 'StatementSummaryCard' est ce que vous voulez dire. Pas 'Dialog' quand 'ConfirmTransferDialog' est ce que vous voulez dire. Des noms génériques dans Figma deviennent des références ambiguës dans les briefs deviennent des mauvais choix de composants dans Angular. La session d'alignement du nommage, c'est une seule réunion. Elle se rentabilise la première fois qu'un brief nomme un composant et que personne n'a à demander lequel c'est.
Un brief n'est pas terminé quand tous les chemins heureux sont documentés. Il est terminé quand chaque état qu'un utilisateur pourrait rencontrer a un comportement spécifié.
Le format compte plus que vous ne le pensez
Gardez le brief court. Utilisez des tableaux pour les états. Utilisez des liens Figma annotés qui vont directement au frame pertinent, pas à la racine du fichier. Si le document fait plus de quatre pages, vous avez probablement inclus des choses qui devraient être dans le ticket Jira ou l'archive de design. Les développeurs ont du contexte venant de la planification et du refinement des stories. Le brief comble les lacunes d'implémentation dans ce contexte. Il ne remplace pas tous les autres documents.
Un lien Figma qui pointe vers la racine du fichier force le développeur à naviguer au bon frame lui-même. Sur un gros fichier, c'est un détour, et il se produit à chaque fois qu'il cross-référence le brief. Liez directement au frame. Utilisez le 'Copy link to selection' de Figma (clic droit sur le frame, puis Copy/Paste as) sur chaque frame que vous référencez. Si vous référencez un variant de composant spécifique, sélectionnez ce variant et copiez son lien. Ça vous coûte quelques secondes par lien. Ça économise au développeur des minutes par session et supprime la friction ambiante qui fait que les gens arrêtent d'ouvrir le brief.
Les briefs qui sont lus sont ceux qui traitent le temps du développeur comme précieux. Courts, structurés, complets sur les états et le comportement, avec des liens Figma directs. Ceux qui ne sont pas lus sont ceux qui documentent le processus de réflexion du design pour un public qui n'était pas dans la revue de design. Connaissez votre lecteur.
Voici la différence en une seule vue. Les noms de composants et d'endpoints ci-dessous sont inventés pour cet article.
Références
- Figma developer handoff guide. https://www.figma.com/best-practices/guide-to-developer-handoff/
- WCAG 2.2 Understanding SC 3.3.1 Error Identification. https://www.w3.org/WAI/WCAG22/Understanding/error-identification.html
- WCAG 2.2 Understanding SC 3.3.3 Error Suggestion. https://www.w3.org/WAI/WCAG22/Understanding/error-suggestion.html