Cada exportación de figmascope comienza con un .zip que contiene siete artefactos. CONTEXT.md es el que se lee primero — intencionadamente. No es un README. No son documentos generados. Es un contrato estilo compilador entre el diseño y el agente que lo convertirá en código.

Este artículo explica qué contiene, por qué está estructurado así y qué falla cuando lo omites.

La diferencia entre un contrato y documentación

La documentación describe lo que existe. Un contrato especifica lo que debe ser cierto. Esa distinción importa cuando tu lector es un LLM que inventará valores de espaciado, aplanará jerarquías de layout o codificará colores hexadecimales en cuanto no tenga una opción mejor.

CONTEXT.md se abre con una declaración de objetivo:

# 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.

El "Jetpack Compose target" no es decorativo. El agente lo usa para elegir primitivos componibles, gestionar unidades dp frente a sp, saber que Modifier.padding() es la abstracción correcta para el espaciado y entender que Box con Alignment es la forma de manejar layouts superpuestos. Un objetivo React/Tailwind genera un CONTEXT.md diferente con primitivos distintos en las restricciones.

La instrucción "lee esto primero" también es intencional. Los agentes procesan el contexto secuencialmente. Si una regla de token aparece después de que el agente ha comenzado a razonar sobre un componente, la restricción llega demasiado tarde. Poner el contrato al frente significa que las reglas están activas desde el primer token de generación.

La sección de restricciones estrictas

La parte más fundamental de CONTEXT.md es el bloque de restricciones:

## 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

Cada restricción existe porque hemos visto a agentes violarla. La regla ±2dp es el ejemplo más claro. Sin ella, un agente que encuentra un gap: 14 en un nodo de pila escribirá Arrangement.spacedBy(14.dp). Con la regla, sabe que debe comprobar si spacing.16 o spacing.12 están dentro de 2dp y usar el token en su lugar. Eso produce una salida diferente — una que sigue siendo coherente cuando cambia el valor del token.

La regla de jerarquía existe porque Compose es un árbol de layout. Cuando un agente aplana una pila anidada en una lista plana de elementos posicionados, destruye el comportamiento responsive implícito en la estructura original. El IR preserva cada nivel de anidamiento por una razón — consulta IR por Pantalla — Stack, Overlay, Absolute, Leaf para entender cómo ese anidamiento codifica la intención del layout.

La restricción no dice "usa los tokens si te apetece." Dice "nunca codifiques directamente si existe un token." Es una prohibición, no una sugerencia. Los LLMs responden de forma diferente a las prohibiciones que a las sugerencias.

La regla de stringRef importa para la i18n. Si un agente inserta literalmente "Speed Test" en lugar de referenciar la clave de recurso, has creado un agujero de localización. La restricción apunta al agente explícitamente a strings.json.

Cómo el agente lee CONTEXT.md secuencialmente

Las ventanas de contexto de los LLMs procesan tokens de izquierda a derecha. La estructura de CONTEXT.md explota esto. El orden es:

  1. Declaración de objetivo (establece el marco completo de generación)
  2. Restricciones estrictas (prohibiciones que aplican a cada decisión)
  3. Mapa del bundle (qué archivos existen y qué contiene cada uno)
  4. Reglas de uso de tokens (cómo resolver espaciado, color, radio y tipografía)
  5. Notas de alcance (brechas honestas — qué cubre y qué no cubre este bundle)

La sección del mapa del bundle indica al agente qué archivos leer y en qué orden:

## 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

Sin este mapa, el agente podría no saber que existe components/inventory.json, o podría tratar _meta.json como la especificación principal. La enumeración explícita guía el orden de lectura.

Notas de alcance — qué no cubre honestamente la v0.4

La sección de notas de alcance es donde figmascope documenta sus propias limitaciones. Esto es deliberado e innegociable. Un agente que no sabe que una especificación está incompleta rellenará los huecos con inventiva. Eso es peor que conocer la brecha.

## 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.

La advertencia de degradados es especialmente importante. Figma admite rellenos de degradado complejos que no tienen equivalente directo en Compose sin dibujo personalizado. En lugar de descartar silenciosamente los degradados o generar código roto, figmascope emite una advertencia background-gradient-not-supported:<name> en _meta.json y la documenta aquí para que el agente trate los nodos afectados como un hueco conocido en lugar de un error en su propia salida.

La nota de tipografía conecta con el campo tokensSource en _meta.json. Cuando un archivo de Figma no tiene Variables, figmascope infiere tokens por frecuencia: los valores comunes se convierten en tokens, los raros no. La nota de alcance indica al agente que esta inferencia es imperfecta y que no asuma cobertura tipográfica completa. Consulta tokens.json Explicado para entender cómo funciona el fallback de inferencia.

Ejemplos INCORRECTO / CORRECTO

Concretemos. Dado un nodo de pila con gap: 16 y un archivo de tokens que contiene spacing.16: 16:

Sin restricciones de CONTEXT.md (INCORRECTO):

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

Con restricciones de CONTEXT.md (CORRECTO):

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

La salida CORRECTA referencia el token. Cuando el sistema de diseño cambia spacing.16 de 16dp a 14dp, el código sigue siendo correcto sin buscar y reemplazar en toda la base de código.

Otro ejemplo — manejo de cadenas. Dado un nodo hoja con text: "Speed Test" y stringRef: "speed.test":

INCORRECTO:

Text(text = "Speed Test")

CORRECTO:

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

La restricción apunta a strings.json, la clave es speed.test y el agente sabe cómo mapear la notación de puntos a IDs de recursos Android. Eso solo es posible si el agente leyó la restricción antes de generar el componente.

¿Por qué no simplemente instruir al agente tú mismo?

Puedes escribir estas instrucciones manualmente en tu prompt. figmascope las externaliza en un archivo porque:

El objetivo no es hacer ingeniería de prompts alrededor de los valores por defecto del agente. Es entregar una especificación que haga irrelevantes esos valores por defecto.

Comparación con alternativas

El modo Dev de Figma muestra medidas, variables y fragmentos de código. No produce una especificación. El agente que usa la salida del modo Dev tiene que inferir reglas a partir de ejemplos — lo que significa que inferirá reglas incorrectas para los casos extremos.

Locofy y herramientas similares generan código directamente. No tienen equivalente a CONTEXT.md porque no esperan que un agente lea una especificación — esperan ser el agente. Eso funciona cuando la generación de código de la herramienta coincide exactamente con tu stack. No funciona cuando tienes convenciones de nomenclatura específicas del proyecto, una biblioteca de componentes personalizada o un sistema de diseño con tokens que la herramienta desconoce.

CONTEXT.md es un briefing de diseño legible por máquina. Es lo que existía como página de Confluence o documento de Notion en cada handoff de diseño pre-LLM, solo que estructurado para una audiencia que realmente sigue las reglas.

Qué hacer con él

Cuando abres una exportación de figmascope en Cursor o Claude Code:

  1. Añade @CONTEXT.md a tu contexto antes de cualquier prompt sobre el diseño.
  2. Referencia el JSON de pantalla en el que trabajas: @screens/home.json.
  3. Si tocas tokens, añade @tokens.json.
  4. Si trabajas con cadenas, añade @strings.json.

Las restricciones de CONTEXT.md aplican durante toda la sesión una vez cargadas. No hay que volver a añadirlo por cada prompt — se añade una vez al inicio y enmarca cada generación posterior.

El resto de artefactos del bundle se cubren en el resto de esta serie. Empieza por tokens.json Explicado para entender cómo el sistema de tokens gestiona archivos con y sin Figma Variables, o IR por Pantalla para ver cómo los layouts de Figma se mapean a nodos stack/overlay/absolute/leaf. ¿Listo para probarlo? Pega tu URL de Figma en figmascope.dev y exporta tu primer bundle.