Les composants sont un contrat : le développement Laravel fait correctement

À partir du moment où un deuxième ingénieur touche à un composant, chaque hypothèse implicite devient un bug en attente de se produire. J'ai appris cela tôt dans le travail sur Production Design System, où la première équipe avait construit quelque chose de visuellement cohérent mais non documenté. La troisième équipe l'a hérité et l'a cassé en une semaine. Ce schéma se répète partout. Ce n'est pas un problème de personnes. C'est un problème de contrat. Le développement Laravel, quand il touche à une couche de composants, a le même mode de défaillance : rapide à écrire, fragile à transmettre.

Un composant est une promesse, pas un morceau de code

Quand je dis contrat, je le pense précisément. Un composant expose une surface : props, slots, événements, références de tokens. Chaque consommateur de ce composant dépend de la stabilité de cette surface. La modifier discrètement et vous cassez les choses en aval d'une manière qui ne s'affiche pas toujours dans les tests. La spécification du W3C Design Tokens Community Group, qui est devenue le format de contrat standard en 2025, a formalisé quelque chose que les praticiens faisaient informellement depuis des années : séparer la couche de tokens de la couche de composants afin que les deux puissent être versionnées indépendamment. Cette séparation n'est pas optionnelle sur un projet multi-équipes. C'est la seule chose qui empêche une refonte de devenir un incident de trois semaines.

Avec React 19 et les Server Components maintenant largement répandus, le contrat s'est étendu davantage. Un composant qui s'exécute sur le serveur ne peut pas accepter de props non sérialisables. Cette limite n'est pas une préférence de style. Elle est appliquée à l'exécution. Je traite maintenant la division serveur/client comme une décision architecturale de première classe, pas une réflexion après coup, et je la documente au même endroit où je documente les types de props.

Comment l'engagement commence réellement

Un client arrive avec un fichier Figma et une date limite. Parfois, ils ont une base de code existante. Parfois, ils ont un backend Laravel déjà en production et un frontend qui a été construit par un entrepreneur qui n'est plus disponible. Les deux premiers jours sont toujours un audit.

Je regarde quatre choses dans l'ordre :

• —Couverture des tokens : les couleurs, l'espacement et la typographie sont-ils exprimés comme des variables ou codés en dur ?
• —Surface des composants : combien de props le composant moyen expose-t-il, et combien d'entre elles sont documentées ?
• —Couverture des tests : y a-t-il des tests de régression visuelle, et si oui, sur quelle ligne de base s'exécutent-ils ?
• —Présence de Storybook : en existe-t-il un, et reflète-t-il l'état actuel du code ou un état d'il y a six mois ?

Les réponses déterminent le coût de l'engagement. Une base de code sans tokens et sans Storybook n'est pas un point de départ. C'est un passif qui doit être tarifé honnêtement avant que tout nouveau travail de fonctionnalité ne commence.

Le développement Laravel comme épine dorsale du contrat de composant

Laravel n'écrit pas de composants. Mais il possède les données qui y circulent, l'authentification qui les contrôle, et les contrats API sur lesquels le frontend dépend. Quand je travaille sur un produit full-stack, la couche Laravel est l'endroit où je définis la forme des données. Cette forme devient l'entrée du contrat de composant sur le frontend.

Sur le travail Financial Services Platform, l'API backend était la source de vérité pour chaque état dans lequel un composant UI pouvait être : chargement, erreur, données partielles, données complètes, restreint par les permissions. La bibliothèque de composants devait gérer explicitement tous ces états. Si l'API renvoyait un nouveau code d'erreur et que le composant n'avait pas de branche pour cela, l'utilisateur voyait un écran blanc. Mapper les états API aux états de composants n'est pas un travail glamour. C'est le travail qui détermine si le produit semble terminé.

Une réduction du temps de réponse de 30 % sur cette plateforme provenait en partie de la mise en cache au niveau de Laravel, mais provenait aussi de composants qui ne se re-rendaient pas inutilement parce que la forme des données était stable et prévisible. Le contrat fonctionnait dans les deux sens.

Storybook et la régression visuelle ne sont pas des extras optionnels

J'ai livré des bibliothèques de composants sans Storybook. Je ne le recommande pas. Storybook n'est pas de la documentation pour elle-même. C'est une fonction de forçage. Quand vous écrivez une histoire pour un composant, vous devez énumérer chaque état dans lequel ce composant peut être. Cette énumération attrape les cas limites avant qu'ils ne se retrouvent en production. Cela donne aussi à l'ingénieur suivant, celui qui rejoint six mois après le lancement, un environnement de travail où il peut explorer le composant en isolation sans avoir besoin de reproduire un état d'application spécifique.

Les tests de régression visuelle sont l'autre moitié. Je les utilise pour attraper la différence entre un changement délibéré et un changement accidentel. Une valeur de token se décale, un composant se re-rend différemment, un diff de capture d'écran le signale. Le coût de la mise en place de ceci est réel. Le coût de ne pas l'avoir, quand un système de design sert plusieurs produits, est plus élevé. Sur l'étude de cas Production Design System, l'obtention de Core Web Vitals de classe mondiale était en partie un problème d'optimisation de build, mais c'était aussi un problème de discipline : chaque composant devait être audité avant de pouvoir être publié, et la suite de régression visuelle était ce qui rendait cet audit assez rapide pour être durable.

Ce qui casse la deuxième année

La première année d'un système de design est généralement correcte. L'équipe qui l'a construit connaît les règles. La deuxième année est quand les règles commencent à s'éroder. Un nouveau produit a besoin d'un composant qui est presque comme un composant existant. Quelqu'un le copie et le modifie au lieu de l'étendre. Maintenant, il y en a deux versions. Les deux sont maintenues pendant un certain temps. Puis une seule l'est. L'autre dérive.

J'ai vu cela sur myQRCode, où le produit s'est étendu à 40 pays ou plus et la bibliothèque de composants a dû absorber des exigences de localisation qui n'étaient pas dans la spécification originale. Les équipes qui ont bien géré cela avaient un processus clair pour proposer des changements de composants, les examiner et verser le résultat. Les équipes qui ne l'ont pas fait avaient un cimetière de composants ponctuels que personne ne voulait toucher.

La discipline n'est pas compliquée. Elle nécessite quelqu'un ayant l'autorité de dire non à un raccourci, et un processus qui rend le bon chemin plus rapide que le mauvais. C'est ce que le leadership technique à l'intérieur d'un engagement de système de design ressemble réellement.

Commencer une conversation est la bonne prochaine étape

Si vous comparez des partenaires pour un projet qui implique une bibliothèque de composants, un backend Laravel, ou les deux, la chose qui vaut la peine d'être discutée n'est pas la stack technologique. C'est le plan de transmission. Qui documente le contrat de composant ? Qui possède la couche de tokens ? Que se passe-t-il quand une deuxième équipe rejoint ?

Ces questions ont des réponses, et les réponses dépendent de la forme de votre projet. La page services couvre les modèles d'engagement que j'offre, y compris MVP Sprint pour les équipes qui ont besoin d'un système fonctionnant en huit à douze semaines et le modèle Fractional CTO pour les équipes qui ont besoin d'un leadership technique continu sans une embauche à temps plein. Si vous voulez discuter de ce qui semble être le bon ajustement pour votre situation, le formulaire de contact est l'endroit pour commencer.