coastdigitalgroup/coastai-skills

Sistema de UI de Tarjetas

Propósito

El Sistema de UI de Tarjetas proporciona una metodología para diseñar y estructurar tarjetas (cards), los bloques de construcción modulares utilizados para agrupar información y acciones relacionadas. Las tarjetas son los componentes fundamentales de las interfaces centradas en el descubrimiento, permitiendo a los usuarios escanear y comparar múltiples elementos distintos (productos, artículos, perfiles) dentro de una cuadrícula o lista unificada. Un enfoque sistemático de las tarjetas asegura que el contenido sea escaneable, visualmente coherente y se adapte con elegancia a diferentes contextos de diseño (cuadrículas, carruseles, pilas) manteniendo la accesibilidad y una intención clara.

Casos de Uso

• Diseñar cuadrículas de productos para páginas de listados de comercio electrónico (PLPs).
• Crear vistas previas de artículos o publicaciones de blog para centros de contenido.
• Crear secciones de "Características" o "Servicios" en una página de aterrizaje.
• Organizar widgets de panel de control, aspectos destacados de funciones o resúmenes de datos.
• Implementar secciones de "Contenido Relacionado" en la parte inferior de las páginas.
• Definir un componente de "Resultado" para vistas de búsqueda o filtro.

Cuándo NO Usarlo

• Tablas de Datos Densas: Cuando los usuarios necesitan comparar atributos específicos en muchas filas de datos granulares simultáneamente; use responsive-data-tables en su lugar (aunque las tarjetas pueden ser una alternativa responsiva).
• Contenido Narrativo Único / Flujos de Texto Simples: Cuando el contenido sigue una historia lineal estricta o párrafos estándar donde un envoltorio de tarjeta añadiría ruido visual innecesario o interferiría con el ritmo de lectura.
• IU de Solo Acción Minimalista: Como una barra de búsqueda de un solo campo o un formulario de inicio de sesión simple donde un envoltorio de tarjeta añadiría ruido visual innecesario.

Entradas

1. Anatomía del Contenido: Una lista de elementos requeridos (ej., Imagen, Título, Categoría, Precio, Descripción, CTA).
2. Intención de Interacción: ¿Es toda la tarjeta clickeable, o hay objetivos de acción específicos?
3. Contexto Padre: ¿Dónde vivirá la tarjeta? (ej., cuadrícula de 3 columnas, barra lateral, desplazador horizontal).
4. Variación de Contenido: ¿Cuál es la cantidad mínima y máxima de texto esperada para títulos y descripciones?
5. Sistemas Existentes: Espaciado fluido, escalas tipográficas y paletas de colores del sistema de diseño padre.

Salidas

1. Especificación de Anatomía de Tarjeta: Regiones definidas (Encabezado, Multimedia, Cuerpo, Pie de página) y su espaciado interno.
2. Plano de Tarjeta: Una definición estructural del diseño interno y las capas de la tarjeta.
3. Variantes Responsivas: Reglas sobre cómo se adapta la tarjeta (ej., cambiar de vertical a horizontal en móvil).
4. Especificación de Interacción: Estados definidos (Hover, Focus, Active) y definiciones de áreas clickeables.
5. Mapa de Accesibilidad: Guía sobre jerarquía de encabezados y patrones de interacción con el teclado.

Flujo de Trabajo

1. Aplicar la "Regla de los Tres Puntos" y Definir la Anatomía

Cada tarjeta debe tener tres puntos claros de jerarquía para garantizar la escaneabilidad:

1. El Ancla (Visual): Una imagen o icono de alta calidad que proporcione reconocimiento inmediato. Defina la relación de aspecto para las imágenes (ej., 16:9, 1:1).
2. El Contexto (Contenido): El título y los metadatos principales (ej., Precio, Fecha, Categoría).
3. El Objetivo (Acción): Una acción principal clara (ej., "Añadir al Carrito", "Leer Más").

Mapa de la jerarquía interna completa: Encabezado (metainformación como etiquetas/fechas), Área Multimedia, Contenido/Cuerpo (título + descripción) y Pie de página/Acciones (CTAs, precio, prueba social).

2. Establecer el Espaciado Interno y la Cuadrícula Interna

Aplicar fluid-spacing-system al interior de la tarjeta:

• Relleno: El espacio entre el borde de la tarjeta y su contenido (generalmente --space-m).
• Huecos de Apilamiento: El espacio vertical entre elementos internos (generalmente --space-xs o --space-s).

Determinar cómo se distribuye el contenido dentro de la tarjeta:

• De Arriba a Abajo (Estándar): Imagen en la parte superior, contenido en el medio, acción en la parte inferior.
• Lado a Lado (Horizontal): Imagen a la izquierda, contenido y acción a la derecha (mejor para listas móviles o barras laterales).
• Superposición: El contenido se sitúa sobre la imagen (requiere tratamientos de alto contraste para la legibilidad).

3. Diseñar la Jerarquía Visual y Manejar la Variación de Contenido

Aplicar las palancas de visual-hierarchy-system para distinguir el contenido:

• Peso: Hacer que el Título sea negrita y más grande que la descripción.
• Contraste: Usar un color apagado para el metatexto (ej., "Publicado el 24 de Oct").
• Elevación: Usar bordes o sombras de caja sutiles para separar la tarjeta del fondo.

Diseñar para el escenario de contenido "peor caso":

• Truncamiento vs. Ajuste: Decidir si los títulos largos deben truncarse con puntos suspensivos o ajustarse a varias líneas.
• Alineación: Usar Flexbox margin-top: auto en el contenedor de acción para asegurar que los botones se alineen perfectamente en tarjetas de diferentes alturas en una cuadrícula.

4. Establecer Patrones de Interacción

Elegir un patrón funcional para la interacción:

• La Caja Grande: Toda la tarjeta es un enlace (requiere un manejo cuidadoso de la accesibilidad para lectores de pantalla).
• La Acción Anidada: Solo botones específicos o el título son clickeables.
• El Híbrido: La superficie de la tarjeta tiene un efecto hover, pero acciones específicas realizan diferentes tareas (ej., "Añadir al Carrito" vs. "Ver Detalles").

Usar transformaciones sutiles en hover (ej., ligero levantamiento, cambio de color del borde) para indicar interactividad.

5. Definir Adaptaciones Responsivas y Verificar la Accesibilidad

Planificar cómo sobrevive la tarjeta en diferentes viewports:

• Vertical a Horizontal: En móvil, una tarjeta podría cambiar de un diseño con imagen en la parte superior a un diseño con imagen a la izquierda para ahorrar espacio vertical.

Verificar la accesibilidad antes de la aprobación final:

• Niveles de Encabezado: Asegurar que los títulos de las tarjetas utilicen niveles de encabezado apropiados (generalmente H3 o H4) para mantener el esquema del documento de la página.
• Objetivos Táctiles: Cualquier elemento interactivo dentro de la tarjeta debe cumplir con WCAG 2.2 SC 2.5.8 (mínimo 24x24px, con espaciado adecuado si los objetivos más pequeños son inevitables); preferir 44x44px donde el espacio lo permita.
• Texto Alternativo: Cada imagen ancla debe tener texto alternativo descriptivo o estar marcada como decorativa.
• Navegación por Teclado: Cada elemento interactivo dentro de una tarjeta debe ser accesible mediante la tecla Tab y tener un indicador de foco que no esté recortado u ocultado por tarjetas hermanas o encabezados fijos (WCAG 2.2 SC 2.4.11, Foco No Ocultado).

Reglas de Decisión

• La "Regla de los Tres Puntos": Una tarjeta rara vez debe tener más de 3 prioridades distintas (ej., 1. Imagen, 2. Título, 3. Precio). Demasiado detalle la convierte en una "minipágina", no en una tarjeta.
• La Regla de la Relación de Aspecto: Usar relaciones de aspecto consistentes para las imágenes (ej., 4:3, 16:9 o 1:1) para evitar diseños "saltarines" en una cuadrícula.
• Puntuación de Proximidad: El espacio entre el Título y la Descripción debe ser más pequeño que el espacio entre la Descripción y el CTA.
• La Regla "Sin Huérfanos": Si una tarjeta es parte de una cuadrícula, la cuadrícula debe manejar el espacio restante con elegancia (ej., grid-template-columns: repeat(auto-fill, minmax(280px, 1fr))).
• Alturas Iguales: En una cuadrícula, las tarjetas en la misma fila idealmente deben tener la misma altura (usando Flexbox align-items: stretch).
• Acciones Primarias vs. Secundarias: Solo una acción debe ser visualmente dominante (CTA Principal). Otras acciones (ej., "Guardar en Lista de Deseos") deben ser iconos o enlaces de bajo contraste.
• Indicación de Interactividad: Si una tarjeta es clickeable, debe tener un estado hover visible.

Restricciones

• Capacidad de Respuesta: Las tarjetas nunca deben exceder el ancho del viewport ni tener un ancho fijo; deben ocupar columnas en un responsive-grid-system y apilarse verticalmente o cambiar a un diseño horizontal en pantallas pequeñas.
• Accesibilidad: Debe soportar la navegación por teclado (Tab a través de elementos interactivos) y mantener una relación de contraste mínima de 4.5:1 para el texto. Si toda la tarjeta es clickeable, use el patrón de "enlace estirado" para evitar enlaces redundantes para lectores de pantalla.
• Rendimiento: Evitar imágenes excesivamente grandes; usar srcset para servir activos de tamaño apropiado para el contenedor de la tarjeta.
• Diseño: Preferir CSS Grid con auto-fill/auto-fit y espacios basados en clamp() en lugar de puntos de interrupción fijos para que las tarjetas se refluyan naturalmente; usar consultas de contenedor (@container) cuando el diseño interno de una tarjeta deba adaptarse a su propio ancho en lugar del viewport (ej., la misma tarjeta en una cuadrícula de ancho completo y una barra lateral estrecha).

Patrones de Falla Comunes

• El Efecto "Escalera / Botones Desalineados": Botones situados a diferentes alturas debido a longitudes variables de título, lo que hace que la cuadrícula se vea desordenada.
• Sobre-decoración: Usar demasiados bordes, sombras y degradados, lo que dificulta la lectura del contenido.
• Baja Densidad de Información: Hacer tarjetas demasiado grandes con muy poco contenido, forzando un desplazamiento innecesario.
• Sobrecarga de Información: Intentar encajar demasiados detalles en una sola tarjeta, rompiendo la Regla de los Tres Puntos y confundiendo al usuario.
• Objetivos de Clic Inaccesibles/Invisibles: Botones o enlaces pequeños que son difíciles de tocar en dispositivos móviles, o hacer que una tarjeta parezca clickeable con solo un icono diminuto como disparador real.
• Falta de Relleno: Apretar el texto contra el borde de la tarjeta o la imagen.

Criterios de Validación

• La "Regla de los Tres Puntos" es claramente visible (Ancla, Contexto, Objetivo).
• El espaciado interno (relleno/huecos) utiliza tokens del sistema de espaciado fluido.
• La tipografía sigue la escala y jerarquía establecidas del sitio.
• Las acciones principales (botones) están alineadas en la parte inferior de la fila de la cuadrícula.
• Las relaciones de aspecto de las imágenes son consistentes en todas las tarjetas del sistema.
• Los estados interactivos (Hover/Focus) están definidos y son accesibles.
• Las tarjetas en una cuadrícula se alinean correctamente y manejan longitudes de contenido variables con elegancia.
• Los niveles de encabezado siguen una jerarquía lógica dentro de la página.
• Los objetivos táctiles cumplen con WCAG 2.2 SC 2.5.8 (mínimo 24x24px).
• Los indicadores de foco nunca son ocultados por tarjetas superpuestas, imágenes o elementos fijos (WCAG 2.2 SC 2.4.11).