Figma a Claude Code — Contexto Estructurado para el CLI de Anthropic

La instrucción "no reimplementar componentes que ya existen" importa cuando el inventario de componentes es compartido. Claude Code puede leer design/components/inventory.json para identificar qué componentes ya están implementados e importarlos en lugar de regenerarlos.

Conectar los design tokens

El tokens.json exportado por figmascope usa una estructura anidada al estilo W3C con campos $value y $type:

{
  "color": {
    "surface":    { "$value": "#f6f2ea", "$type": "color" },
    "ink":        { "$value": "#1f1d1a", "$type": "color" },
    "accent":     { "$value": "#d96a3a", "$type": "color" }
  },
  "spacing": {
    "1": { "$value": "4px",  "$type": "dimension" },
    "2": { "$value": "8px",  "$type": "dimension" },
    "4": { "$value": "16px", "$type": "dimension" },
    "8": { "$value": "32px", "$type": "dimension" }
  },
  "typography": {
    "body": {
      "fontFamily": { "$value": "Inter",  "$type": "fontFamily" },
      "fontSize":   { "$value": "14px",   "$type": "dimension" },
      "lineHeight": { "$value": 1.45,     "$type": "number" }
    }
  }
}

Pídele a Claude Code que genere un bloque de extensión de tema en tailwind.config.ts desde este archivo como primer paso, antes de implementar cualquier pantalla. Así todas las implementaciones posteriores pueden usar los alias de tokens de Tailwind de forma consistente:

claude --print "Read design/tokens.json and generate a tailwind.config.ts
theme.extend block. Map color tokens to theme.extend.colors,
spacing tokens to theme.extend.spacing, and typography to
theme.extend.fontFamily / fontSize. Output only the config object."

Consulta Exportación de Design Tokens para Agentes de IA para un análisis profundo del formato de tokens y el mecanismo de inferencia por frecuencia que usa figmascope cuando las Variables de Figma no están configuradas.

Gestionar la capa de cadenas de texto

Cada nodo de texto del archivo de Figma tiene una entrada en strings.json. Las claves usan notación de punto derivada de la jerarquía de frames:

{
  "home.hero.title":        "Everything you need",
  "home.hero.subtitle":    "Ship faster with structured context",
  "home.cta.primary":      "Get started",
  "settings.account.heading": "Account settings"
}

Indica a Claude Code que use estas claves como identificadores i18n. En lugar de codificar la cadena "Everything you need" en JSX, el componente generado llama a t('home.hero.title') (o el equivalente de tu librería i18n). El archivo de recursos ya está en strings.json — solo necesitas importarlo o conectarlo a tu configuración i18n.

Si figmascope detecta una colisión — dos nodos que producen la misma clave — emite una advertencia strings-collision en _meta.json y añade un sufijo numérico para disambiguar. Comprueba _meta.json antes de iniciar una sesión para saber qué esperar.

Integración con CLAUDE.md

Si usas un archivo de contexto de proyecto CLAUDE.md, añade una sección corta que apunte al agente al directorio de diseño. Esto encaja bien con el enfoque descrito en AI Design Handoff y complementa la explicación de por qué figmascope difiere de los plugins de inspección de Figma.

Añade una sección de diseño como esta:

## Design context

Design tokens, layout IR, reference renders, and strings live in `design/`.
Always read `design/CONTEXT.md` before implementing any screen.
Token values are in `design/tokens.json` — never hardcode color or spacing.
Component canonical names are in `design/components/inventory.json`.

Esto significa que cada sesión de Claude Code en el proyecto tendrá automáticamente el contexto de diseño como parte de su conocimiento de trabajo, sin que tengas que repetirlo en cada prompt.

Lo que el agente acierta con contexto estructurado

Con contexto estructurado, Claude Code acierta de forma fiable en:

• Valores de espaciado — porque están en tokens.json como spacing.4 → 16px, no estimados desde una captura de pantalla
• Colores — valores hexadecimales exactos, no "parece naranja cálido"
• Tipografía — familia tipográfica, tamaño, peso, interlineado, todo tipado
• Dirección de layout — los nodos stack tienen un campo explícito direction y gap
• Nombres de componentes — inventory.json es la fuente canónica, sin nombres inventados
• Textos — strings.json evita que el agente parafrasee o invente texto de relleno

Lo que aún necesita revisión humana: estados de interacción (hover, focus, active) que no son visibles en frames estáticos de Figma, timing de animaciones, y breakpoints responsive que no se diseñaron explícitamente en el archivo. El IR captura layout estático; el comportamiento dinámico queda fuera del alcance.

Usar --dangerously-skip-permissions en entornos controlados

Para pipelines automatizados donde quieres que Claude Code opere sin prompts de aprobación interactivos — por ejemplo en un paso de CI que genera stubs de componentes tras una actualización de diseño — puedes usar --dangerously-skip-permissions. Solo apropiado en entornos aislados sin credenciales de producción.

claude --dangerously-skip-permissions --print "$(cat <<'EOF'
Read design/CONTEXT.md. Generate component stub files for any components
in design/components/inventory.json that don't already exist in src/components/.
Use TypeScript + React functional component format. Include a TODO comment
for each component referencing the relevant screen JSON.
EOF
)"

En flujos de trabajo de desarrollo en producción, deja los permisos en modo interactivo. Los prompts existen por buenas razones — Claude Code puede y va a escribir archivos, y conviene saber cuáles antes de que lo haga.

Revisar las advertencias de exportación antes de hacer el prompt

figmascope emite advertencias en _meta.json para condiciones que pueden afectar la calidad del output. Revísalas antes de iniciar una sesión de Claude Code:

python3 -c "
import json
meta = json.load(open('design/_meta.json'))
for w in meta.get('warnings', []):
    print(f\"{w['code']}: {w['message']}\")
print(f\"Frames exported: {meta['frameCount']}\")
print(f\"Tokens source: {meta.get('tokensSource', 'variables')}\")
"

Dos advertencias a las que prestar atención:

• layout-mode-none-inferred — un frame no tenía auto-layout configurado. figmascope infirió el layout a partir de posiciones absolutas de los hijos, lo cual es menos fiable. Señala la pantalla relevante en tu prompt: "Esta pantalla usa posicionamiento absoluto; genera en consecuencia."
• strings-collision — dos nodos de texto produjeron la misma clave de recurso. figmascope lo disambigua con un sufijo numérico, pero deberías verificar que las cadenas en strings.json son correctas antes de que el agente genere llamadas i18n.

Flujos de trabajo para Android e iOS

Claude Code no se limita a frameworks web. El bundle de contexto es agnóstico al framework — el IR de layout y los tokens son datos, no CSS. Para Jetpack Compose:

claude --print "$(cat <<'EOF'
Read design/CONTEXT.md and design/tokens.json.

Implement design/screens/Home.json as a Jetpack Compose screen.
- Map color tokens to a MaterialTheme ColorScheme
- Map spacing tokens to Dp values (strip 'px' suffix, use .dp)
- Map typography tokens to MaterialTheme.typography
- Use the component names from design/components/inventory.json as Composable names
- Reference design/screens/Home.png for visual accuracy
EOF
)"

Los nodos stack del IR se mapean naturalmente a Column (direction: vertical) y Row (direction: horizontal) en Compose. Los nodos leaf con type: "text" se convierten en composables Text; type: "image" se convierte en Image o un marcador de posición. Consulta Jetpack Compose desde Figma para el patrón completo.

Versionar el bundle de diseño

Trata el directorio design/ como cualquier otra dependencia del proyecto. Cuando el diseño cambia significativamente, vuelve a exportar desde figmascope.dev, haz commit y anota el cambio en el PR:

# Check when the bundle was last exported vs when Figma file was last modified
python3 -c "
import json
from datetime import datetime
meta = json.load(open('design/_meta.json'))
exported = datetime.fromisoformat(meta['exportedAt'].replace('Z', '+00:00'))
modified = datetime.fromisoformat(meta['figmaLastModified'].replace('Z', '+00:00'))
delta = modified - exported
if delta.total_seconds() > 0:
    print(f'WARNING: Figma file was modified {delta} after last export')
else:
    print('Bundle is current')
"

Un bundle desactualizado significa que el agente está trabajando con un diseño obsoleto. La comprobación del timestamp lo detecta antes de que inviertas tiempo en una sesión de generación de código basada en especificaciones superadas.