De captura de pantalla a sistema de estilo: un playbook de design tokens de 5 días que los clientes sí adoptan | Blanche

La mayoría de los proyectos de design tokens no se atascan porque los equipos no entiendan los tokens. Se atascan porque el trabajo empieza demasiado grande.

Un escenario típico de agencia se ve así:

La UI es un collage de decisiones de “solo hay que entregarlo” repartidas entre páginas de marketing, producto y campañas.
Varios diseñadores interpretan la misma marca de forma distinta.
Frontend tiene una mezcla de utilidades de Tailwind, CSS ad-hoc y una librería de componentes a medio hacer.
El cliente quiere “un sistema de diseño”, pero lo que realmente necesita es consistencia que pueda mantener.

La solución no es una iniciativa de sistema de diseño de 12 semanas. Es un set mínimo y entregable de tokens que se pueda adoptar en días, no en trimestres—y un flujo de trabajo que haga difícil el bloat y evidente el progreso.

Callout: El objetivo de los tokens no es una taxonomía perfecta. Es reducir la toma de decisiones y la inconsistencia mientras aumenta la velocidad de entrega.

Por qué la mayoría de los proyectos de design tokens se atascan (y cómo evitarlo)

1) Empiezan con un lienzo en blanco

Si empiezas el trabajo de tokens inventando una arquitectura impecable desde cero, ya vas tarde. Los clientes reales no tienen UIs impecables: tienen capturas de pantalla, CSS heredado y “ese estilo de botón de la campaña del año pasado”.

Conclusión: Empieza extrayendo lo que existe y luego ajusta.

2) Confunden tokens “primitivos” con tokens “semánticos”

Los equipos a menudo saltan directamente a tokens semánticos como button.primary.background, pero no han estabilizado la paleta base, la escala tipográfica o las reglas de espaciado.

Conclusión: Fija primero los primitivos, y luego mapea la semántica.

3) Crean tokens para todo

El bloat de tokens aparece cuando tokenizas cada caso extremo:

color-blue-487
padding-card-compact-v2
shadow-modal-legacy

Suena exhaustivo, pero es inmantenible.

Conclusión: Tokeniza decisiones, no artefactos.

4) No hay gobernanza

Sin un responsable, los tokens se convierten en un vertedero. Sin versionado, cada cambio se vuelve una emergencia.

Conclusión: La gobernanza no es burocracia: es lo que hace que la adopción sea segura.

El flujo de extracción de 5 días: de auditoría → primitivos → componentes

Esto está pensado para agencias: rápido, adoptable y resistente a los handoffs.

Día 1: Audita la UI como un detective (no como un perfeccionista)

Inputs:

15–30 pantallas clave (o plantillas de página) entre producto + marketing
CSS existente (si está disponible)
Archivos de Figma (si existen)

Qué estás buscando: repetición y deriva.

Haz un “inventario de capturas”

Crea un tablero (FigJam, Miro o incluso Figma) con capturas agrupadas por área de UI:

Botones
Formularios
Navegación
Tarjetas
Alertas/toasts
Bloques tipográficos
Visualización de datos (tablas, badges)

Luego anota qué es inconsistente:

¿Cuántos azules se usan para enlaces?
¿Cuántos radios de esquina existen?
¿Cuántas sombras aparecen?

Herramientas que ayudan:

Figma: inspección de color/tipografía de la selección
Chrome DevTools Coverage + búsqueda en CSS
Stylelint o estadísticas de PostCSS (si tienes un codebase)

Entregable al final del Día 1:

Una lista de primitivos candidatos (colores, tipografía, espaciado, radios, sombras)
Una lista de los 10 componentes con más “dolor” (normalmente botones, inputs, tarjetas)

Regla: No estás auditando todo. Estás auditando lo que impulsa el 80% del output de la UI.

Día 2: Extrae primitivos a un set mínimo de tokens “v0”

Los primitivos son tus materias primas. Mantenlos aburridos y estables.

Empieza con el set más pequeño que se pueda entregar

Un v0 práctico suele incluir:

Color: escala neutral + 1–2 escalas de marca + colores semánticos de estado
Tipografía: familias tipográficas, tamaños base, interlineados, pesos
Espaciado: una escala por pasos (p. ej., 4, 8, 12, 16…)
Radios: 2–3 opciones como máximo
Sombras: 2–4 niveles como máximo
Bordes: 1–2 grosores

Ejemplo (primitivos):

color.neutral.0…900
color.brand.50…900
space.1…12
radius.sm | radius.md | radius.lg
shadow.1…4

Evita la trampa de color más común

Los clientes suelen tener “azul de marca” más 14 azules ligeramente distintos. No codifiques todos.

En su lugar:

Elige una escala de marca (50–900) que soporte estados hover/active.
Mapea los azules heredados a los valores más cercanos de la escala.
Crea un bucket temporal de “legacy” solo si hace falta, y planifica eliminarlo.

Callout: Si no puedes borrar un token más adelante, no es un token: es una capa de compatibilidad permanente.

Entregable al final del Día 2:

Un archivo de tokens primitivos (JSON) + un borrador de colección de variables en Figma

Día 3: Crea tokens semánticos que reflejen la intención del producto

Los tokens semánticos son los que diseñadores y desarrolladores deberían usar en el día a día. Codifican significado:

color.text.default
color.surface.canvas
color.border.muted
color.action.primary
color.action.primaryHover

Una convención de nombres que sobrevive a los handoffs

Un patrón duradero es:

Categoría (color, space, radius, type)
Rol (text, surface, border, action)
Intención (default, muted, primary, danger)
Estado (hover, active, disabled, focus)

Ejemplos:

color.text.default
color.text.muted
color.surface.default
color.surface.raised
color.action.primary.default
color.action.primary.hover
color.action.primary.disabled

Cómo evitar el bloat de tokens

Usa estas restricciones:

Cada token semántico debe mapear a un primitivo. Nada de valores hex en crudo.
Cada token debe tener al menos dos consumidores. Si solo lo usa un componente, probablemente sea un token de componente.
Prefiere composición a proliferación. Por ejemplo, usa color.border.default de forma amplia en lugar de crear color.border.card, color.border.table, color.border.modal.

Entregable al final del Día 3:

Capa de tokens semánticos definida y mapeada a primitivos
Un doc corto de “reglas de uso de tokens” (1 página)

Día 4: Conecta tokens a componentes (Figma + código) con una capa fina de adopción

Aquí es donde los proyectos de tokens se vuelven reales.

Patrón 1: Variables CSS como fuente de verdad en producción

Un enfoque pragmático:

Guardar tokens en JSON (por portabilidad)
Generar variables CSS (para theming en runtime)
Opcionalmente generar tipos TypeScript (por seguridad)

Herramientas que los equipos realmente usan:

Style Dictionary (clásico, flexible)
Tokens Studio (excelente para flujos Figma ↔ tokens)
Panda CSS / Vanilla Extract (estilado tipado)
Tailwind (puede consumir variables CSS y mapearlas a utilidades)

Ejemplo de output (conceptual):

--color-text-default
--color-surface-default
--radius-md
--space-4

Luego los componentes referencian variables en lugar de valores hard-coded.

Patrón 2: Theming con fallbacks

Si necesitas light/dark o multi-brand:

Define tokens semánticos por tema
Mantén los primitivos estables
Usa fallbacks para evitar romper páginas

Una regla segura:

Los primitivos rara vez cambian
Los tokens semánticos pueden cambiar por tema
Los tokens de componente cambian más (y deben tratarse con cuidado)

Patrón 3: Alineación con la librería de componentes

Si tienes una librería de componentes (React, Vue, Web Components), implementa tokens en el nivel más bajo:

El Button base usa color.action.primary.*
Input usa color.border.default, color.text.default, color.surface.default

Conclusión: Si los componentes no consumen tokens, los tokens son solo documentación.

Entregable al final del Día 4:

Tokens fluyendo a variables CSS
3–5 componentes core refactorizados para usar tokens de extremo a extremo

Día 5: Gobernanza, versionado y documentación a prueba de clientes

Esta es la parte que las agencias se saltan—y la parte que determina si los clientes realmente siguen usando el sistema.

Handoff + gobernanza: versionado, docs y ownership

Decide quién aprueba cambios de tokens

Un RACI simple funciona bien:

Owner (Accountable): Design System Lead (agencia o cliente)
Approvers (Responsible): 1 representante de diseño + 1 de frontend
Contributors: cualquier diseñador/dev vía PR
Informed: stakeholders de producto/marketing

Callout: Si cualquiera puede añadir tokens, el conteo de tokens solo sube.

Versiona tokens como un producto

Trata los tokens como un paquete:

Usa SemVer (major/minor/patch)
Publica un changelog
Exige una plantilla de PR: “qué cambió, por qué, capturas, notas de migración”

Reglas generales:

Patch: corregir un typo, ajustar documentación, sin cambio visual
Minor: añadir tokens, no rompe
Major: cambiar/eliminar tokens, probable cambio visual

Documenta decisiones, no solo valores

Los clientes no necesitan un sitio de sistema de diseño de 40 páginas para empezar. Necesitan:

Inventario de tokens (tabla)
Guías de uso (cuándo usar qué)
Registro de decisiones (por qué elegiste una escala, qué deprecaste)
Notas de migración (qué actualizar en el código)

Dónde alojarlo:

Cero fricción: README en el repo de tokens
Mejor: Storybook + docs en MDX
Enterprise: Backstage, Confluence (pero mantén la fuente cerca del código)

Entregable al final del Día 5:

Doc de gobernanza (1–2 páginas)
Paquete/repo de tokens versionado con changelog
Flujo de trabajo de “cómo solicitar un cambio de token”

Patrones de implementación que hacen que los tokens sean rápidos de adoptar (y difíciles de romper)

Patrón A: El “modelo de tokens de dos capas” (primitivos + semánticos)

Este es el punto dulce para la mayoría de clientes de agencia.

Los primitivos estabilizan el lenguaje visual
La semántica estabiliza el uso entre equipos

Puedes añadir tokens de componente más adelante si la librería madura.

Patrón B: Deprecación en lugar de eliminación

Cuando tengas que cambiar un token:

Marca los tokens antiguos como deprecated
Mantenlos durante un ciclo de versión minor
Proporciona un codemod o guía de búsqueda/reemplazo
Elimínalos en la siguiente versión major

Conclusión: La deprecación es cómo mantienes la confianza mientras mejoras el sistema.

Patrón C: “Tokens de compatibilidad” para UI heredada

Si el cliente tiene páginas legacy que no se pueden refactorizar de inmediato, crea una pequeña capa de compatibilidad:

legacy.color.link → maps to color.action.primary.default

Luego migra gradualmente los consumidores a los nuevos tokens semánticos.

Conclusión: Los tokens de compatibilidad son un puente, no un destino.

Métricas antes/después (lo que a los clientes realmente les importa)

Los tokens solo son valiosos si puedes demostrar impacto. Mide esto:

Velocidad de entrega

Tiempo para construir una nueva sección de landing
Tiempo para implementar una nueva variante de componente

Consistencia

Conteo de valores hex únicos en el CSS de producción (debería bajar)
Conteo de tamaños de fuente/interlineados únicos (debería bajar)

Mantenibilidad

Número de overrides “one-off” por página/plantilla
Frecuencia de issues de QA de diseño relacionados con espaciado/color/tipo

Preparación para rebrand

Tiempo para actualizar el color de marca y propagarlo por superficies
Número de archivos/componentes tocados para una actualización de marca

Una victoria realista tras adoptar un set mínimo de tokens:

Menos regresiones de UI porque los componentes referencian tokens semánticos estables
Iteración más rápida porque los diseñadores dejan de debatir “qué gris”
Los rebrands se convierten en cambios controlados de variables, no en una búsqueda del tesoro

Callout: El ROI no son los tokens. El ROI es menos decisiones y menos inconsistencias.

Una plantilla de pitch al cliente que puedes reutilizar

Usa esta estructura en tu próximo kickoff o QBR.

1) El problema (en su idioma)

“Ahora mismo, las nuevas páginas y funcionalidades se entregan con pequeñas diferencias visuales que se acumulan—grises distintos, espaciado inconsistente, estilos de botón ligeramente diferentes. Eso ralentiza la entrega y hace que los rebrands sean caros.”

2) La propuesta (pequeña, rápida, segura)

“En 5 días, extraeremos un set mínimo de tokens a partir de tu UI existente y lo conectaremos a Figma y a tu codebase usando variables CSS. Esto no es un rediseño: es una capa de consistencia.”

3) Los entregables

Set de tokens (primitivos + semánticos)
Variables de Figma alineadas con el código
Implementación de variables CSS
3–5 componentes core refactorizados
Flujo de gobernanza + versionado

4) Las métricas de éxito

Reducir colores únicos en X%
Reducir tamaños tipográficos únicos en Y%
Reducir el time-to-build de nuevas secciones en Z%
Reducir inconsistencias de QA por release

5) El siguiente paso

“Tras la adopción de v0, ampliaremos la cobertura componente a componente, priorizando las superficies que más entregáis.”

Conclusión: entrega el sistema de tokens más pequeño que no se pueda ignorar

Un sistema de tokens que los clientes realmente usan no es el más completo. Es el que:

Parte de la realidad (capturas, UI heredada, CSS desordenado)
Se entrega rápido (una semana, no un trimestre)
Tiene nombres que sobreviven a los handoffs
Funciona entre Figma, variables CSS y componentes
Incluye gobernanza para que no se degrade

Si lideras un equipo de agencia, la ventaja competitiva no es “hacemos design tokens”. Es podemos hacer tu UI consistente sin ralentizarte.

¿Quieres un plan de tokens de arranque rápido para tu cliente?

Si compartes (1) 10–15 capturas de pantalla y (2) un enlace al repo o al CSS compilado, podemos definir un set de tokens v0, un esquema de nombres y un plan de entrega de 5 días adaptado a tu stack (Webflow, React, Next.js, Tailwind, Storybook, etc.).