Chaque export figmascope commence par un .zip contenant sept artefacts. CONTEXT.md est celui qui est lu en premier — intentionnellement. Ce n'est pas un README. Ce ne sont pas des docs générées. C'est un contrat de type compilateur entre le design et l'agent qui va le transformer en code.

Cet article détaille son contenu, la raison de sa structure et ce qui se passe quand on l'ignore.

Ce que ressemble un contrat vs. de la documentation

La documentation décrit ce qui existe. Un contrat spécifie ce qui doit être vrai. Cette distinction importe quand votre lecteur est un LLM qui inventera allègrement des valeurs d'espacement, aplatira des hiérarchies de mise en page ou codifiera en dur des couleurs hex dès qu'il n'a pas de meilleure option.

CONTEXT.md s'ouvre sur une déclaration de cible :

# CONTEXT.md — Jetpack Compose target

This file is the authoritative spec for generating UI code from this bundle.
Read it before reading any other file.

La mention « Jetpack Compose target » n'est pas décorative. L'agent l'utilise pour choisir les primitives composables, gérer les unités dp vs sp, savoir que Modifier.padding() est la bonne abstraction pour l'espacement, et comprendre que Box avec Alignment est la façon de gérer les mises en page superposées. Une cible React/Tailwind génère un CONTEXT.md différent avec des primitives différentes dans les contraintes.

L'instruction « lire ceci en premier » est également intentionnelle. Les agents traitent le contexte de manière séquentielle. Si une règle de token apparaît après que l'agent a déjà commencé à raisonner sur un composant, la contrainte arrive trop tard. Mettre le contrat en tête signifie que les règles sont actives dès le premier token de génération.

La section des contraintes strictes

La partie la plus essentielle de CONTEXT.md est le bloc de contraintes :

## Strict constraints (must follow)

- Never hardcode dp values if a token exists within ±2dp
- Never flatten layout hierarchy — preserve every stack/overlay/absolute node
- Use stringRef values from strings.json, never inline literal text
- Treat missing fields as absent, not zero
- Do not invent component names not present in components/inventory.json

Chaque contrainte existe parce que nous avons observé des agents la violer. La règle du ±2dp en est l'exemple le plus clair. Sans elle, un agent rencontrant un gap: 14 sur un nœud de pile écrira Arrangement.spacedBy(14.dp). Avec la règle, il sait vérifier si spacing.16 ou spacing.12 est dans les 2dp et utiliser le token à la place. Le résultat est différent — un résultat qui reste cohérent quand la valeur du token change, l'autre non.

La règle de hiérarchie existe parce que Compose est un arbre de mise en page. Quand un agent aplatit une pile imbriquée en une liste plate d'éléments positionnés, il détruit le comportement responsive implicite de la structure d'origine. L'IR préserve chaque niveau d'imbrication pour une raison — voir IR par écran — Stack, Overlay, Absolute, Leaf pour la façon dont cette imbrication encode l'intention de mise en page.

La contrainte ne dit pas « utiliser les tokens si vous en avez envie ». Elle dit « ne jamais coder en dur si un token existe ». C'est une interdiction, pas une suggestion. Les LLM réagissent différemment aux interdictions qu'aux suggestions.

La règle stringRef importe pour l'i18n. Si un agent inscrit "Speed Test" en dur au lieu de référencer la clé de ressource, vous avez créé un trou de localisation. La contrainte pointe l'agent vers strings.json explicitement.

Comment l'agent lit CONTEXT.md séquentiellement

Les fenêtres de contexte des LLM traitent les tokens de gauche à droite. La structure de CONTEXT.md exploite cela. L'ordre est le suivant :

  1. Déclaration de cible (définit le cadre de génération entier)
  2. Contraintes strictes (interdictions qui s'appliquent à chaque décision)
  3. Carte du bundle (quels fichiers existent et ce que chacun contient)
  4. Règles d'utilisation des tokens (comment résoudre espacement, couleur, rayon, typographie)
  5. Notes de portée (lacunes honnêtes — ce que ce bundle couvre et ne couvre pas)

La section de carte du bundle indique à l'agent quels fichiers lire et dans quel ordre :

## Bundle contents

- tokens.json — design tokens (spacing, radius, color, typography)
- screens/*.json — per-screen IR in stack/overlay/absolute/leaf format
- components/inventory.json — component identity list
- strings.json — i18n resource keys
- _meta.json — generation metadata and warnings

Sans cette carte, un agent pourrait ignorer l'existence de components/inventory.json, ou traiter _meta.json comme la spec principale. L'énumération explicite guide l'ordre de lecture.

Notes de portée — ce que la v0.4 ne couvre honnêtement pas

La section des notes de portée est l'endroit où figmascope documente ses propres limites. C'est délibéré et non négociable. Un agent qui ne sait pas qu'une spec est incomplète comblera les lacunes avec confiance par invention. C'est pire que de connaître la lacune.

## Scope notes (v0.4)

- Gradient fills are not supported. Nodes with gradient fills emit a warning
  in _meta.json under warnings. Treat as a solid fill approximation or TODO.
- Typography tokens require Figma Variables to be populated. If tokensSource
  is "inferred-from-frequency" or "none", typography coverage may be partial.
- This bundle covers UI structure only. Navigation, state management,
  and network calls are outside scope.
- Component instances are identified by componentId. Full component
  source props are not included — the inventory gives identity, not implementation.

L'avertissement sur les dégradés est particulièrement important. Figma prend en charge des remplissages en dégradé complexes qui n'ont pas d'équivalent direct dans Compose sans dessin personnalisé. Plutôt que de supprimer silencieusement les dégradés ou de générer du code cassé, figmascope émet un avertissement background-gradient-not-supported:<name> dans _meta.json et le note ici pour que l'agent sache traiter les nœuds affectés comme une lacune connue plutôt qu'un bug dans sa propre sortie.

La note typographique est liée au champ tokensSource dans _meta.json. Quand un fichier Figma n'a pas de Variables, figmascope infère les tokens par fréquence — les valeurs courantes deviennent des tokens, les rares non. La note de portée indique à l'agent que cette inférence est imparfaite et de ne pas supposer une couverture typographique complète. Voir tokens.json expliqué pour le fonctionnement du mécanisme de repli par inférence.

Exemples FAUX / JUSTE

Rendons cela concret. Étant donné un nœud de pile avec gap: 16 et un fichier de tokens contenant spacing.16: 16 :

Sans les contraintes de CONTEXT.md (FAUX) :

Column(
    modifier = Modifier.padding(horizontal = 24.dp),
    verticalArrangement = Arrangement.spacedBy(16.dp)
) {

Avec les contraintes de CONTEXT.md (JUSTE) :

Column(
    modifier = Modifier.padding(horizontal = Spacing.spacing24),
    verticalArrangement = Arrangement.spacedBy(Spacing.spacing16)
) {

La sortie JUSTE référence les tokens. Quand le système de design modifie spacing.16 de 16dp à 14dp, le code reste correct sans recherche-remplacement dans la base de code.

Autre exemple — la gestion des chaînes. Étant donné un nœud feuille avec text: "Speed Test" et stringRef: "speed.test" :

FAUX :

Text(text = "Speed Test")

JUSTE :

Text(text = stringResource(R.string.speed_test))

La contrainte pointe vers strings.json, la clé est speed.test, et l'agent sait comment mapper la notation pointée vers les identifiants de ressources Android. Cela n'est possible que si l'agent a lu la contrainte avant de générer le composant.

Pourquoi ne pas simplement prompter l'agent vous-même ?

Vous pouvez écrire ces instructions manuellement dans votre prompt. figmascope les externalise dans un fichier parce que :

L'objectif n'est pas de contourner les comportements par défaut de l'agent par prompt engineering. C'est de livrer une spec qui rend ces comportements par défaut sans objet.

Structure comparée aux alternatives

Le Dev Mode de Figma génère des mesures, des variables et des extraits de code. Il ne produit pas de spec. L'agent utilisant la sortie du Dev Mode doit inférer des règles à partir d'exemples — ce qui signifie qu'il inférera de mauvaises règles pour les cas limites.

Locofy et outils similaires génèrent du code directement. Ils n'ont pas d'équivalent à CONTEXT.md parce qu'ils n'attendent pas qu'un agent lise une spec — ils s'attendent à être l'agent. Cela fonctionne quand la génération de code de l'outil correspond exactement à votre stack. Cela ne fonctionne pas quand vous avez des conventions de nommage spécifiques au projet, une bibliothèque de composants personnalisée, ou un système de design avec des tokens que l'outil ne connaît pas.

CONTEXT.md est un brief de design lisible par machine. C'est la chose qui existait sous forme de page Confluence ou de doc Notion dans chaque passation de design pré-LLM, simplement structurée pour un public qui suit réellement les règles.

Comment l'utiliser

Quand vous ouvrez un export figmascope dans Cursor ou Claude Code :

  1. Ajoutez @CONTEXT.md à votre contexte avant tout prompt sur le design.
  2. Référencez le JSON d'écran sur lequel vous travaillez : @screens/home.json.
  3. Si vous touchez aux tokens, ajoutez @tokens.json.
  4. Si vous travaillez avec des chaînes, ajoutez @strings.json.

Les contraintes de CONTEXT.md s'appliquent à toute la session une fois chargées. Vous ne le rajoutez pas par prompt — vous l'ajoutez une fois au début et laissez-le encadrer chaque génération suivante.

Les autres artefacts du bundle sont couverts dans le reste de cette série. Commencez par tokens.json expliqué pour voir comment le système de tokens gère les fichiers avec et sans Figma Variables, ou IR par écran pour la façon dont les mises en page Figma se mappent en nœuds stack/overlay/absolute/leaf. Prêt à essayer ? Collez votre URL Figma sur figmascope.dev et exportez votre premier bundle.