- Rol
- Diseñador de producto
- Alcance
- Desde junio de 2023; migración a la siguiente versión en curso
- El problema
- El design system de Syniverse estaba escrito para personas. Un agente de IA lo lee al pie de la letra, así que cada hueco y cada «?» de la documentación se volvía una suposición.
- Mi rol
- Extiendo el design system (componentes, el grid, dark mode, QA) y reescribo su documentación como Markdown que leen por igual personas y agentes de IA. Su librería de Figma documenta 39 componentes y dos equipos de ingeniería de cinco personas construyen sobre ella.
- Qué decidí
- Nombrar los primitivos por tono y los roles por función. Correr cuatro temas desde un solo set de tokens. Dejar las reglas en DESIGN.md, no en cada prompt.
- Dónde está
- La versión actual está en producción. La siguiente versión está en QA interno. Claude Code ya construye prototipos en código a partir del sistema.
4
temas desde un solo set de tokens
39
componentes en la librería
2
modos de densidad sobre un grid de píxeles enteros
12
colores categóricos para gráficas en sets permitidos
45%
menos tiempo de diseño a desarrollo
Contexto y mi rol
Los productos de Syniverse son herramientas de operación para el tráfico de telecomunicaciones. Una pantalla típica tiene un título con una acción principal, un panel de filtros y una datatable con status pills, etiquetas de protocolo y acciones por fila. El design system es la librería en Angular, la librería de Figma y las guías detrás de ambas.
Me incorporé en junio de 2023, cuando el sistema ya estaba en producción. Como diseñador añadí tarjetas, el selector de fecha y hora, las gráficas, el grid de layout y el dark mode. Hace poco el sistema ganó un segundo lector: escribimos las specs de pantalla como prompts y Claude las construye a partir del design system, primero en Figma y ahora en prototipos en código.
El problema
Una persona diseñadora llena los huecos con contexto. Un agente toma la documentación al pie de la letra y, donde no queda claro, adivina. Al revisar nuestra documentación de tokens y tipografía fila por fila, encontré huecos concretos y repetibles.
Abrir imagen completa (se abre en una pestaña nueva)
Ninguno rompe una pantalla que construye una persona. Cada uno es una moneda al aire para un modelo.
Las primeras specs en forma de prompt mostraron el mismo problema desde el otro lado. Cada una tenía que repetir las reglas del sistema, y las copias arrastraban pedazos viejos: la spec de Alarms todavía listaba el botón «Create rule» de Active Rules. Las reglas que viven en los prompts se desvían, porque cada prompt es un fork.
Cómo lo abordé
El dark mode dejó los huecos al descubierto. Mapear cada token semántico a un valor oscuro expuso pasos que las paletas de primitivos no tenían. De ahí salieron muchos de los valores «?».
Un ciclo de auditoría junto a producción. La migración a la siguiente versión corre en paralelo a producción, así que ingeniería nunca se bloquea. Audito los tokens fila por fila contra una pregunta: ¿podría un agente resolver esto sin preguntarle a nadie? Luego Claude construye specs desde el sistema, registro cada resultado fuera del sistema y cada hallazgo se corrige en el sistema.
Documentación para dos lectores. Reescribo la documentación que me corresponde, empezando por el grid y las tarjetas. Los valores están en px y rem (tokens de tipografía en rem, el grid mapeado a Tailwind y CSS), la aritmética está escrita y las reglas se expresan como reglas («no se permite desvincular componentes»).
Decisiones clave
Nombrar los primitivos por tono, los roles por función
- Decidido
- Los primitivos se nombran por tono y paso; una capa de roles dice para qué sirve un color. Los componentes, Figma y DESIGN.md piden el rol, el tema elige el primitivo y todo valor de tema se resuelve a uno real. No se lanza ningún «Teal-?».
- Descartado
- Palabras de rol en los nombres de los primitivos, como los tokens de color primario de la versión actual.
- Por qué
- «Primary» deja de ser cierto cuando un tema lo vuelve algo distinto del teal. Un primitivo que falta deja que un agente invente un hex.
Abrir imagen completa (se abre en una pestaña nueva)
Abrir imagen completa (se abre en una pestaña nueva)
Un set de tokens, cuatro temas
- Decidido
- Syniverse y Neutral, cada uno claro y oscuro, renderizan la misma pantalla sin tocar el layout ni el código de los componentes. Solo cambia el primitivo detrás de cada rol.
- Por qué
- El dark mode demostró que valía la pena arreglar la capa de tokens, y los temas neutrales muestran que el sistema no está atado al teal de Syniverse.
Abrir imagen completa (se abre en una pestaña nueva)
Un grid de píxeles enteros, con densidad y un panel de IA que lo respetan
- Decidido
- La aritmética de columnas siempre da píxeles enteros: a 1440px, doce columnas de 92px, o exactamente 76px junto a una navegación de 192px. La densidad compact reduce el espacio en blanco, nunca los objetivos táctiles. El panel de IA de 476px empuja el grid en desktop y flota sobre él debajo de 1024px.
- Descartado
- Tratar el panel de IA como una tarjeta más.
- Por qué
- Sin blur de subpíxeles ni desfase entre Figma y el navegador. El panel cambia cuánto canvas tiene el grid, y empujar debajo de 1024px aplastaría las gráficas.
Abrir imagen completa (se abre en una pestaña nueva)
Abrir imagen completa (se abre en una pestaña nueva)
Las reglas viven en el sistema, no en el prompt
- Decidido
- Cada regla que las primeras specs repetían pasó a DESIGN.md, el único archivo que el agente lee antes de escribir código. Una spec solo dice lo que es único de la pantalla.
- Descartado
- Repetir las reglas en cada prompt.
- Por qué
- Las reglas en los prompts se desvían, porque cada prompt es un fork.
- Efecto
- El resultado fuera del sistema se corrige en el design system o en DESIGN.md, así que la siguiente pantalla recibe la corrección gratis.
La solución
Una persona diseñadora escribe una spec de pantalla corta: título, filtros, columnas, datos de ejemplo. Claude lee DESIGN.md, construye la pantalla como un componente Angular de la librería de producción usando solo tokens, y el resultado se revisa contra una lista de verificación corta.
Abrir imagen completa (se abre en una pestaña nueva)
El color de las gráficas sigue la misma lógica. El sistema define doce colores categóricos y sets ya verificados para dos a seis series, así que una gráfica toma el set de su número de series en vez de elegir colores.
Abrir imagen completa (se abre en una pestaña nueva)
Este es un prototipo en código del Network View de la herramienta de monitoreo, construido a partir de una spec contra el design system. Es una captura del navegador, no un frame de Figma.
Abrir imagen completa (se abre en una pestaña nueva)
Entrega y estado
Partes de la siguiente versión ya están en el código del front-end. Los componentes llegan a ingeniería a través de Figma, una revisión con las personas de ingeniería y recorridos de QA contra la spec.
Impacto
La versión actual está en producción y dos equipos de ingeniería construyen sobre él todos los días. Los componentes reutilizables y con tokens redujeron 45% el tiempo de diseño a desarrollo. La siguiente versión está en QA interno, y el ciclo de construcción ya se usó en dos productos reales, entre ellos la herramienta de monitoreo.
Reflexión
Yo pensaba que la documentación de un design system era una cortesía. Escribir specs para un agente cambió eso: cada nota vaga y cada «?» es una decisión que el sistema no ha tomado. Una persona la toma en silencio por ti, y un agente la toma distinto cada vez.
Lo más útil de la siguiente versión hasta ahora no han sido los componentes nuevos. Ha sido lograr que los existentes digan exactamente lo que significan.
Los nombres de clientes en las capturas están difuminados.