Biblioteca de componentes: foundations, patrones y páginas

Mapa de las cuatro capas

Organiza la biblioteca de componentes en cuatro responsabilidades: las foundations reúnen decisiones visuales compartidas; las primitivas ofrecen controles reutilizables pequeños; los patrones combinan controles para una tarea; las páginas incorporan datos y reglas del producto. Las dependencias deben apuntar hacia los bloques más pequeños. Un botón no necesita conocer la página que lo utiliza. Esta arquitectura es una recomendación práctica, no una clasificación obligatoria del sector. Su utilidad consiste en hacer predecibles los cambios entre equipos.

Imagina una pantalla de ajustes de cuenta con un campo de correo, una acción para guardar y un mensaje de confirmación. La tipografía y el espaciado proceden de las foundations. El campo y el botón son primitivas. La sección editable constituye un patrón. La página decide qué cliente ha iniciado sesión, si puede cambiar el correo y cómo guardar el resultado. Una pantalla concreta permite clasificar la biblioteca antes de reorganizar cientos de elementos existentes.

Los límites importan más que los nombres. Algunos equipos llaman componente a una primitiva y componente compuesto a un patrón. Escribe las definiciones junto a ejemplos y añade un caso que quede fuera. Card puede distribuir contenido; una tarjeta que calcula si una cuenta puede renovar debe estar más cerca del producto. La guía sobre el alcance de un kit y un sistema de diseño explica el modelo general; aquí nos centramos en responsabilidades y dependencias.

Foundations independientes de las pantallas

Las foundations describen decisiones que varias interfaces pueden consumir sin importar comportamientos del producto. Empieza por los estilos tipográficos, superficies, espacios, bordes e indicadores de interacción que realmente utilizas. USWDS presenta los tokens como un vocabulario limitado de valores visuales. Nombrar una decisión facilita seguir sus cambios; no demuestra que ese valor funcione en cualquier contexto. Separa la decisión del control que la aplica y documenta las excepciones conocidas.

Por ejemplo, define el rol border.interactive y deja que el campo lo utilice para su borde. La página de cuenta no necesita una copia llamada account.email.border solo porque el campo aparezca allí. Introduce un rol más específico cuando exprese una decisión real que los existentes no puedan representar. Anota el motivo y sus consumidores. Si cada pantalla inventa sus propios roles para valores equivalentes, la capa común deja de aportar una referencia útil.

Comprueba un cambio antes de dar esta capa por terminada. Modifica una decisión de espaciado en una rama o una copia del archivo de diseño y revisa el campo, la sección editable y la página. Si un elemento conserva un valor local, documenta la excepción o reconéctalo. Es un ejercicio de dependencias, no una invitación a cambiar todo el espaciado de producción. Mantén visibles las salidas de cada plataforma y el código que transforma las decisiones compartidas.

Un contrato pequeño para cada primitiva

Una primitiva tiene una tarea útil que puedes describir sin mencionar un área del negocio. Button inicia una acción; TextField recoge texto; Badge muestra un estado breve. Su contrato incluye estados admitidos, límites del contenido, eventos y responsabilidades de accesibilidad. Debe facilitar las combinaciones válidas y explicar las que no admite. Evita convertir cada variación de una captura en una nueva propiedad pública. Una API pequeña con composición documentada suele resultar más comprensible que un control lleno de interruptores independientes.

En TextField, documenta la etiqueta, el valor, la ayuda y el error, además de cómo los relaciona la implementación. Indica quién aporta la validación y cuándo aparece el mensaje. El campo puede representar un error de forma consistente mientras el flujo de cuenta decide si el correo es aceptable. W3C exige identificar y describir mediante texto los errores de entrada detectados automáticamente. Un borde rojo, por sí solo, deja incompleta la especificación del estado de error.

Reparte las responsabilidades de accesibilidad entre capas. El botón puede conservar su nombre accesible y su interacción con teclado; la página debe elegir una etiqueta significativa y situarlo correctamente en el flujo. Del mismo modo, una tarjeta flexible puede recibir una imagen de anchura fija que rompa su composición. Revisa el resultado completo, además del control aislado. Para ejemplos de propiedades y estados de diseño, consulta la guía de variantes y estados UI claros.

Patrones que resuelven una tarea

Convierte una composición en patrón cuando la relación repetida resuelva la misma tarea, no solo porque dos pantallas se parezcan. Una sección editable reúne título, explicación, campos, guardado y respuesta. Su documentación debe aclarar cuándo se guarda, qué sucede ante un fallo y qué información permanece disponible durante la petición. CMS Design System distingue los patrones de las piezas individuales de interfaz: combinan componentes, contenido y accesibilidad alrededor de problemas recurrentes.

Escribe un contrato breve antes de crear un SettingsPanel genérico. Puede recibir un título, contenido explicativo, una zona de campos y una función de guardado. Define dónde aparece la respuesta y qué acciones siguen disponibles. El producto aporta los campos concretos, los permisos y la persistencia. Si dos equipos necesitan momentos de guardado diferentes, nombra esa diferencia de comportamiento. No escondas el guardado automático y el envío explícito detrás de un booleano cuya repercusión solo entiende una persona.

Prueba la relación con escenarios concretos: valores sin cambios, guardado en curso, error de validación, fallo del servidor y confirmación. Usa mensajes realistas en lugar de rectángulos vacíos. Comprueba si la persona puede recuperarse sin perder lo escrito y si entiende el resultado sin depender del color. Conserva los ejemplos como parte del contrato. Una distribución repetida sin comportamiento acordado puede ser una plantilla, pero todavía no establece la interacción compartida que hace útil al patrón.

La lógica de producto pertenece a la página

Las páginas ensamblan las piezas compartidas en una experiencia específica. Conocen la cuenta actual, la ruta, los permisos y el resultado de cargar los datos. Pueden elegir qué patrón mostrar y traducir un error del servicio a un mensaje útil. Los controles comunes no deberían importar el cliente de servicio de esa página ni sus rutas. De lo contrario, cambiar la lógica de cuenta altera inesperadamente las dependencias de todas las aplicaciones que consumen la biblioteca.

Para los ajustes, puedes mantener un AccountPage conectado alrededor de una vista AccountView de presentación. El contenedor obtiene los datos y proporciona funciones; la vista compone el patrón. Storybook documenta páginas de presentación y simulación de dependencias para componentes conectados. Es una opción con compromisos: concentrar la carga puede exigir pasar propiedades entre niveles y no encajar con cargas incrementales. Elige el límite que deje claras las dependencias reales, sin imponer una única arquitectura de datos a todas las aplicaciones.

Explica la regla mediante un ejemplo: AccountPage utiliza SettingsSection; SettingsSection consume TextField y Button; estos controles emplean foundations. Una foundation nunca debe necesitar AccountPage para funcionar. Puedes mantener las capas en un paquete al principio. Sepáralas cuando los consumidores, los ritmos de publicación o las plataformas lo justifiquen. Los nombres de las carpetas no hacen cumplir la regla: revisa imports, exportaciones públicas e instalación real antes de prometer que un límite está protegido.

Una tarjeta de EmviUI para probar los límites

Un ejemplo preparado ayuda a comprobar la arquitectura antes de reconstruir la biblioteca. El catálogo de componentes de EmviUI ofrece diseños que puedes inspeccionar y adaptar. La tarjeta horizontal inferior contiene imagen, etiquetas, título, texto de apoyo y acción. Es un ejemplo de diseño de EmviUI. Su contenido de muestra sirve para explicar la composición; no demuestra el funcionamiento de una aplicación, no representa otro producto y no acredita precios actuales.

Clasifica cada responsabilidad. Tipografía y espacios pertenecen a las foundations; acción y etiquetas son controles reutilizables; la distribución puede convertirse en una composición Card. La página elige qué cuenta o recurso aparece. Si varios productos repiten la misma tarea de selección de recursos, extrae un patrón con comportamiento documentado. Si solo comparten la distribución visual, conserva una composición flexible y deja la interacción al producto. Así evitas convertir una pantalla de ejemplo en un modelo de negocio obligatorio.

Aprovecha el ejemplo para revisar el diseño: introduce un título traducido largo, elimina una etiqueta opcional y sustituye la imagen por un estado sin contenido multimedia. Después especifica qué hará el código cuando la acción no pueda continuar. EmviUI aporta un punto de partida visual; tu equipo sigue definiendo implementación, datos y criterios de aceptación. Para la propiedad y los cambios entre equipos, continúa con EmviUI a escala de producción.

Verifica los contratos de cada capa

Construye una verificación pequeña y útil alrededor de los fallos posibles, en vez de acumular capturas del estado inicial. Comprueba el error de una primitiva, la recuperación del patrón y los datos realistas de la página. Reutiliza datos de prueba cuando mantengan coherentes los ejemplos, pero conserva la capacidad de mostrar el fallo en su límite correcto. Que el botón funcione aislado no demuestra que la actualización completa de la cuenta funcione también.

Incluye un caso estrecho con contenido largo. La guía de Reflow de W3C describe una condición de 320 píxeles CSS de anchura para contenido con desplazamiento vertical, con excepciones para contenido que necesita distribución bidimensional. Úsala como comprobación de accesibilidad cuando corresponda, no como breakpoint universal del producto. Observa si la etiqueta se parte correctamente, el error sigue asociado al campo y las acciones permanecen accesibles. Repite la tarea en los tamaños realmente admitidos por el producto.

Asigna revisiones concretas. Quien mantiene la biblioteca comprueba el contrato del control; un representante del producto revisa la tarea compuesta; ingeniería verifica el comportamiento real. En un equipo pequeño, una persona puede asumir varias funciones. Registra qué comprobaciones se hicieron y qué excepciones quedan pendientes. Distingue un estado de diseño propuesto de una implementación verificada para que otros equipos sepan qué pueden utilizar con confianza y qué necesita trabajo adicional.

Añade una comprobación de dependencias: ¿puede un consumidor representar TextField sin configurar el servicio de cuentas? ¿puede el ejemplo del patrón mostrar un fallo con datos proporcionados? ¿puede la página sustituir su función de persistencia sin modificar el control? Anota las respuestas junto a los ejemplos para que otro equipo pueda reproducir las comprobaciones.

Refactoriza una pantalla antes de ampliar

Empieza por una pantalla con varios controles repetidos y un problema de mantenimiento conocido. Enumera sus imports, estilos locales y reglas de negocio. Mueve únicamente las responsabilidades cuyo límite puedas explicar. Conserva un adaptador para la página actual mientras introduces el contrato de la nueva primitiva o patrón. Revisa la tarea antes y después con contenido realista. La arquitectura obtiene así un beneficio visible antes de convertirse en una migración de todo el repositorio.

Redacta una nota breve del cambio: qué contrato se modificó, quién lo consume, qué requiere migración y qué escenarios se comprobaron. Mantén ejemplos antiguos y nuevos durante la transición. Cuando otro equipo adopte el patrón, registra dónde encaja el contrato y dónde necesita ampliarse. Comparte el comportamiento mínimo respaldado por esos casos. El objetivo es entender el próximo cambio de la biblioteca y disponer de un lugar claro para las excepciones específicas del producto.

Un ticket concreto puede sustituir los botones locales de dos pantallas por el contrato Button y retirar sus ajustes de espaciado duplicados. Mantén la función de envío en cada página. Después compara cómo muestran la respuesta y extrae únicamente la relación compartida. Registra una excepción si un tipo de cuenta necesita aprobación. Esa diferencia ayuda a delimitar el patrón; no debe convertirse silenciosamente en una nueva obligación para todos los botones del sistema.