De la spec à l'app : IA, React Native, Design System et Figma MCP

Le projet

Depuis 2020, je gère ma nutrition via un fichier Google Sheets que j'ai construit et affiné au fil des années. D'abord pour moi, puis pour mes coachés lorsque j'ai développé une activité annexe de coach sportif et nutrition. Un fichier bien rodé, automatisé, qui connaît exactement mes besoins, mais qui reste un fichier.

L'idée était de transformer ce Google Sheets en une vraie application mobile, en reprenant les mêmes fonctionnalités et les mêmes logiques, mais avec une expérience fluide, pensée pour le téléphone, installée sur mon iPhone et utilisée au quotidien.

Pourquoi maintenant

L'objectif n'était pas d'apprendre React Native et les outils IA en isolation, via des tutoriels ou des tests sans enjeu. C'était de monter en compétences sur ces deux fronts en même temps, sur un vrai projet, avec de vraies contraintes, et un résultat qui m'est utile au quotidien. Claude Code a rendu cette approche crédible.

Brainstorming avec Claude AI

Armé de cette vision, j'ai ouvert une conversation avec Claude AI pour structurer le projet. J'avais une idée claire : transformer mon Google Sheets de tracking nutritionnel en app mobile. Mais passer d'une vision à un brief exploitable par Claude Code demandait du travail.

J'ai partagé mes fichiers CSV issus du Google Sheets, décrit les fonctionnalités attendues, les comportements UX, les contraintes techniques. Claude AI m'a aidé à affiner la vision, arbitrer les priorités et définir le périmètre exact du MVP. Ce travail a produit deux livrables : un flowchart FigJam avec les écrans principaux, les enchaînements de navigation et les comportements clés de chaque vue, et un fichier specs.md qui allait devenir la source de vérité du projet. Deux documents complémentaires, structurés pour ancrer Claude Code dans la logique globale de l'app avant de toucher au code.

Le specs.md : source de vérité vivante

Le specs.md n'est pas un cahier des charges rigide. C'est un document vivant : avant le build, il concentre la vision, l'architecture technique, les certitudes du MVP. Pendant et après le build, il s'enrichit et se précise au fil des décisions prises. Il a rapidement été complété par d'autres fichiers thématiques : documentation.md, design-tokens-architecture.md, design-system-rules.md... Autant de ressources que Claude Code peut consulter à tout moment pour rester aligné avec les intentions du projet.

Briefer Claude Code avant de coder

Une fois le FigJam et le specs.md prêts, j'ai construit une app vide : structure de fichiers, stack installée, un "hello world" classique. Puis j'ai soumis l'ensemble des ressources à Claude Code, sans lui demander de coder quoi que ce soit. Sa mission : ingurgiter le FigJam, le specs.md et les CSV, détecter les incohérences, les zones d'ombre, les points de friction. Je lui ai demandé de me produire un fichier de synthèse de cet audit, puis on a affiné les documents avant de se lancer sur le premier lot.

Cette phase amont, du brainstorming initial au brief Claude Code, a tenu en une à deux journées. Courte, mais décisive.

Piloter, pas juste prompter

La méthode de travail avec Claude Code s'est affinée dès les premiers lots. Le réflexe systématique : ne jamais lui demander de foncer dans le tas. Avant chaque implémentation, lui demander d'exposer sa réflexion, de se documenter auprès de ressources pertinentes, de proposer plusieurs pistes et d'expliquer ses choix. Valider la direction avant de donner le go sur les modifications.

Sur le lot design system en particulier, cette approche a fait une vraie différence. Affiner la vision ensemble, challenger les options, comprendre les implications de chaque décision avant d'écrire une ligne : c'est ce qui a permis d'arriver à une architecture de tokens solide plutôt que de refactoriser après coup.

En fin de session, le réflexe du diff : demander à Claude Code de synthétiser ce qui a changé, pourquoi, et ce qui reste à faire. Une façon de garder la main sur ce qui se passe réellement dans la codebase.

Les skills : automatiser les tâches récurrentes

Entre les lots, j'ai créé deux skills Claude Code qui sont devenus indispensables. Le skill /audit déclenche un audit complet de la codebase : qualité du code, cohérence des composants, logique métier, alignement avec les docs de référence. Le skill /debug-error structure le processus de debug avec explications et analyse des screenshots d'erreur. Ces deux skills ont rendu les sessions de refacto entre les lots beaucoup plus efficaces et reproductibles.

Documentation comme infrastructure

Deux fichiers ont émergé naturellement au fil du build. Le documentation.md d'abord, à mi-parcours, quand la stack était suffisamment dense pour nécessiter un mémo centralisé : stack technique complète, conventions, patterns de debug, procédures de build. Un mémo vivant, mis à jour au fil du projet et consulté régulièrement.

Le backlog.md ensuite, une fois les 12 lots terminés et un dernier /audit passé : toutes les améliorations identifiées, les décisions différées, les next steps classées par priorité. La façon de clôturer proprement une version sans perdre le fil de ce qui attend.

Monter en compétences sur un écosystème inconnu

Ce projet m'a confronté à plusieurs technologies nouvelles en parallèle. L'adaptation à React Native a été rapide : venant du web, le templating Yoga et l'absence de CSS classique demandent un petit temps d'ajustement, mais la logique reste familière pour quelqu'un qui a du JavaScript et de la culture composant.

Sur TanStack Query, Zustand et Supabase, l'approche a été différente. Ces parties ont bénéficié d'un appui plus conséquent sur Claude Code. Pas une délégation aveugle : le même réflexe qu'ailleurs, demander d'expliquer les options, les compromis, pourquoi telle structure plutôt qu'une autre. J'ai contrôlé l'architecture globale, les décisions de réutilisabilité, l'organisation en composants et en objets. Mais la maîtrise fine de ces libs est un chantier ouvert, et c'est l'un des apprentissages que ce projet continue de nourrir.

NativeWind : Tailwind sur mobile

Sur le web, on stylerait avec du CSS classique. Sur React Native, il n'y a pas de CSS : les styles sont des objets JavaScript appliqués composant par composant. NativeWind résout ça en adaptant la syntaxe Tailwind à React Native. On écrit des className comme sur le web, NativeWind les transforme en styles natifs au build.

Ce choix a une conséquence directe sur l'architecture des tokens : tout le système de design passe par tailwind.config.js. C'est lui qui fait le lien entre nos tokens et les classes utilitaires disponibles dans les composants.

Architecture tokens : 3 couches, circulation descendante

Le système de tokens est organisé en trois couches distinctes, chacune dans son propre fichier, avec une règle absolue : un token ne circule que vers le bas, jamais vers le haut.

La couche 1 sont les primitives, dans foundations-tokens.js : valeurs brutes organisées par familles. Les couleurs, nommées par teinte et step numérique (gray.900, blue.500). La typographie, avec les familles de polices, les tailles et les graisses. L'espacement, les dimensions fixes et les border radius. Ce sont les matériaux bruts du système, sans intention ni rôle assigné.

La couche 2 sont les alias sémantiques, dans alias-tokens.js : les primitives reçoivent un rôle. gray.900 devient primary, foreground, surface.foreground. C'est cette couche qui produit les classes Tailwind utilisées dans le code : bg-primary, text-foreground, bg-surface. Elle couvre aussi la typographie avec des styles nommés par intention, heading, body, label, muted, jamais par leur valeur brute.

La couche 3 sont les tokens composant, déclarés inline en haut de chaque fichier .tsx. Chaque composant déclare un objet Tokens qui référence en priorité des alias de couche 2. Jamais de valeur hex en dur, jamais de classe Tailwind arbitraire. Certaines catégories comme SPACING, FONT_SIZE ou SIZING n'ont pas de couche 2 : un composant peut alors les importer directement depuis foundations-tokens.js. Ce n'est pas une exception à la règle, il n'y a simplement rien entre les deux.

La règle de circulation est strictement descendante : la couche 2 ne référence jamais la couche 3, la couche 1 ne référence jamais la couche 2 ou 3. Ce qui est interdit c'est la remontée, pas le saut.

tailwind.config.js ne fait qu'assembler : il importe les deux fichiers de tokens et câble le thème Tailwind. Il ne définit aucune donnée lui-même.

Le DS Playground : un Storybook natif

Un choix d'outillage délibéré : un groupe de routes (ds)/, visible uniquement en mode __DEV__, qui liste et documente tous les composants du système. Foundations, atoms, molecules, organisms : chaque composant est affiché avec toutes ses variantes, ses props, ses états. Un Storybook maison intégré directement à l'app, consultable sur simulateur ou device à tout moment.

Ce playground permet de valider visuellement chaque composant au moment de sa création et de disposer d'une référence vivante à portée de main pendant tout le build.

Le substitut artisanal : trois fichiers de référence

La réponse à cette contrainte a été de documenter manuellement ce que Code Connect aurait automatisé. Trois fichiers ont été créés pour ça.

design-system-rules.md : la référence styling condensée. Stack technique, tokens couleurs et typographie, règles critiques (twMerge obligatoire, pas de valeurs hardcodées, pas de StyleSheet.create), direction visuelle. Le document que Claude Code consulte pour savoir comment styler n'importe quel composant.

component-map.md : le mapping exhaustif Figma/code. Pour chaque composant, le nom dans Figma, le fichier source dans la codebase, les props principales, les usages. C'est ce qui évite à Claude Code de recréer un composant qui existe déjà, et ce qui garantit que les deux côtés restent alignés.

figma-prompt-template.md : le template de prompt pour toutes les sessions de mise à jour UI. Un format standardisé qui assure qu'aucune information critique n'est oubliée d'une session à l'autre.

Ces trois fichiers sont déclarés dans CLAUDE.md : Claude Code les consulte automatiquement sans qu'ils soient mentionnés dans chaque prompt. Ce substitut ne couvre pas totalement ce que ferait Code Connect : rien n'est lié automatiquement et précisément entre les composants Figma et les composants React Native. Mais il permet de driver Claude Code de façon suffisamment précise pour s'en approcher et maintenir une cohérence entre les deux côtés.

Générer la bibliothèque depuis la codebase

La génération de la bibliothèque Figma depuis le code se fait via le skill /figma-generate-library. C'est une tâche multi-étapes qui demande des ressources : variables, styles, composants, pages organisées en miroir de la codebase. Mieux la codebase est architecturée et documentée, plus la génération est précise et les écarts limités. Mais ça reste une grosse tâche, qui nécessite une session dédiée sans interruption.

Le résultat : une bibliothèque Figma organisée comme la codebase, avec une page par atom, par molecule et par organism. Variables de couleurs, styles typographiques, composants avec leurs variantes. Une base de travail solide, pas un résultat parfait.

Les limites de la génération Code→Figma

La direction Code→Figma est la moins mature du workflow. Les incohérences sont inévitables, et plusieurs catégories se sont répétées sur ce projet.

Les variables n'ont pas été systématiquement liées aux composants générés. Des ajustements manuels ont été nécessaires de façon aléatoire sur les couleurs, les typographies, les espacements, pour s'assurer que chaque composant utilise bien les variables Figma plutôt que des valeurs hardcodées.

Les styles de texte n'ont pas été liés aux textes des composants. C'est un manquement connu côté Figma, une fonctionnalité qui devrait être ajoutée prochainement.

L'interprétation du code est parfois bancale. Le MCP a généré des variantes pour des états interactifs qui n'ont pas vocation à être documentés dans Figma, ajoutant de la complexité inutile à la bibliothèque.

Le MCP n'a pas respecté la hiérarchie des composants : chaque composant a été redessiné à plat, sans instancier les composants enfants existants. Dans la molecule FormField par exemple, qui compose l'atom Input, le MCP a recréé l'UI de l'Input from scratch plutôt que d'en utiliser l'instance. C'est probablement un cas où Code Connect ferait la différence : sans liaison précise entre les composants Figma et React Native, le MCP ne sait pas qu'un composant en contient un autre.

Enfin, les composants avec des patterns visuels particuliers ont été mal interprétés. La progress bar circulaire et le bouton "+" circulaire ont été redessinés de façon approximative, loin du rendu réel.

La bonne pratique établie : corriger manuellement dans Figma plutôt que de chercher à tout résoudre par des prompts itératifs. Republier la bibliothèque après corrections, puis passer aux écrans.

Générer les écrans depuis les specs

Une fois la bibliothèque publiée et les corrections manuelles appliquées, les écrans peuvent être générés via /figma-generate-design. J'ai généré un écran par prompt, dans un ordre logique du plus simple au plus complexe. Setup d'abord, Profil, Food, Recipes, et en dernier le Diary, l'écran le plus complexe avec son bottom sheet, ses snap points et ses comportements non-inférables depuis la structure Figma seule.

Pour chaque écran, Claude Code reçoit l'URL du fichier bibliothèque, l'URL de la frame cible avec son node-id, le fichier source .tsx, et les specs fonctionnelles correspondantes. Il travaille section par section, en instances de composants publiés, toutes les couleurs liées aux variables Figma, avec validation visuelle après chaque section.

Après chaque écran généré, les écarts sont corrigés manuellement dans Figma par comparaison avec le simulateur iOS. Ce qui ne peut pas s'inférer depuis la structure, les comportements interactifs, les guards de navigation, les transitions du bottom sheet, est annoté dans les prompts.

Claude Code consulte Figma

Un usage qui s'est imposé naturellement au fil du projet : utiliser le MCP Figma dans l'autre sens, pas pour générer mais pour consulter. Claude Code accède à la bibliothèque Figma pour détecter des manques, vérifier l'alignement entre ce qui existe dans Figma et ce qui existe dans le code, identifier des états ou des variantes qui n'ont pas encore été implémentés. Un audit croisé permanent qui permet de garder les deux côtés synchronisés.

Figma→Code : le workflow inverse

Une fois la bibliothèque et les écrans en place dans Figma, le travail UX et UI peut se faire directement dans Figma. Et depuis, le sens inverse est opérationnel.

Le workflow est le suivant : des frames précises avec des annotations dans Figma, une URL de layer ciblée, un prompt construit depuis le figma-prompt-template.md, et l'ensemble des fichiers .md de référence en contexte. Claude Code lit les frames, lit les annotations, compare avec le code existant, propose un plan d'action et implémente les modifications. Le component-map.md est particulièrement utile ici : Claude Code sait exactement quel composant existant modifier plutôt que d'en recréer un nouveau.

Frames + annotations + prompt + documents de référence : un workflow défini et reproductible pour implémenter des updates ou de nouvelles features.

Suivre les écarts Figma/Code

Pour garder une vision claire de ce qui existe dans Figma et dans le code à tout moment, j'ai créé un fichier figma-etats-manquants.md. Il répertorie de façon exhaustive les composants, les parcours, les états et les interactions : ce qui est dans la lib Figma, ce qui est dans l'app, et les écarts entre les deux. Un audit croisé qui sert de point de départ dès qu'un besoin d'itérer sur un état précis se fait ressentir, dans un sens ou dans l'autre.

Ce que ça change dans ma pratique

Ce projet révolutionne ma façon de travailler. L'approche specs-first, le découpage en lots, les skills Claude Code : ce sont des méthodes directement transposables à mes projets clients. En particulier sur deux plans où je vois un impact immédiat : le travail de design system, où le workflow Code/Figma ouvre des possibilités que je n'avais pas avant, et la capacité à builder ou prototyper des produits rapidement et à les rendre testables.

Ce que je ferais différemment

Si je recommençais, je changerais une seule chose : démarrer plus tôt. Les outils IA de développement étaient encore dans leurs balbutiements il y a un an, mais c'était déjà suffisant pour se lancer. La vraie barrière n'était pas technique, c'était de trouver le bon prétexte pour commencer sérieusement.

Suite

Le projet continue. L'immédiat, c'est d'améliorer l'UX et l'UI de l'app avec le workflow Figma établi. À moyen terme, ouvrir le projet à d'autres utilisateurs, implémenter l'authentification, faire évoluer les features. Et à plus long terme, explorer l'intégration de solutions IA directement dans l'app.