Audit de composant

Auditez les composants de code existants pour les décisions architecturales spécifiques à Webflow. Cette skill se concentre sur la qualité de l'intégration des composants avec Webflow Designer, pas sur les meilleures pratiques React génériques.

Quand utiliser cette skill

À utiliser quand :

• L'utilisateur souhaite améliorer le fonctionnement de ses composants dans Webflow Designer
• Il faut vérifier si les bonnes choses sont exposées comme props ou codées en dur
• Il faut vérifier si les patterns de gestion d'état sont compatibles avec Webflow
• Il faut chercher des opportunités de rendre les composants plus conviviaux pour les designers
• Un composant n'affiche pas ou ne se comporte pas correctement dans Webflow

À NE PAS utiliser quand :

• Valider avant le déploiement (utiliser pre-deploy-check à la place)
• Créer de nouveaux composants (utiliser component-scaffold à la place)
• Convertir un composant React (utiliser convert-component à la place)
• Faire une revue générique de qualité de code (utiliser un linter)

Philosophie centrale

Cet audit répond à trois questions :

1. Contrôle du designer : Les bonnes choses sont-elles exposées comme props pour que les designers les personnalisent ?
2. Compatibilité Webflow : Le composant fonctionne-t-il dans les contraintes de Webflow (Shadow DOM, SSR, racines React isolées) ?
3. Architecture du composant : Est-ce le bon niveau de granularité, ou faudrait-il le diviser/combiner ?

Instructions

Phase 1 : Découverte

1. Trouver tous les composants :

   • Localiser webflow.json
   • Trouver tous les fichiers .webflow.tsx
   • Lire les composants React correspondants

2. Comprendre l'intention : Demander à l'utilisateur à quoi servent les composants et ses préoccupations spécifiques

Phase 2 : Analyse

Pour chaque composant, analysez ces domaines spécifiques à Webflow :

A. Analyse d'exposition des props

Objectif : Identifier ce que les designers DEVRAIENT pouvoir contrôler mais ne peuvent pas actuellement.

Alias : props.String = props.Text, props.Children = props.Slot. Traiter ces comme équivalents lors de l'audit.

Questions à poser :

• « Qu'est-ce qu'un designer voudrait changer ? »
• « Qu'est-ce qui nécessite une modification du code qui ne devrait pas ? »

B. Architecture de gestion d'état

Objectif : Identifier les patterns qui ne fonctionneront pas dans Webflow.

Recommandations de refactorisation :

• Si les composants doivent communiquer → suggérer le pattern d'état entre composants
• Si Context est utilisé uniquement en interne → c'est OK, le documenter
• Si les composants sont étroitement couplés → suggérer la décomposition

C. Opportunités de Slot

Objectif : Identifier le contenu codé en dur qui devrait être contrôlé par le designer.

Quand NE PAS utiliser les Slots :

• Quand le contenu a des exigences comportementales spécifiques
• Quand le contenu doit interagir avec l'état du composant
• Quand la structure est vraiment fixe et non personnalisable

D. Compatibilité Shadow DOM

Objectif : S'assurer que les styles fonctionnent en isolement.

Note SSR : Quand vous utilisez styled-components ou Emotion, vous devez également configurer le rendu serveur dans webflow.json pour que SSR fonctionne correctement :

• styled-components: "library": { "renderer": { "server": "@webflow/styled-components-utils/server" } }
• Emotion: "library": { "renderer": { "server": "@webflow/emotion-utils/server" } }

E. Sécurité SSR

Objectif : Identifier le code spécifique au navigateur qui s'exécute lors du rendu.

F. Granularité du composant

Objectif : Déterminer si le composant est au bon niveau d'abstraction.

Signes qu'un composant devrait être DIVISÉ :

• Trop de props (>10) rendant l'UI du Designer encombrée
• Plusieurs sections distinctes qui pourraient être indépendantes
• Les designers veulent utiliser les parties séparément
• Le composant traite plusieurs préoccupations sans lien

Signes que les composants devraient être COMBINÉS :

• Toujours utilisés ensemble
• État étroitement couplé qui est maladroit à synchroniser
• Petits composants sans utilisation autonome

Phase 3 : Rapport

Générez un rapport exploitable avec :

1. Résumé : Aperçu rapide des conclusions
2. Par composant : Problèmes spécifiques et recommandations pour chacun
3. Recommandations architecturales : Préoccupations transversales
4. Actions prioritaires : Quoi corriger en premier

Liste de contrôle d'audit

Contrôle du designer (le plus important pour Webflow)

Compatibilité Webflow

Architecture

Exemple

Prompt utilisateur :

Audit my ProductCard component

Réponse :

## Audit : ProductCard

### Vue d'ensemble du composant

```typescript
// Props actuelles
props: {
  title: props.Text(),
  price: props.Number(),
  imageUrl: props.Text()  // ⚠️ Devrait être Image
}

A. Analyse d'exposition des props

Contenu codé en dur trouvé :

// Ligne 24 - codé en dur, devrait être une prop
<button>Add to Cart</button>

// Ligne 18 - codé en dur, devrait être une prop ou supprimé
{onSale && <span className="badge">SALE</span>}

Props recommandés à ajouter :

props: {
  // ...existant
  addToCartLabel: props.Text({
    name: "Button Label",
    defaultValue: "Add to Cart"
  }),
  showBadge: props.Boolean({
    name: "Show Badge",
    defaultValue: false
  }),
  badgeType: props.Variant({
    name: "Badge Type",
    options: ["sale", "new", "featured"],
    defaultValue: "sale"
  })
}

B. Gestion d'état

Problème : localStorage dans le rendu

// Ligne 8 - cassera SSR
const cartCount = localStorage.getItem('cart');

Correctif :

const [cartCount, setCartCount] = useState(0);
useEffect(() => {
  setCartCount(parseInt(localStorage.getItem('cart') || '0'));
}, []);

C. Opportunités de Slot

Si les designers doivent mettre un contenu différent (bouton, lien, élément personnalisé) dans la zone d'action :

props: {
  actions: props.Slot({
    name: "Actions"
  })
}

// Composant
<div className={styles.actions}>
  {actions}
</div>

Cependant, si le comportement du bouton est lié à la logique du panier, le garder codé en dur.

D. Compatibilité Shadow DOM

E. Sécurité SSR

F. Granularité du composant

Taille actuelle : 4 props (sera 7 après recommandations) Verdict : Bonne granularité - objectif unique, props gérables

Résumé

Actions prioritaires :

1. Corriger le problème SSR de localStorage (bloque le déploiement)
2. Changer imageUrl de prop Text à Image
3. Exposer les contrôles de badge comme props
4. Envisager d'exposer le label du bouton

Directives

Ce que cet audit NE vérifie PAS

Ceci n'est pas un audit générique de qualité de code. Ignorer :

• Les patterns de performance React génériques (laisser les utilisateurs utiliser React DevTools)
• L'accessibilité générique (laisser les utilisateurs utiliser axe ou similaire)
• Le formatage du code (laisser les utilisateurs utiliser Prettier/ESLint)
• Les meilleures pratiques TypeScript génériques

Se concentrer uniquement sur les préoccupations spécifiques à Webflow.

Heuristiques d'exposition des props

Devrait être une prop :

• Tout texte visible dans l'UI
• Toute image ou média
• Toute couleur ou taille qui peut varier
• Tout booléen qui contrôle la visibilité
• Toute valeur qui change par utilisation

Ne devrait PAS être une prop :

• Détails d'implémentation interne
• État qui change lors de l'interaction
• Valeurs dérivées d'autres props
• Timing/easing d'animation (sauf si explicitement personnalisable)

Quand recommander les Slots par rapport aux props

Utiliser Slot quand :

• Le designer veut mettre des éléments Webflow arbitraires à l'intérieur
• La structure du contenu est flexible
• Le contenu imbriqué n'a pas besoin d'interagir avec l'état du composant

Utiliser des props quand :

• Le contenu est simple (texte, image, lien)
• Le composant doit traiter/transformer le contenu
• Une structure spécifique est requise

Recommandations de pattern d'état

Si les composants doivent partager l'état, recommander dans cet ordre :

1. Paramètres URL - si l'état doit être partageable/marquable
2. Nano stores - pour la synchronisation en temps réel entre composants
3. Événements personnalisés - pour la communication sans retour
4. Stockage du navigateur - pour la persistence entre sessions