Del diseño al código: qué le importa realmente a un desarrollador de tu design system

La mayoría de los design systems fracasan por la misma razón: están hechos para que los diseñadores trabajen cómodos, pero los desarrolladores tienen que interpretar, traducir y adaptar cada componente antes de escribir una línea de código. El resultado es predecible: componentes que se parecen al diseño pero funcionan distinto, props que no existían en Figma y variantes que aparecen porque "había que resolver esto de alguna forma".

Un design system útil se mide por cuánto reduce las decisiones arbitrarias del equipo de desarrollo. Si tu sistema de diseño obliga a los devs a preguntarse "¿y esto cómo se implementa?", entonces el problema no está en el código, está en la documentación y la estructura.

Tokens que se puedan exportar, no colores bonitos

Los tokens de diseño son variables. Punto. Si un desarrollador ve en Figma un color llamado Brand/Primary/Default pero en el código tiene que escribir #4A90E2, algo salió mal desde el principio.

Lo que realmente importa:

• Nomenclatura consistente: los nombres de los tokens deben ser idénticos en Figma y en el código. Si cambiás "primary" por "main" en algún lugar, ya generaste fricción.
• Estructura de categorías: semántica antes que estética. Preferí color.text.primary a color.gray.800.
• Export automatizado: plugins como Tokens Studio o herramientas como Style Dictionary permiten sincronizar tokens desde Figma a JSON, CSS o archivos de configuración de Tailwind.

Un token bien definido permite esto:

:root {
  --color-text-primary: #1a1a1a;
  --color-text-secondary: #666666;
  --spacing-sm: 8px;
  --spacing-md: 16px;
}

Y esto en el código:

<button className="bg-primary text-white py-spacing-sm px-spacing-md">
  Enviar
</button>

Sin intermediarios. Sin traducciones. Sin decisiones sobre la marcha.

Componentes con props definidas, no artboards infinitos

Un componente en Figma debería tener la misma lógica que un componente en React, Vue o cualquier framework. Cada variante visible tiene que corresponder a una prop específica. Si el desarrollador tiene que adivinar cuándo usar size="large" o variant="primary", el design system no está haciendo su trabajo.

Ejemplo práctico: un botón con estas variantes en Figma.

• Default, Hover, Disabled
• Primary, Secondary, Outline
• Small, Medium, Large

Esto debería traducirse a:

interface ButtonProps {
  variant: 'primary' | 'secondary' | 'outline';
  size: 'small' | 'medium' | 'large';
  disabled?: boolean;
}

Nada más. Nada menos. Si en Figma tenés 20 versiones del mismo botón pero no están organizadas por propiedades, el desarrollador va a implementar lo que entienda, no lo que diseñaste.

Espaciado y layout: grillas que se puedan replicar

La distancia entre elementos no puede ser una intuición. Si un card tiene 24px de padding en Figma pero el desarrollador pone 20px "porque se ve bien", el sistema dejó de ser sistema.

Lo que los devs necesitan:

• Tokens de espaciado: 4px, 8px, 16px, 24px, 32px. Nada intermedio. Nada de 18px o 22px salvo que exista una razón documentada.
• Grillas explícitas: si usás un layout de 12 columnas, decilo. Si hay un gap de 16px entre columnas, especificalo.
• Auto-layout en Figma mapeado a Flexbox o Grid: si configurás auto-layout con space-between en Figma, el desarrollador debería saber que eso se traduce a justify-content: space-between.

Ejemplo:

.card {
  padding: var(--spacing-md);
  gap: var(--spacing-sm);
  display: flex;
  flex-direction: column;
}

Si esto está documentado en Figma con las mismas propiedades, el código prácticamente se escribe solo.

Tipografía: no tamaños aislados, sino jerarquías

Los desarrolladores no quieren 15 estilos de texto distintos. Quieren una jerarquía clara con nombres que signifiquen algo.

Mal:

• Title Bold 32
• Subtitle Regular 24
• Body Medium 16
• Small Text 14

Bien:

• heading/h1
• heading/h2
• body/default
• body/small

Con esta estructura, un desarrollador puede hacer:

<h1 className="text-heading-h1">Título principal</h1>
<p className="text-body-default">Este es el contenido.</p>

Y sabe que está respetando el sistema sin buscar en mil artboards cuál es el tamaño correcto.

Estados interactivos: documentados, no imaginados

Hover, focus, active, disabled. Cada estado debe estar especificado en Figma y cada uno debe tener un equivalente en código. Si el hover de un botón primario cambia el fondo a primary-dark, ese token tiene que existir.

Ejemplo de documentación útil:

• Default: background: var(--color-primary)
• Hover: background: var(--color-primary-dark)
• Focus: outline: 2px solid var(--color-focus)
• Disabled: background: var(--color-neutral-200), cursor: not-allowed

Sin esto, el desarrollador va a poner lo que crea conveniente. Y probablemente no sea lo que diseñaste.

Responsive: breakpoints compartidos

Si el diseño tiene breakpoints en 768px, 1024px y 1440px, esos mismos valores tienen que estar en el código. No hay lugar para interpretaciones.

const breakpoints = {
  mobile: '320px',
  tablet: '768px',
  desktop: '1024px',
  wide: '1440px',
};

Y en Figma, los frames deberían estar configurados con esos mismos anchos. Así, cuando el desarrollador recibe un diseño mobile, sabe exactamente en qué breakpoint aplicar esos estilos.

Documentación técnica: specs que se puedan copiar

Los desarrolladores no necesitan descripciones largas sobre "la filosofía del botón". Necesitan specs técnicas que puedan copiar directo al código.

Herramientas útiles:

• Figma Inspect panel: asegurate de que los valores de espaciado, tipografía y colores sean copiables.
• Storybook: cada componente documentado con sus props, estados y ejemplos de uso.
• README por componente: una descripción breve de cuándo usar el componente, qué props acepta y ejemplos de código.

Ejemplo de documentación mínima viable:

## Button

### Props
- variant: 'primary' | 'secondary' | 'outline'
- size: 'small' | 'medium' | 'large'
- disabled: boolean

### Uso
<Button variant="primary" size="medium">Click aquí</Button>

Eso es suficiente. Todo lo demás es ruido.

Versionado: cambios claros, no sorpresas

Si cambiás el padding de un componente o el color de un token, los desarrolladores tienen que saberlo. Un sistema sin changelog es un sistema impredecible.

Cada cambio en el design system debería estar documentado con:

• Qué cambió: "El espaciado interno de los botones pasó de 12px a 16px"
• Por qué cambió: "Para mejorar la accesibilidad en mobile"
• Cómo migrar: "Reemplazá padding: var(--spacing-sm) por padding: var(--spacing-md)"

Git para los componentes, versiones semánticas para los paquetes de tokens. Nada de "actualizamos el Figma, fijate qué cambió".

El puente entre diseño y desarrollo

Un design system no es un archivo de Figma. Es un contrato entre diseño y desarrollo que dice: si respetás estas reglas, tu producto va a ser consistente, escalable y mantenible.

Los desarrolladores no odian a los diseñadores. Odian tener que inventar soluciones para problemas que el sistema debería haber resuelto. Si tu Figma tiene 80 variantes de un botón pero ninguna explicación de cuándo usar cada una, el sistema no está ayudando, está generando más trabajo.

La clave está en pensar cada componente, token y espaciado como si lo tuvieras que implementar vos mismo. Si te resulta confuso a vos, va a ser imposible para quien tenga que traducirlo a código.

Un buen design system no necesita reuniones de aclaración. Se entiende solo.