UDS —
uDocz Design System

Cuatro productos, cuatro maneras de dibujar un botón.

uDocz creció por productos: la experiencia B2C de estudio, el dashboard para instituciones, la suite de profesores embebida en el LMS y los programas del sector público. Cada uno resolvía su interfaz por su cuenta — al auditar uno de ellos encontré más de 50 implementaciones one-off y hasta cuatro variantes del mismo botón conviviendo en producción.

El costo real: cada pantalla nueva volvía a decidir cosas ya decididas, y cada inconsistencia era una conversación más en el handoff con desarrollo.

Primitivos y semánticos: dos capas de tokens.

El sistema separa primitivos (paletas por escala, espaciado en base 2px, radios, elevaciones, tipografía) de semánticos (texto, superficie, borde, marca, feedback — nombrados por rol). Los componentes consumen solo semánticos; los primitivos anclan la capa semántica y nada más.

Con eso, el theming sale casi gratis: dark mode y las variantes de producto se resuelven re-apuntando la capa semántica con un atributo. Los 76 componentes heredan sin cambios.

Nueve reglas de contribución, escritas.

Cualquier cambio al sistema pasa por nueve reglas documentadas. Las cuatro que más trabajo hacen:

• El sistema define apariencia y comportamiento, no lógica de aplicación. Si un componente necesita JS, el sistema documenta el comportamiento y cada producto lo implementa.
• Nada se elimina sin plan de migración. Un breaking change es una versión mayor con la ruta de salida documentada.
• Sin parches de estilo. Heredé 11 excepciones que forzaban estilos por encima del sistema; quedan 2, cada una con su razón documentada.
• Los componentes nuevos no entran directo al sistema. Nacen en el producto que los necesita, con las convenciones del sistema, y se promueven cuando sirven a más de un producto — sin renombrar nada.

En la v0.4.0 ese mecanismo promovió 49 componentes de una vez, del staging B2C al sistema, sin romper a ningún consumidor: de 27 a 76.

WCAG 2.2 AA, con cada fix en el changelog.

Lo auditado y corregido, con fecha y versión:

• El texto informativo subió de 3.1:1 de contraste a 7.2:1 — de fallar el mínimo AA a superar el estricto AAA. La demo de abajo lo calcula en vivo sobre los hex reales.
• Indicador de foco agregado a 21 de 27 componentes que no lo tenían.
• Lectores de pantalla auditados componente por componente: navegación, diálogos, avisos y estados anunciados.
• prefers-reduced-motion respetado: con la preferencia activa, las animaciones se apagan. Ningún objetivo táctil baja de 44×44 px.
• En dark, marca y acento suben un stop de la escala para sostener el contraste.

Documentado, versionado, en producción.

Cada componente llega con documentación de uso —cuándo usarlo, cuándo no, anatomía, do's y don'ts— y su página de preview aislada. El conjunto se publica con releases versionadas y changelog: 76 componentes, 40 iconos propios, 4 releases. Ante una duda de implementación, la respuesta está escrita en el sistema; cuando el sistema se queda corto, se corrige y sale en la siguiente versión.

Los prototipos de los cuatro productos consumen estos mismos tokens: lo que se aprueba en un prototipo ya está dentro del sistema.

Un design system nunca está terminado.

La v0.4.0 dejó trabajo abierto, registrado en el changelog:

• El refactor de los estilos forzados que llegaron del staging. La promoción trajo 11 !important, un recurso que las reglas del sistema prohíben porque vuelve impredecible qué estilo gana. Nueve resultaron innecesarios y ya salieron; los dos que quedan son excepción documentada: la única forma de que un ajuste móvil le gane a estilos que el JS escribe inline.
• La verificación de dark mode componente por componente. Se hizo completa cuando el sistema tenía 27; los 49 promovidos heredan el tema oscuro de la capa semántica y su revisión uno por uno está en curso.
• El comportamiento vive en cada producto, por decisión. El sistema entrega estilos y estructura, no JS: la navegación por teclado de un modal o el anuncio de un toast los implementa cada consumidor, y la doc fija exactamente qué le toca a cada quien.