Issu du passage de notre maquette Page Carrefour dans l'intégration Figma + shadcn MCP. La Partie 1 décrit ce dont nous avons besoin dans les fichiers. La Partie 2 est une structure à discuter — elle peut être écartée.
Gardez les composants (Button, Card, …) isolés sur une page Composants, avec leurs variantes. Gardez les maquettes sur leur propre page. Kiro lit la maquette pour comprendre l'usage, et le composant pour comprendre sa structure — mélangés, il ne peut pas les distinguer.
Ne laissez pas de composants en trop ou en double dans une frame de composition. Les restes créent du bruit et rendent flou quelle version fait foi.
Chaque élément qui correspond à un composant doit rester une instance vivante liée à celui-ci — pas détachée, pas redessinée en formes brutes. Une instance détachée est invisible pour le mapping : Kiro la reconstruit comme un one-off au lieu de reconnaître le composant.
Sur Page Carrefour, le fil d'ariane, la carte d'avis, la notation et les cartes « atouts » étaient tous des frames détachées — chacune a dû être reconstruite à la main plutôt que mappée.
Le nom d'une frame doit dire ce qu'elle est, pour qu'elle se mappe à un élément et un composant qui ont du sens.
À privilégier : Header Hero Card Testimonial Section : Pourquoi l'UCPA
À éviter : Frame 222 Group 11 Container Flex
Sur Page Carrefour, les sections arrivaient nommées Frame 222, container… — savoir laquelle était le hero, le footer, les avis a dû se déduire du contenu, pas des noms.
Toutes les couleurs, espacements, tailles et typographies viennent des variables globales — jamais d'une valeur en dur ni d'un style ponctuel. Une page Style Guide peut refléter les variables, mais elle n'est jamais un second endroit où les valeurs sont modifiées.
C'est la règle la plus impactante. Nous avons déjà rencontré de vrais bugs dus à des écarts : un token d'espacement dont les deux paliers étaient inversés ; un h1 réglé sur la valeur mobile, si bien que tous les titres desktop s'affichaient ~16 px trop petits ; et du contenu de page encore lié à des valeurs kit/wireframe résiduelles (--sds-*, une couleur wireframe #100D08) au lieu des tokens UCPA.
L'idée : l'identité de marque et le theming vivent dans une seule core library. UCPA est à la fois l'identité et son propre projet. Les projets réels, en production — speedboat, alpha, labalaguère — se placent en dessous, chacun avec ses propres composants et tokens de thème ; common regroupe ce qui est partagé. Les pages/features (Page Carrefour, Tunnel d'achat, toute nouveauté) se lient à la core plutôt que de redessiner les éléments localement.
Kiro a les composants de la core reliés via Code Connect, ce qui lui permet de mapper chaque élément de design au bon composant de code. Quand un designer modifie un composant, son lien Code Connect passe en « obsolète » ; un dev lance une commande de re-liaison ciblée sur cette page et ce composant. La configuration du projet embarque un manifeste des IDs de pages et des mappings, versionné dans le repo, pour qu'un simple checkout sache déjà où se trouve chaque élément.
Le MCP de Figma peut récupérer le contexte d'un projet Make directement dans l'agent. On partage un lien de prototype Make et l'agent récupère le comportement et les styles de ce composant — par ex. le mouvement d'une popup — et l'implémente sur notre vrai composant, portant l'animation du prototype jusqu'à la production. (Nécessite un client MCP compatible « resources ».) Doc Figma →