Sistemas de diseño que sobreviven al caos del cliente: tokens, variables y una entrega sin sorpresas

El feedback del cliente en la recta final no es un bug del proceso: es el proceso.

Si construyes sistemas de diseño para trabajo con clientes, ya conoces el patrón: el sistema se ve impecable en la semana tres, y luego llega la semana siete con “solo un botón especial”, una nueva landing “que no puede parecerse al resto” y un ejecutivo que quiere que el hero se sienta “más premium”. De repente, tu librería limpia de componentes se convierte en un museo de excepciones.

Este artículo es un playbook práctico para agencias para construir sistemas de diseño que sobreviven a múltiples stakeholders, múltiples herramientas y solicitudes de cambio en etapas tardías—sin convertir tu base de código en un cementerio de overrides puntuales.

Un sistema de diseño no es lo que entregas. Es lo que puedes seguir entregando cuando el cliente cambia de opinión.

---

Por qué el trabajo con clientes rompe los sistemas de diseño (y cómo planificarlo)

El caos del cliente no rompe los sistemas porque los clientes sean irracionales. Rompe los sistemas porque las agencias a menudo entregan sistemas que son:

• Asset-first (una librería de Figma) en lugar de contract-first (reglas claras que producción hace cumplir)
• Demasiado centrados en componentes antes de que las bases estén estables (tokens, escala tipográfica, espaciado)
• Poco documentados justo cuando más gente necesita claridad (handoff + QA)
• Sin gobernanza (sin versionado, sin ruta de revisión, sin un “no”) y por eso las variantes se multiplican

El impuesto del “caso especial” es real

Cada vez que aceptas un one-off sin una decisión a nivel de sistema, pagas:

1. Deuda de diseño: los diseñadores dejan de confiar en la librería porque la realidad se desvía.
2. Deuda de ingeniería: se acumulan overrides; los refactors dan miedo.
3. Deuda del cliente: el cliente aprende que “si lo pides lo bastante fuerte” crea nuevas variantes.

Conclusión concreta: trata cada solicitud como una de estas opciones:

• Un cambio de token (a nivel de sistema),
• Una variante de componente (reutilizable), o
• Una excepción específica de página (acotada en el tiempo, documentada y aislada de forma intencional).

Si no es una de esas, no es una solicitud: es ambigüedad.

---

Bases token-first (y errores comunes)

Los tokens son la única abstracción que sobrevive de forma fiable a los límites entre herramientas: Figma → CSS → Webflow → React/Vue → plantillas de email → páginas de marketing.

Pero la mayoría de equipos estructuran los tokens de una manera que vuelve la traducción un caos. La solución es separar qué es un valor de qué significa.

Usa un modelo de tokens de dos capas: primitivo + semántico

Los tokens primitivos son la paleta y las escalas en bruto.

• color.blue.500: #2563EB
• space.4: 16px
• font.size.2: 14px

Los tokens semánticos describen intención (y mapean a primitivos).

• color.text.default → color.neutral.900
• color.bg.surface → color.neutral.0
• color.border.subtle → color.neutral.200
• space.section.paddingY → space.12

Por qué esto importa en trabajo con clientes:

• Los clientes cambian colores de marca. Si dejaste “Primary Blue” hardcodeado, te toca refactorizar componentes.
• Los clientes agregan modo oscuro más tarde. Los tokens semánticos te permiten cambiar valores sin reescribir la UI.
• Se vuelve posible soportar múltiples productos/marcas bajo el paraguas de un mismo cliente sin duplicar librerías.

Si tus componentes referencian primitivos directamente, no tienes un sistema: tienes un tema.

Estructura de tokens que mapea limpio de Figma a producción

Una taxonomía práctica de tokens que funciona bien para agencias:

1. Color

   • Primitivos: color.neutral.*, color.brand.*, color.red.*
   • Semánticos: color.text.*, color.bg.*, color.border.*, color.action.*, color.feedback.*

2. Tipografía

   • Primitivos: font.family.*, font.size.*, font.weight.*, lineHeight.*, letterSpacing.*
   • Semánticos (recomendado): type.body.sm, type.body.md, type.heading.lg como estilos compuestos

3. Espaciado + tamaños

   • space.* para márgenes/padding
   • size.* para dimensiones fijas (avatares, iconos, contenedores)

4. Radio, sombra, motion

   • radius.*, shadow.*, motion.duration.*, motion.easing.*

Errores comunes de tokens que causan regresiones

• Nombrar tokens según la UI: color.buttonPrimary se vuelve una trampa cuando la marca agrega “secondary” y “tertiary”. Usa intención semántica.
• Sin capa semántica: los componentes apuntan a primitivos; cada cambio de marca dispara ediciones en componentes.
• Unidades inconsistentes: mezclar px, rem y valores arbitrarios rompe la previsibilidad.
• Demasiados pasos: una escala de espaciado de 24 pasos se siente “flexible” hasta que nadie sabe elegir el valor correcto.

Conclusión concreta: para espaciado, la mayoría de sistemas de agencia funcionan bien con 8–12 pasos (p. ej., base de 4px con algunos saltos más grandes). Que sea opinado.

Herramientas que vuelven real el flujo de tokens

• Figma Variables: trátalas como la fuente de verdad para tokens semánticos.
• Tokens Studio for Figma: útil cuando necesitas pipelines de exportación y gestión multi-tema.
• Style Dictionary (Amazon): una forma probada de compilar tokens a salidas CSS/JS/JSON.

Si trabajas mucho con Webflow, igual puedes mantener disciplina de tokens: los tokens se convierten en variables CSS en una hoja de estilos global y se referencian mediante clases utility o estilos de componentes.

---

Variables CSS + contratos de componentes (cómo evitar los “casos especiales”)

Los tokens solo funcionan si producción los hace cumplir. Tu capa de enforcement son las variables CSS y los contratos de componentes.

Estrategia de variables CSS: variables semánticas en el borde

Un patrón simple:

• Primitivos: --color-neutral-900, --space-4, --radius-2
• Semánticos: --text-default, --bg-surface, --border-subtle, --action-primary-bg

Luego los componentes solo usan variables semánticas:

• color: var(--text-default);
• background: var(--bg-surface);
• border-color: var(--border-subtle);

Cuando el cliente quiere un look “premium” nuevo, ajustas los mapeos semánticos—no 37 componentes.

Contratos de componentes: define lo permitido

Un contrato de componente es un acuerdo escrito y aplicado:

• Props/inputs (variantes, tamaños)
• Estados (hover, focus, disabled, loading)
• Requisitos de accesibilidad
• Reglas de uso de tokens (sin hex crudo, sin espaciado ad-hoc)

Ejemplo: Contrato de Button

• Variantes: primary | secondary | ghost | destructive
• Tamaños: sm | md | lg
• Estados: default | hover | active | focus-visible | disabled | loading
• Reglas:
  • El padding usa --space-*
  • El border radius usa --radius-*
  • El focus ring usa --focus-ring-color y --focus-ring-width

Conclusión concreta: si una solicitud no encaja en el contrato, dispara una decisión de sistema—no un override rápido.

Mata el “one-off” con un marco de decisión

Cuando alguien pide un caso especial, pásalo por esto:

1. ¿Es un token semántico nuevo? (p. ej., nuevo color de superficie para una campaña)
2. ¿Es una variante nueva? (reutilizable en al menos 2–3 lugares)
3. ¿Es específico de página y temporal? (override acotado con caducidad explícita)

Si no es ninguna de esas, probablemente es preferencia subjetiva. Haz pushback con opciones:

• “Podemos lograr esa sensación ajustando la superficie semántica + la rampa tipográfica (a nivel de sistema).”
• “Podemos agregar una variante ‘marketing’ para este componente, pero requerirá QA en breakpoints y estados.”
• “Podemos hacer una excepción de página, pero no estará soportada en plantillas futuras.”

Tu trabajo no es decir que no. Tu trabajo es hacer explícitos los tradeoffs.

La accesibilidad es parte del contrato, no un QA de último momento

El caos del cliente suele aparecer como “hazlo más claro” o “hazlo más sutil”, lo que puede destruir el contraste y los estilos de focus.

Incluye esto en los contratos:

• Objetivos mínimos de contraste (WCAG 2.2 AA por defecto)
• Estilos requeridos de :focus-visible (nunca se eliminan; solo se reestilizan)
• Mínimos de área clicable (44px para targets táctiles cuando aplique)
• Preferencias de motion (prefers-reduced-motion)

Herramientas que ayudan:

• Stark (Figma + navegador)
• axe DevTools
• Lighthouse

---

Flujo de handoff: docs, QA y ownership (la entrega “sin sorpresas”)

Un buen handoff no es “aquí está el Figma”. Es un mapa compartido de decisiones.

La regla de handoff de agencia: entrega el sistema como un producto

Trata el sistema de diseño como un entregable con:

• Un número de versión
• Notas de release
• Un changelog de actualizaciones de tokens y cambios de componentes
• Un único lugar donde vive la verdad (docs)

Así evitas que los hilos de Slack se conviertan en el sistema.

Qué documentar (documentación mínima viable del sistema)

No necesitas un sitio de 200 páginas. Necesitas claridad sobre:

1. Fundamentos

   • Listas de tokens (semánticos + primitivos)
   • Rampa tipográfica y guía de uso
   • Escala de espaciado y reglas de layout

2. Componentes

   • Variantes, estados y ejemplos de haz/no hagas
   • Notas de accesibilidad
   • Reglas de contenido (p. ej., labels de botones, empty states)

3. Patrones

   • Formularios, modales, navegación, tablas
   • Reglas de comportamiento responsive

Herramientas de docs que funcionan bien en la realidad de agencia:

• Zeroheight (documentación de sistemas de diseño)
• Notion (rápido, amigable para clientes)
• Storybook (engineering-first, excelente para contratos)

Flujo de QA que detecta regresiones antes que el cliente

Un stack pragmático de QA:

• Regresión visual: Chromatic (Storybook) o Percy
• Testing a nivel de componente: tests de componentes con Playwright (cuando aplique)
• Checks de accesibilidad: axe en CI para flujos clave
• Checks responsive: breakpoints definidos + un checklist (no “se ve bien en mi laptop”)

Conclusión concreta: define una página “golden path” que incluya cada estado de componente que te importa. Cuando cambian los tokens, validas esa página primero.

Ownership: ¿quién aprueba qué?

En trabajo con clientes, el ownership poco claro es cómo los sistemas se desvían.

Define tres roles:

• System Owner (Agencia): última palabra sobre tokens y contratos
• Product Owner (Cliente): prioriza solicitudes y acepta tradeoffs
• Implementer (Dev lead): hace cumplir el uso de variables y bloquea valores ad-hoc

---

Gobernanza: versionado, revisiones y cuándo decir “no” a nuevas variantes

La gobernanza suena pesada hasta que has entregado tu tercer “secondary secondary button”.

Versiona tu sistema como software

Usa versionado semántico para el paquete del sistema (aunque no sea literalmente un paquete npm):

• MAJOR: cambios breaking (renombres de tokens, cambios de contrato)
• MINOR: nuevos componentes/variantes (compatibles hacia atrás)
• PATCH: bug fixes (pequeños arreglos de estilo/accesibilidad)

Publica notas de release que respondan:

• ¿Qué cambió?
• ¿Por qué?
• ¿Qué deberían hacer distinto los equipos?

Un proceso de revisión liviano que evita la proliferación de variantes

Adopta un “Variant Gate” simple:

1. La solicitud incluye capturas + casos de uso
2. Demuestra reutilización (¿dónde más aparecerá?)
3. Revisa encaje con tokens (¿se puede resolver con tokens?)
4. Revisión de accesibilidad
5. Añadir a docs + matriz de QA

Si no pasa el gate, se convierte en:

• Una excepción de página (acotada en el tiempo), o
• Una solicitud rechazada con explicación y alternativa.

Cuándo decir “no” (y qué decir en su lugar)

Di no cuando:

• Una variante solo resuelve la preferencia de una única página
• Introduce espaciado/tipografía inconsistentes fuera de la escala
• Rompe el contraste/comportamiento de focus
• Duplica una variante existente con ajustes menores

Qué decir:

• “Podemos lograr ese resultado ajustando tokens semánticos, lo que mantiene el sistema consistente.”
• “Si agregamos esto, tendremos que soportarlo en estados, breakpoints y plantillas futuras. ¿Vale la pena?”
• “Acotemos esto como una excepción de campaña y lo revisamos después de ver performance/feedback.”

---

Plantillas y checklists que puedes copiar

Úsalas como artefactos internos de agencia. Están diseñadas para reducir ambigüedad y acelerar decisiones.

Plantilla de definición de design token

• Token name: color.text.default
• Type: color
• Description: primary text on default surfaces
• Maps to (light): color.neutral.900
• Maps to (dark): color.neutral.50
• Usage: body text, labels, headings
• Do not use for: disabled text, placeholder text

Plantilla de contrato de componente

• Component: Button
• Purpose: primary and secondary actions
• Variants: primary / secondary / ghost / destructive
• Sizes: sm / md / lg
• States:
  • default
  • hover
  • active
  • focus-visible
  • disabled
  • loading
• Content rules:
  • label max 24 characters
  • avoid punctuation
• Accessibility:
  • focus ring required
  • min hit area 44px
• Token rules:
  • no hex values
  • spacing from space.*

Checklist de handoff sin sorpresas (agencia → dev)

1. Tokens

   • Tokens semánticos definidos para text/bg/border/action/feedback
   • Naming de tokens consistente y documentado
   • Figma Variables coincide con los nombres de variables de producción (o existe una tabla de mapeo)

2. Componentes

   • Cada componente tiene variantes + estados definidos
   • Requisitos de accesibilidad listados
   • Comportamiento responsive especificado

3. Enforcement en producción

   • Variables CSS implementadas globalmente
   • Linting/guardrails en su lugar (donde sea posible)
   • Sin hex crudo / espaciado arbitrario en el código de componentes

4. QA

   • Baseline de regresión visual capturada
   • Flujos clave probados con axe/Lighthouse
   • Página golden path creada para validación rápida

5. Gobernanza

   • Número de versión asignado
   • Changelog iniciado
   • Owner + ruta de aprobación documentados

Checklist de intake de solicitudes del cliente (evita “drive-by variants”)

• ¿Cuál es el objetivo de negocio?
• ¿Dónde se usará (URLs/pantallas)?
• ¿Es un cambio de token, una variante o una excepción de página?
• ¿Cuál es el deadline y qué estamos sacrificando?
• ¿Afecta a la accesibilidad?
• ¿Quién aprueba el cambio del sistema?

---

Conclusión: construye sistemas que esperan el cambio—y se mantienen coherentes de todos modos

El trabajo con clientes es caótico porque los negocios son caóticos. La victoria no es eliminar el cambio; es construir un sistema de diseño que pueda absorber el cambio sin perder integridad.

Si quieres un sistema que sobreviva:

• Empieza token-first con un modelo primitivo + semántico
• Haz cumplir los tokens en producción con variables CSS
• Define contratos de componentes que hagan explícitas las excepciones
• Ejecuta un handoff sin sorpresas con docs, QA y ownership
• Gobierna las solicitudes con versionado y un variant gate—y acostúmbrate a decir “no así”

Si quieres, comparte tu stack actual (¿Figma + Webflow? ¿React + Storybook? ¿mixto?) y los patrones típicos de solicitudes de cliente que ves. Puedo adaptar un esquema de tokens, una convención de nombres de variables y un flujo de gobernanza que encaje con tu modelo de entrega.