Tu sistema de diseño no vive en Figma en Markdown

El contenido del portfolio en texto estructurado para leerlo, compartirlo o usarlo como contexto en un asistente de IA.

_DESIGN SYSTEMS_

# Tu sistema de diseño no vive en Figma

Durante años hemos tratado Figma como la fuente de verdad y el código como su copia. Con agentes de IA escribiendo interfaz, ese modelo deja de funcionar. Esta es la alternativa que he implementado y probado: un sistema de diseño headless.

Javier González · 11 nov 2026 · 7 min de lectura

## El problema: dos sistemas que se parecen

En casi todos los equipos con los que he trabajado hay en realidad dos sistemas de diseño. Uno está en Figma: librerías, variables, componentes con sus variantes. El otro está en el código: tokens, componentes de React, historias de Storybook. Se parecen mucho, pero nadie puede garantizar que sean el mismo.

La distancia entre los dos se salva a mano. El diseñador entrega una pantalla, el desarrollador la interpreta, y en esa interpretación se decide otra vez lo que ya estaba decidido: qué variante es, qué espaciado, qué pasa cuando el texto no cabe. Cada entrega es una traducción, y cada traducción introduce pequeñas diferencias.

Mientras solo trabajaban personas, esto se sobrellevaba con conversación. Un desarrollador con dudas pregunta. Un agente de IA no pregunta: rellena el hueco con lo más probable. Si la regla no está escrita en un sitio que pueda leer, la inventa.

## La idea: el sistema es el contrato, no el archivo

Un sistema de diseño headless separa las decisiones de las herramientas donde se muestran. Las decisiones viven en un repositorio, en texto, con historial de cambios y revisión. Figma, React, Storybook, el gestor de contenidos y los agentes son consumidores de esas decisiones. Ninguno es el original.

«Descentralizado de Figma» no significa «sin Figma». Los diseñadores siguen diseñando allí, con componentes y variables reales. Lo que cambia es la dirección de la autoridad: cuando Figma y el repositorio no coinciden, hay una regla clara sobre cuál gana y un mecanismo que avisa.

## Las tres piezas del repositorio

### 1. Tokens

Las decisiones visuales básicas: color, tipografía, espaciado, radios, sombras. Se guardan en un formato estándar de design tokens y se transforman a lo que cada consumidor necesita: variables de Figma por un lado, propiedades CSS por otro.

El punto delicado es la sincronización. Tokens y variables de Figma tienen que estar conectados en los dos sentidos, pero con un único sentido que manda. Si un diseñador cambia una variable en Figma, eso es una propuesta de cambio al repositorio, no un cambio del sistema.

### 2. Contratos de componentes

Es la pieza que casi ningún sistema tiene y la que más cambia el resultado. Un contrato describe un componente de forma que una persona y una máquina lo entiendan igual.

La documentación tradicional explica el componente. El contrato lo delimita: dice qué está permitido, y por tanto permite comprobar automáticamente si un diseño o un fragmento de código lo cumple.

### 3. El mapa entre diseño y código

Cada componente de Figma tiene que saber cuál es su equivalente en código, y al revés. Sin ese mapa, un agente que recibe una pantalla ve rectángulos y texto. Con él, ve «un botón primario dentro de una tarjeta de producto», con sus propiedades.

## Conectado a Figma: validar y entregar

Con esas tres piezas, el trabajo dentro de Figma cambia en dos momentos.

**Antes de entregar, se valida.**: Un plugin compara el diseño con los contratos: componentes que no vienen del sistema, valores sueltos donde debería haber un token, variantes que no existen, estados que faltan. El diseñador lo ve mientras diseña, no tres semanas después en una revisión de código.

**Al entregar, se exporta estructura, no imágenes.**: En vez de capturas con medidas, la entrega es una descripción de la pantalla: qué componentes la forman, con qué propiedades y con qué contenido. De esa descripción salen directamente paquetes de React, historias de Storybook o el JSON que necesita el gestor de contenidos.

## Qué significa «preparado para IA»

Un agente necesita lo mismo que un desarrollador nuevo en su primer día, solo que por escrito y sin ambigüedad:
- **Contexto que pueda leer.**: Tokens y contratos en texto estructurado, no en capas de un archivo de diseño.
- **Reglas que pueda comprobar.**: Si el contrato dice que un botón primario solo aparece una vez por vista, eso se puede verificar.
- **Ejemplos.**: Uno correcto y uno límite enseñan más que tres párrafos de descripción.

Con esto el agente deja de adivinar. Construye con los componentes del sistema, no al margen de ellos, y lo que produce puede pasar por la misma validación que el trabajo de una persona.

No hace falta un sistema distinto para la IA. Preparar el sistema para agentes y ordenar la colaboración entre diseño y front resulta ser el mismo trabajo.

## Qué cambia para el equipo

- **Para diseño:**: menos libertad para improvisar valores y más certeza de que lo diseñado es construible. La validación llega mientras se trabaja.
- **Para front-end:**: la entrega deja de ser una interpretación. Llega estructura, y las dudas se resuelven en el contrato, no en un hilo de mensajes.
- **Para producto:**: las decisiones quedan escritas y versionadas. Se puede saber cuándo cambió una regla y por qué.

Lo que no cambia es quién decide. La IA explora, construye y comprueba; las personas revisan y deciden.

## Lo que todavía no está resuelto

Sería poco honesto presentar esto como terminado.
- **Los contratos hay que mantenerlos.**: Un contrato desactualizado es peor que ninguno, porque ahora hay una máquina que lo obedece.
- **La gobernanza importa más, no menos.**: Hay que decidir quién aprueba un cambio en un contrato y cómo se propone desde Figma.
- **Un piloto no es producción.**: Lo que cuento aquí está implementado y probado con un equipo de diseño y un equipo front-end. Escalarlo a toda una organización es otro problema.

## Por dónde empezar

No empieces por el sistema entero.
- **Elige un componente**: que aparezca en muchas pantallas.
- **Escribe su contrato**: con la plantilla que acompaña a este artículo.
- **Conéctalo:**: enlaza el componente de Figma con su equivalente en código y sus valores con tokens.
- **Pide a un agente que lo use**: en un flujo real y mira dónde toma una decisión que el contrato deja abierta.
- **Corrige el contrato,**: no el resultado. Luego pasa al siguiente componente.

Si después de cinco componentes la entrega entre diseño y front no es más corta, el problema está en otra parte y habrás gastado poco en averiguarlo.

Markdown

### Plantilla de contrato de componente

Un archivo Markdown para escribir tu primer contrato: propiedades, estados, tokens, accesibilidad, reglas comprobables, ejemplo y caso límite.

Descargar la plantilla (https://baguelus.com/recursos/plantilla-contrato-componente-es.md)