Una fuente, varios destinos

Cada herramienta lee las reglas del sistema en un sitio distinto: el agente de Figma, en las guidelines; Claude Code, en el repositorio; Claude Design, en el sistema publicado. Si escribes una versión para cada una, acabarán diciendo cosas distintas. Esta página propone escribir una vez y publicar en cada destino.

En esta página

• Los destinos
• La carpeta docs como fuente
• Qué va a cada destino
• Generar las guidelines de Figma
• En resumen

Los destinos

La carpeta docs como fuente

Qué va a cada destino

• Guidelines de Figma: las reglas que afectan al diseño (fundamentos, antipatrones, patrones), agrupadas en pocos archivos. No las props: el agente de Figma trabaja con los componentes de la librería, no con el código.
• Instrucciones de Code Connect: dos o tres líneas por componente con lo que un agente de código necesita al implementarlo, sacadas de la sección Reglas de su documento. Lo vemos en Instrucciones para el MCP.
• CLAUDE.md o AGENTS.md: las reglas que valen siempre y un mapa de la carpeta docs/, no los documentos enteros. Claude Code permite importar archivos con @ruta, pero los archivos importados se cargan al empezar la sesión y no reducen el coste de contexto (Claude Code: Memory). Mejor enlazar las rutas y dejar que el agente abra lo que necesite (capítulo 6).
• Sistema de diseño en Claude: el repositorio con los componentes y la documentación, como una de sus fuentes. Si los componentes son de React, /design-sync desde Claude Code lee los tokens y los componentes directamente (Claude Help: Set up your design system).
• Storybook: si usas su MCP, el manifiesto de documentación solo recoge lo que está escrito en los archivos MDX, no valores importados de otros archivos (Storybook: Best practices).

Generar las guidelines de Figma

Mientras las guidelines estén en beta, los archivos se suben a mano (Figma: About guidelines). Un script puede prepararlos desde docs/ y comprobar el tamaño:

// Junta docs/ en los archivos que se suben a Figma (Library → Manage guidelines…).
import fs from 'node:fs';
import path from 'node:path';

const OUT = 'dist/figma-guidelines';
const groups = {
  'overview.md': ['docs/foundations'],
  'rules.md': ['docs/rules'], // reglas transversales y anti-patterns.md
  'patterns.md': ['docs/patterns'],
  'content.md': ['docs/content'],
};

const read = (p) =>
  fs.statSync(p).isDirectory()
    ? fs.readdirSync(p).filter((f) => f.endsWith('.md')).sort().map((f) => read(path.join(p, f))).join('\n\n')
    : fs.readFileSync(p, 'utf8').replace(/^---\n[\s\S]*?\n---\n/, ''); // sin frontmatter

fs.mkdirSync(OUT, { recursive: true });
let total = 0;
for (const [file, sources] of Object.entries(groups)) {
  const text = sources.map(read).join('\n\n');
  fs.writeFileSync(path.join(OUT, file), text);
  total += Buffer.byteLength(text);
}
console.log(`Guidelines: ${(total / 1024).toFixed(1)} KB`);
if (total > 100 * 1024) process.exitCode = 1; // Figma recomienda menos de 100 KB

El script es un ejemplo: ajusta los grupos a tu carpeta docs/. Lo importante es el orden de trabajo: se cambia docs/, se genera, se sube.

Fuentes

• Figma: About guidelines
• Figma: Code Connect integration
• Claude Code: How Claude remembers your project
• Claude Code: Extend Claude with skills
• Claude Help: Set up your design system in Claude Design
• Claude Help: How can I create and manage projects
• Storybook: Best practices for using Storybook with AI