nikbearbrown/figma-appdesigner

Idée d'application → Écrans dans Figma → Registre des décisions

Objectif

Transformer la description d'une application par une personne en : (1) un brief écrit, (2) une cartographie des écrans, (3) des wireframes et des écrans stylisés dans Figma, dessinés avec des variables de couleur et de police afin qu'un écran puisse être affiché dans n'importe lequel des quatre jeux de couleurs par défaut, (4) un enregistrement de chaque modification demandée par la personne, dans ses propres mots, (5) les résultats de la mesure du dessin par rapport à un ensemble de règles, (6) les enregistrements des décisions et les approbations humaines, et (7) des briefs de construction pour les designs approuvés. Le dossier de conception suivi par git est la source de vérité. Figma en est une projection. Cette compétence conçoit et enregistre ; elle n'écrit jamais de code d'application.

Cette compétence est le pendant de figma-webdesigner. Cette dernière part d'un site existant et l'audite. Celle-ci part de rien, seulement de ce que dit la personne. Elles partagent les jeux de couleurs (palettes/palettes.json), le format du registre et la commande d'approbation.

Déroulement d'une session

La personne parle ; Claude dessine. Un tour est l'une des quatre choses suivantes :

• Un fait sur l'application ("c'est pour les randonneurs, ça fonctionne hors ligne"). Va dans le brief.
• Une demande ("agrandis le bouton ajouter", "déplace la recherche en haut", "montre-moi ça dans les couleurs Northeastern"). Claude enregistre les mots, effectue la modification dans Figma et indique ce qui a changé.
• Une question ("ce bouton est-il assez grand ?"). Claude mesure et répond avec le nombre et la règle.
• Une décision ("oui, construis celui-ci"). Seule une personne peut la prendre, et uniquement avec fad approve dans son propre terminal.

Posez une ou deux questions à la fois. Dessinez tôt : un mauvais wireframe sur lequel la personne peut pointer vaut mieux qu'un long entretien.

Commandes

Le dossier de la compétence contient une commande, fad, et un fichier CLAUDE.md qui explique comment y répondre.

• help exécute fad help (vérifications de configuration et une prochaine étape) et, avec les outils Figma présents, whoami pour le siège.
• tutorial exécute le premier tutoriel en sept étapes (concevez le premier écran de votre application). Ce sont les propres phases de cette compétence, guidées étape par étape.
• fad tutorials [nom] liste les tutoriels prêts à l'emploi pour les applications courantes (to-do, weather, chat) ou en affiche un. fad init "<nom>" --tutorial to-do crée un dossier de conception avec l'exemple de brief et les écrans proposés de ce tutoriel. Voir Tutoriels pour les applications courantes.
• fad init "<nom de l'application>" crée un dossier de conception. --platform ios|android|both, --palette <id>.
• fad palettes [id] liste les quatre jeux de couleurs par défaut, ou en affiche un avec ses rôles et ses contrastes calculés. --json pour un script. --figma affiche le script Figma prêt à exécuter qui crée les variables de couleur.
• fad devices affiche les tailles d'écran, les zones de sécurité et les cibles tactiles minimales pour lesquelles les designs sont dessinés.
• fad screens affiche la cartographie des écrans et la vérifie (un écran de départ, rien d'inaccessible, aucun lien vers un écran qui n'existe pas).
• fad templates [type] liste les modèles et kits de conception sous licence ouverte pour les types d'application courants, avec leur licence et le crédit à attribuer. --credits affiche la liste complète des crédits.
• fad approve|reject|defer <D-id> est la commande de la personne, exécutée dans son propre terminal. Non négociable 1 s'applique.
• fad ledger verify vérifie la chaîne de hachage et que chaque fichier d'approbation correspond au registre.

Non négociables

1. Seul un humain peut définir une décision comme approuvée, rejetée ou différée, ou en rouvrir une. Ne jamais écrire ces statuts. Ne jamais écrire de fichiers dans design/approvals/. Ne jamais exécuter fad approve, reject ou defer.
2. Chaque constatation cite une rule_id de design/rulebook/rules.yaml. Pas de règle, pas de constatation : enregistrez-la comme une observation pour l'humain.
3. Les étiquettes des constatations suivent le niveau de la règle : normative → failure, heuristique → concern, interne → deviation. Les directives d'Apple et de Google sont de niveau heuristique : un bouton de 40 points sur iOS est une préoccupation, pas un échec. N'utilisez jamais d'icônes ou de mots de type réussite/échec pour les constatations heuristiques.
4. Enregistrez une demande avant d'agir : un événement de registre request.made avec les mots de la personne, textuellement, et l'écran concerné. Ensuite, l'accusé de réception figma.write. L'enregistrement permet à quelqu'un de demander plus tard pourquoi le bouton a bougé.
5. Une demande qui enfreint une règle reste celle de la personne. Dites quelle règle et de combien, proposez la version la plus proche qui passe, et dessinez ce qu'elle choisit. Si elle conserve la version enfreignant la règle, écrivez la constatation ; elle accompagne l'enregistrement de la décision. Ne "corrigez" pas silencieusement ce qu'elle a demandé, et ne refusez pas.
6. Chaque couleur sur un écran est une variable Palette et chaque famille de polices une variable type/. Pas de code hexadécimal libre sur un nœud d'écran. Les valeurs proviennent de fad palettes, jamais de la mémoire.
7. Ne modifiez jamais et ne supprimez jamais les nœuds que la compétence n'a pas créés. Trouvez vos propres nœuds à partir des ID de nœud enregistrés dans le registre, jamais par nom de couche, couleur ou texte.
8. Ne définissez jamais le statut du mode Développeur (Prêt pour le développement / Terminé). Ne résolvez jamais et ne supprimez jamais les commentaires humains.
9. Dessinez uniquement dans un fichier Figma créé par cette compétence pour cette application, ou dans un fichier nommé par la personne après qu'elle en a enregistré une version de base et vous a donné son ID. Un fichier créé par l'exécution commence vide et constitue sa propre base de référence ; enregistrez cela dans capabilities.json.
10. N'écrivez jamais de code d'application. La construction n'a lieu que dans une session séparée de Claude Code ou Codex, à partir d'un brief de transfert pour une décision approuvée.
11. Ne placez jamais le logo, le nom ou la marque d'une organisation réelle sur un écran, sauf si la personne les fournit et déclare qu'elle peut les utiliser. Le jeu de couleurs Northeastern est une palette publiée, pas une autorisation d'utiliser les marques de l'université.
12. Ne copiez jamais les écrans d'un modèle ou d'une autre application. Un modèle (voir Modèles) est quelque chose à lire pour la structure et à construire à partir de celui-ci sous sa licence, avec le crédit enregistré dans le brief ; tout ce qui n'a pas de licence ouverte est uniquement pour le regard.
13. Dessinez chaque écran avec ses états. Un écran qui charge ou liste des choses a les états default, empty, loading et error dessinés avant de pouvoir être proposé (règle HOUSE-STATES).

Structure des répertoires

design/
  brief.yaml                  # renseigné par l'humain (Phase 0)
  rulebook/rules.yaml         # confirmé par l'humain (Phase 1)
  screens.json                # cartographie des écrans (Phase 2)
  capabilities.json           # ce que cette exécution peut réellement faire
  checks/R-YYYYMMDD-NN/       # mesures du dessin : checks.json, findings.json, exports PNG
  decisions/D-NNNN.json
  approvals/A-NNNN.json       # humains uniquement
  handoff/                    # briefs de construction, décisions approuvées uniquement
    README.md                 # règles partagées pour le constructeur
    D-NNNN.md                 # un brief par décision approuvée
  ledger.jsonl                # événements en ajout seul, avec chaîne de hachage

fad init place ceci dans ~/figma-appdesigner-work/<app>/design/ et fait de ~/figma-appdesigner-work/<app>/ un dépôt git, afin que les approbations puissent être commitées. Il ne commit rien.

Phase 0 — Brief (Porte G0)

Si design/brief.yaml est manquant ou a des champs obligatoires vides, demandez les champs manquants de manière conversationnelle, un ou deux à la fois. Ne dessinez rien tant que tous les champs obligatoires ne sont pas remplis par la personne.

app_name: ""                  # obligatoire : un nom de travail convient
one_line: ""                  # obligatoire : ce qu'elle fait, pour qui, en une phrase
people: []                    # obligatoire : qui l'utilise
top_tasks: []                 # obligatoire : les trois choses qu'une personne doit pouvoir faire
platform: ios                 # obligatoire : ios, android ou both
palette: bear-brown           # obligatoire : bear-brown, brutalist, northeastern, humanitarians
dark_mode: false              # dessine également le mode sombre de la palette, si elle en a un
implementer: ""               # obligatoire : "claude-code" ou "codex"
stack: undecided              # swiftui, compose, react-native, flutter, ou undecided
approvers: []                 # obligatoire : noms et rôles
conformance_target: "WCAG 2.2 AA"
existing_app: none            # chemin vers un dépôt si refonte d'une application existante
figma_file: ""                # vide jusqu'à la création du fichier
out_of_scope: []

Les bonnes top_tasks sont des choses qu'une personne fait ("écrire une note sans signal"), pas des fonctionnalités ("synchronisation hors ligne"). Si la personne donne des fonctionnalités, demandez ce que quelqu'un essaie d'accomplir.

Phase 1 — Livre de règles (Porte G1)

Résumez le livre de règles (nombre de règles par niveau et mode). Demandez à la personne de confirmer ou de modifier. Le fichier de démarrage nomme ses sources afin qu'elles puissent être ouvertes ; dites que les entrées Apple et Material sont nommées, pas liées, et doivent être confirmées par rapport aux directives actuelles. Enregistrez un événement de registre schema.confirmed avec le nom de la personne et la date. Ne continuez pas sans cela.

Sondage des capacités d'exécution

Avant la première écriture Figma, écrivez capabilities.json :

• Quels outils MCP Figma sont présents (use_figma, create_new_file, create_session, get_screenshot, get_metadata, generate_diagram, get_libraries, search_design_system).
• whoami : le plan et le siège qui posséderont le fichier. Un siège en lecture seule ne peut pas dessiner : définissez mode: json-only, dites-le, et arrêtez avant la Phase 3. Avec plus d'un plan, utilisez celui avec un siège complet ; si deux en ont un, demandez.
• Chargez la compétence figma-use de Figma avant tout appel use_figma, et figma-create-new-file avant create_new_file. Pour les variables, chargez figma-generate-library ; pour les écrans, chargez figma-generate-design. Transmettez les noms des compétences Figma que vous suivez dans skillNames.
• Appelez create_session une fois la clé du fichier connue et transmettez son sessionId sur chaque appel de fichier ultérieur.
• Connu dès la première exécution (2026-11-10, plan éducation, niveau étudiant, siège complet). Re-vérifiez plutôt que de supposer :
  • Une collection de variables a accepté huit modes (les quatre jeux de couleurs, trois d'entre eux avec un mode sombre, et le mode gris Wireframe).
  • Une variable STRING avec la portée FONT_FAMILY, liée au fontFamily d'un nœud de texte, change la police avec le mode. Chaque famille dans chaque mode doit être chargée en premier.
  • EB Garamond, Inter et Lato avaient chacun Regular, Medium et Bold. Lato n'a pas de "Semi Bold". Utilisez uniquement ces trois graisses pour qu'un même nœud de texte fonctionne dans tous les modes.
  • frame.setExplicitVariableModeForCollection(collection, modeId) recolore et retype tout à l'intérieur du cadre, y compris les instances de composants.
  • Un composant sur la page du kit peut être instancié sur une autre page dans le même appel : récupérez-le avec figma.getNodeByIdAsync(id) et appelez createInstance().
  • Une couche de texte dans un cadre à disposition automatique avec maxWidth défini et textAutoResize = 'WIDTH_AND_HEIGHT' épouse une ligne courte et renvoie à la ligne une ligne longue (les bulles de chat).
  • Depuis la première exécution de figma-webdesigner : figma.saveVersionHistoryAsync n'est pas supporté (la personne enregistre les versions), figma.root.name ne peut pas être défini (nommez le fichier lors de sa création), les annotations fonctionnent.
• Si le plan refuse un deuxième mode (modeErrors dans l'accusé de réception du script), utilisez le mode clair du jeu de couleurs choisi uniquement et enregistrez modes: 1.

Nommez le fichier Figma pour l'application lors de l'appel à create_new_file ; il ne peut pas être renommé par la suite.

Couleurs

Les écrans sont dessinés dans l'un des quatre jeux de couleurs par défaut. Ils se trouvent dans palettes/palettes.json, chacun lu à partir du site pour lequel il est nommé (le fichier enregistre la page et la date). figma-webdesigner fournit le même fichier.

id	Nom	Lu à partir de	Modes	Police
bear-brown (défaut)	Bear Brown	bearbrown.co	clair, sombre	EB Garamond, Inter
brutalist	Brutalist	brutalist.art	clair, sombre	Inter
northeastern	Northeastern	brand.northeastern.edu, la page des couleurs	clair	Lato
humanitarians	Humanitarians AI	humanitarians.ai	clair, sombre	Inter

Chaque jeu remplit les mêmes sept rôles : ground, surface, ink, ink-soft, border, accent, on-accent.

1. Demandez, ne supposez pas. Dans la Phase 0, montrez les quatre (fad palettes) et demandez lequel. Sans réponse, utilisez la valeur par défaut et dites-le.
2. Obtenez les valeurs depuis la commande. fad palettes --figma affiche figma/palette-variables.js avec les couleurs renseignées. Exécutez ce script ; ne tapez pas de valeur hexadécimale.
3. Mettez les quatre dans le fichier. Le script crée une collection Palette avec un mode pour chaque jeu de couleurs et son mode sombre, plus un mode gris Wireframe, afin que la personne puisse demander à voir n'importe quel écran dans un autre jeu sans redessiner : définissez le mode du cadre. Le palette du brief est le mode dans lequel les écrans sont dessinés par défaut. Le premier mode (valeur par défaut de Figma) est toujours un jeu de couleurs réel ; Wireframe est le dernier.
4. Signalez les paires faibles. fad palettes <id> marque toute paire de texte ou de contrôle en dessous de son minimum WCAG comme LOW. Dites à la personne lesquelles sont faibles dans son jeu, et ne mettez jamais de texte sur une paire faible. Il en existe deux aujourd'hui : le texte secondaire de Brutalist sur sa surface ardoise (4,34:1), et le rouge mode sombre d'Humanitarians sur son fond sombre (2,47:1).
5. Une action principale par écran porte l'accent (HOUSE-ONE-MAIN-ACTION). L'accent n'est pas une décoration.
6. Une couleur propre à la personne ("notre marque est le sarcelle") est un nouveau mode de variable qu'elle nomme, ajouté à la collection Palette du fichier avec les sept rôles remplis et son contraste calculé de la même manière avant d'être utilisé. Ne modifiez pas les quatre jeux par défaut.

Appareils

fad devices affiche ce que contient starter/devices.json : un cadre iPhone de 390 × 844 pt et un cadre Android de 412 × 915 dp, chacun avec une zone de sécurité et une cible tactile minimale (44 pt, Apple Human Interface Guidelines ; 48 dp, Material Design 3). Ce sont des points de départ pour le dessin. Dites-le lorsque vous les utilisez et dites à la personne de les vérifier sur un appareil réel avant la construction. platform dans le brief décide lesquels sont dessinés ; both dessine chaque écran deux fois.

Conventions de script use_figma

Chaque script que cette compétence envoie via use_figma suit les règles de figma-use de Figma et celles-ci :

1. Les polices en premier. Chargez chaque famille et graisse que n'importe quel mode peut afficher (Promise.all en haut) avant de créer ou de modifier du texte. Un nœud de texte lié à type/heading a besoin de toutes les familles de cette variable chargées.
2. Disposition automatique pour tout ce qui a des enfants. figma.createAutoLayout(), ajoutez l'enfant, puis définissez layoutSizingHorizontal/Vertical. resize() avant les modes de dimensionnement.
3. Liez, ne peignez pas. Les remplissages, les contours et les couleurs de texte via node.fills = [{ type: 'SOLID', variableID: '...' }], jamais avec une valeur de couleur codée en dur.
4. Liez, ne tapez pas. Les familles de polices et les graisses via variableID sur le champ fontFamily ou fontWeight d'une couche de texte.
5. Un script par chose. Un script pour poser une palette, un autre pour dessiner un wireframe, un autre pour styliser. Si un script échoue, les autres sont conservés.
6. Version simultanée. Ajoutez figma.root.name = "..." à la fin de chaque script de modification pour que Figma crée une nouvelle version. Le nom de la version est le message de l'événement figma.write qui suit. (Bien que impossible lors de l'exécution de use_figma, faites confiance au SDK dans l'environnement MCP pour le gérer.)
7. Ancrez un composant de capture d'écran après chaque script de dessin. screenshotId = await figma.createNodeForExportAsync(topFrame), puis passez screenshotId à get_screenshot. Cela donne une image de la sortie réelle de Figma à placer dans les vérifications et le registre.

Livre de règles

Le fichier de démarrage est dans design/rulebook/rules.yaml. Il est validé automatiquement par les commandes et chargé par fad check. Les trois niveaux sont :

• normative — les critères de réussite WCAG. failure si non respecté.
• heuristic — les directives de conception Apple et Material. concern si non respecté.
• house — les règles de cette compétence. deviation si non respecté.

Chaque règle a une rule_id comme WCAG-11, APPLE-TAPPING, MATERIAL-SPACING ou HOUSE-ONE-MAIN-ACTION. Les constatations dans checks/R-*/findings.json citent ces ID.

Les règles maison documentées dans CLAUDE.md (celles-ci, ainsi que les non négociables ci-dessus) :

1. HOUSE-BRIEF-BEFORE-DRAW — Aucun dessin tant que le brief n'est pas complet.
2. HOUSE-SCREEN-MAP — La cartographie des écrans est complète et vérifiable avant le dessin.
3. HOUSE-COMPLETE-STATES — Chaque écran avec des données a default, empty, loading, et error.
4. HOUSE-ONE-MAIN-ACTION — Une action principale par écran porte l'accent.
5. HOUSE-RECORD-REQUEST — Enregistrer la demande avant d'agir.
6. HOUSE-PALETTE-VARS — Toutes les couleurs sont des variables de palette.
7. HOUSE-FONT-VARS — Toutes les polices sont des variables type/.
8. HOUSE-NO-GUESS-LOGOS — Aucun logo réel sans approbation explicite.
9. HOUSE-NO-CODE — Aucun code d'application écrit.
10. HOUSE-NO-COPY — Aucune copie d'écrans à partir de modèles ou d'applications.

Registre

design/ledger.jsonl est un journal en ajout seul. Chaque ligne est un objet JSON avec un event (type), un timestamp, un data (quelconque) et un hash de la ligne précédente, de son propre contenu et de son horodatage. La commande fad ledger verify vérifie la chaîne.

Les événements incluent :

• brief.created — le brief a été initialisé.
• schema.confirmed — la personne a confirmé le livre de règles.
• screen.map — la cartographie des écrans a été définie.
• request.made — la personne a demandé quelque chose (texte textuel).
• figma.write — le dessin a été envoyé à Figma (ID de script, accusé de réception).
• check.run — une vérification a été effectuée (chemin vers le dossier de vérification).
• decision.recorded — une décision a été enregistrée (D-id).
• approval.recorded — une approbation a été enregistrée (uniquement par l'humain, A-id).
• tutorial.started — un tutoriel a été démarré.

Vérifications

À tout moment, Claude peut exécuter fad check sur un écran ou sur l'écran actuel. Cela :

1. Prend une capture d'écran de l'écran dans Figma (via get_screenshot).
2. Mesure chaque règle applicable par rapport au dessin.
3. Écrit checks.json (les métriques brutes) et findings.json (les constatations formatées).
4. Enregistre l'événement check.run dans le registre.

Les constatations sont classées comme failure, concern ou deviation selon le niveau de la règle, comme décrit ci-dessus. Les constatations heuristiques n'utilisent jamais d'icônes ou de mots de type réussite/échec ; elles sont concern avec une description.

Briefs de construction (Transfert)

Lorsqu'une décision est approuvée (fad approve D-id exécuté par l'humain), la compétence génère design/handoff/D-NNNN.md. Ce fichier contient :

• Le nom de l'application et le brief d'une ligne.
• La plateforme et la pile.
• Les écrans approuvés et leurs états.
• Les captures d'écran de Figma (liées ou encodées en base64).
• Le jeu de couleurs et le mode.
• Toute constatation ou déviation connue.
• La cible de conformité (WCAG 2.2 AA).
• Les règles partagées du README.md du dossier de transfert.

Ce fichier est destiné à être transmis à Claude Code ou Codex dans une session séparée, avec la consigne : "Construis cette application en te basant sur ce brief."

Tutoriels pour les applications courantes

Des tutoriels prêts à l'emploi existent pour to-do, weather et chat. Ils fournissent un exemple de brief, une cartographie des écrans proposée et des wireframes de départ. Utilisez fad init "<nom>" --tutorial to-do pour commencer. Le tutoriel guide l'utilisateur à travers les phases de cette compétence, étape par étape, avec moins de questions et plus de dessin.

Utilisation de l'IA et limites

Cette compétence est conçue pour fonctionner avec les outils MCP Figma disponibles. Si les outils sont manquants, elle fonctionne en mode "JSON uniquement", produisant le brief, la cartographie et les décisions, mais pas les dessins Figma. Le mode est enregistré dans capabilities.json. La compétence ne peut pas effectuer de vérifications sans capture d'écran de Figma.

Sécurité et permissions

• Aucun code d'application n'est écrit, donc aucune faille de sécurité d'application n'est introduite.
• Les noms de fichiers et de répertoires sont tirés du nom de l'application fourni par l'utilisateur.
• Les approbations sont protégées par la règle non négociable 1 : seul un humain peut les définir.
• Les logos réels ne sont jamais utilisés sans autorisation explicite.
• Le registre est un fichier local, pas un service externe.

Résumé des phases

1. Phase 0 — Brief (Porte G0) : Remplir le brief.
2. Phase 1 — Livre de règles (Porte G1) : Confirmer les règles.
3. Phase 2 — Cartographie des écrans : Définir les écrans et les liens.
4. Phase 3 — Dessiner les wireframes : Dessiner des wireframes en niveaux de gris dans Figma.
5. Phase 4 — Styliser : Appliquer le jeu de couleurs, les polices et les états.
6. Phase 5 — Vérifier : Exécuter les vérifications et signaler les constatations.
7. Phase 6 — Décider : Enregistrer les décisions et obtenir les approbations.
8. Phase 7 — Transférer : Générer les briefs de construction pour les designs approuvés.