10 errores de design system que arruinan la coherencia a escala

Un equipo entrega su décima funcionalidad del trimestre. Ocho contienen botones nuevos. Tres de esos botones se parecen al primary button del design system, pero cada uno lleva un padding, un radio o una sombra ligeramente distintos. Nadie tomó la decisión de bifurcar. Todos simplemente entregaron. Así se ve la incoherencia de un design system a escala: no una decisión mala, sino mil pequeñas que nadie tuvo que defender.

Los errores siguientes son los diez que seguimos encontrando cuando hacemos una auditoría de design system en un producto que creció más rápido que su sistema. Ninguno es exótico. Todos componen. La buena noticia: cada uno tiene un arreglo mecánico, una vez decides pagarlo.

1. Tratar el design system como un proyecto secundario

El error: nadie es dueño del sistema. Una diseñadora senior lo mantiene vivo en el 20% de su tiempo. Ingeniería trata los fixes como "ya llegaremos". No hay roadmap, no hay on-call, no hay release notes.

Cuánto cuesta: cada contribuidor reinventa lo que falta. La biblioteca acumula casi-duplicados porque nadie tiene la autoridad de rechazar un pull request que añade el 41º variante del botón.

El arreglo: asignar un dueño real con un porcentaje de su tiempo asignado formalmente, un roadmap público y una sola cola de Slack o Linear. Un ciclo de vida definido para los componentes (proponer, revisar, construir, documentar, lanzar, medir, deprecar) convierte una caja de piezas en un producto.

2. Añadir un componente por cada nuevo diseño

El error: cada nueva funcionalidad añade dos o tres componentes a la biblioteca. Seis meses después, el equipo no sabe si usar Card, CardCompact, CardWithHeader o CardLegacy.

Cuánto cuesta: confianza. El sprawl socava los beneficios mismos que el design system debería crear. Los equipos dejan de ir a la biblioteca porque no pueden navegarla.

El arreglo: un criterio estricto para promocionar a la biblioteca compartida. Nosotros usamos tres: el patrón aparece en al menos dos funcionalidades no relacionadas, ha sido estable por al menos un release, y una diseñadora más un ingeniero han firmado sobre la API. Todo lo demás se queda local hasta que se gana el upgrade.

3. Saltarse la capa semántica de tokens

El error: los componentes referencian los tokens primitivos directamente. Button usa color-blue-500 en vez de color-action-primary. La capa semántica nunca se construye porque "la añadimos después".

Cuánto cuesta: cada cambio de tema se vuelve un find-and-replace global. La mayoría de los sistemas define tokens primitivos genéricos aliados a usos intencionales de espacio y color. Sin ese aliasing, no se entrega dark mode sin reescribir cada componente.

El arreglo: tres capas. Las primitivas tienen los valores (color-blue-500 = #3B82F6). Los tokens semánticos tienen la intención (color-action-primary apunta a color-blue-500). Los tokens de componente tienen decisiones locales (button-bg-default apunta a color-action-primary). Los componentes referencian la capa semántica o la de componente, nunca la primitiva. Cubrimos los trade-offs en tokens vs CSS variables vs Tailwind.

4. Permitir que los overrides locales se vuelvan normales

El error: cada equipo de producto bifurca un componente "solo para esta vista" y cambia una prop. Seis meses después, la mitad de las superficies usa el override y la mitad la base. El sistema tiene dos verdades y ninguna manera de elegir.

Cuánto cuesta: design drift. Los overrides locales sobre spacing, color, tipografía o props de componente se vuelven normales y fragmentan lentamente el sistema hasta que "qué es realmente estándar" es una pregunta que nadie puede responder.

El arreglo: tratar el override rate como una métrica de primera clase. Si un componente se sobrescribe en más del 10% de sus instancias, al sistema le falta un variant y el override es la señal. O lo reabsorbes como variant soportado, o lo eliminas junto con el caso de uso al que servía.

5. Sin presupuesto de variantes

El error: un botón empezó con tres variantes. En el segundo año tiene 22, incluyendo primary-with-icon-on-right-disabled-loading.

Cuánto cuesta: el equipo que debería estar construyendo funcionalidades pasa los martes por la tarde discutiendo qué variante existente usar. Storybook se vuelve un laberinto.

El arreglo: poner un techo a las variantes por componente. Nosotros usamos un presupuesto: un componente con más de cinco variantes activa una revisión. Añadir una variante nueva requiere deprecar una vieja o demostrar que no se puede expresar componiendo primitivas existentes. El techo es artificial. La disciplina es real.

6. Sin camino de deprecación

El error: los componentes solo se añaden, nunca se retiran. ButtonV1 vive al lado de ButtonV2 porque retirarlo rompería seis páginas que nadie del equipo actual posee.

Cuánto cuesta: confusión a nivel de import ("qué Button uso"), bundle hinchado y un coste de auditoría que crece linealmente con la edad de la biblioteca.

El arreglo: un sistema de tiers de calidad. Experimental, Beta, Stable, Deprecated, Removed. Un componente vive en Deprecated por dos ciclos de release con un codemod disponible, luego desaparece. Ese calendario lo declaramos públicamente, en el changelog, el día en que depreciamos.

7. Nombrar los tokens por valor en lugar de por intención

El error: color-red-600, spacing-16, shadow-large. Los nombres describen el output visual. El día en que la marca cambia el rojo a magenta, cada nombre miente.

Cuánto cuesta: un nombre como color-text-red describe un valor visual, lo que significa que se rompe en cuanto el color cambia. Un nombre como color-text-error describe la intención y se mantiene estable.

El arreglo: nombrar por el porqué. color-feedback-error, spacing-stack-md, elevation-overlay. La primera vez que una diseñadora replique ("pero es rojo"), explica que el sistema sirve a los próximos cinco años, no al mockup de hoy.

8. Tratar Figma como fuente de la verdad

El error: la biblioteca de diseño vive en Figma. Los ingenieros la traducen a código a mano. Las dos divergen en semanas.

Cuánto cuesta: un problema de handoff vestido de design system. En cada release, diseño entrega componentes que ingeniería no ha implementado, e ingeniería entrega fixes que diseño no ha absorbido. La brecha de auditoría se ensancha hasta que alguien hace una reconciliación manual que nadie quiere repetir.

El arreglo: el código es la fuente de la verdad. Los tokens viven en un único repositorio como JSON o un export tipado, y Figma lee desde ahí vía Variables y una herramienta de sync. Los componentes tienen una sola implementación canónica; diseño aporta specs anotadas, no fuentes paralelas. La biblioteca de Figma refleja la de código, no al revés.

9. Sin métrica de adopción medida

El error: nadie puede responder "qué porcentaje de la UI usa el design system". El equipo estima 80%. La auditoría encuentra 38%.

Cuánto cuesta: es difícil decir qué constituye un conteo sano sin un objetivo. Sin medición, cada conversación sobre el sistema es anécdota contra anécdota.

El arreglo: instrumenta la cobertura. Análisis estático sobre el codebase que reporta el ratio de instancias de componentes del design system frente a las bespoke, desglosado por superficie. Mews construyó la suya escaneando el árbol de React en producción. Nosotros corremos un escaneo similar en nuestras ops, semanalmente, y tratamos cualquier caída como un incidente.

10. Diseñar el sistema solo alrededor de los diseñadores

El error: el sistema es precioso en Figma y doloroso en código. Las APIs de los componentes son incoherentes, las props llevan nombres de conceptos visuales que ingeniería no usa, faltan las primitivas de accesibilidad. Los ingenieros rodean el sistema en lugar de pelear con él.

Cuánto cuesta: la adopción se atasca. Ingeniería escribe sus propias primitivas, diseño las audita y encuentra drift, el ciclo se repite.

El arreglo: traer a ingeniería al sistema desde el día uno. Las APIs de los componentes se diseñan junto a la especificación visual, no después. La accesibilidad es un requisito duro en cada componente (gestión del foco, handlers de teclado, roles ARIA). El sistema se entrega como un paquete que un ingeniero instala e importa en una línea, no como una biblioteca de Figma más una página de wiki. Un sistema custom que los ingenieros rehúsan usar es lo peor de ambos mundos.

El patrón debajo de los diez

El hilo común: un design system o se gobierna o se desparrama. Los errores anteriores no son fallos de gusto ni de talento. Son fallos de gobernanza. Un roadmap, un presupuesto, un sistema de tiers, una medición, un dueño. Ninguno es exótico y ninguno requiere una herramienta nueva. Requieren que alguien decida que el sistema es un producto y trate su evolución como tal.

Los sistemas que aguantan a escala comparten una regla silenciosa: cada nuevo componente, variante, token u override tiene que justificarse frente al coste que añade. La respuesta por defecto es no.