coastdigitalgroup/coastai-skills

Sistema de Métricas y Estadísticas

Propósito

El Sistema de Métricas y Estadísticas proporciona una metodología para visualizar datos cuantitativos de una manera que sea instantáneamente comprensible y contextualmente relevante. Va más allá de simplemente "mostrar un número" al establecer reglas para la jerarquía numérica, visualización de tendencias y color semántico, asegurando que los usuarios puedan captar el significado de un valor (por ejemplo, "¿Es el 42% bueno o malo?") sin un análisis profundo.

Casos de Uso

• Paneles SaaS: Mostrar indicadores clave de rendimiento (KPI) como MRR, Churn o Usuarios Activos.
• Prueba Social de Marketing: Destacar secciones de "Cifras Clave" (por ejemplo, "10k+ Clientes", "99.9% de Disponibilidad").
• Salud y Monitoreo: Visualizar rendimiento del sistema, tasas de error o uso de recursos.
• Analíticas Personales: Mostrar el progreso hacia objetivos en aplicaciones de fitness, finanzas o productividad.
• Comercio Electrónico: Mostrar recuentos de reseñas, niveles de stock o "artículos vendidos en las últimas 24 horas".

Cuándo NO Usarlo

• Conjuntos de Datos Sin Procesar: Si el usuario necesita ordenar, filtrar o comparar 10+ filas de datos con múltiples atributos, usa data-table-ui-system.
• Relaciones Complejas: Si el objetivo principal es mostrar la relación entre variables a lo largo del tiempo, usa una biblioteca completa de Gráficos (no cubierta por este sistema atómico).
• Contenido Narrativo: Los números incrustados en oraciones deben seguir la tipografía estándar; este sistema es para métricas de "Visualización".
• Metadatos de Bajo Valor: Conteos pequeños (como notificaciones) deben usar badge-and-tag-system.

Entradas

1. El Valor: El número o porcentaje principal a mostrar.
2. La Etiqueta: Una descripción clara y concisa de lo que representa el valor.
3. Contexto/Tendencia: Datos comparativos (por ejemplo, vs. el mes pasado, vs. el objetivo).
4. Unidad/Formato: Símbolos de moneda, porcentajes o unidades (por ejemplo, "ms", "GB").
5. Prioridad de Jerarquía: ¿Es un "KPI Principal" o una "Estadística de Apoyo"?

Salidas

1. Especificación de Tarjeta de Estadística: La disposición espacial del valor, la etiqueta y la tendencia dentro de un contenedor.
2. Escala Tipográfica: Tamaños definidos para números de "Visualización" vs. etiquetas.
3. Lógica de Tendencia: Reglas visuales para estados Ascendente, Descendente y Neutral (Color + Iconos).
4. Estrategia Adaptativa: Cómo se colapsan o escalan las cuadrículas de métricas en móvil.

Flujo de Trabajo

1. Categorizar el Tipo de Métrica

Determinar la "gravedad" visual requerida:

• Nivel 1: Métrica Hero. Grande, centrada, a menudo sin borde. Se usa para la prueba social de alto nivel en páginas de aterrizaje.
• Nivel 2: Tarjeta KPI. Contenida dentro de una tarjeta, a menudo en una cuadrícula. Se usa para resúmenes de panel.
• Nivel 3: Estadística En Línea. Pequeña, de alta densidad. Se usa dentro de encabezados o barras laterales.

2. Establecer Jerarquía Numérica

Aplicar las reglas de "Tipografía de Visualización":

• El Valor: Debe ser el elemento más grande (generalmente 200–400% del tamaño del cuerpo).
• La Etiqueta: Colocada directamente encima o debajo del valor. Usa un color apagado o un peso menor para asegurar que no compita.
• La Unidad: Los símbolos (%, $) deben ser ligeramente más pequeños que el número para evitar que "rompan" el enfoque visual del valor.

3. Proporcionar Contexto de Tendencia y Comparación

Un número sin contexto a menudo carece de significado. Añade una "Capa de Comparación":

• Indicador de Tendencia: Usa una flecha (↑/↓) combinada con un cambio porcentual o de valor.
• Etiqueta de Período de Tiempo: Especifica siempre el período de comparación (por ejemplo, "vs últimos 30 días").
• Color Semántico: Aplica color a la tendencia, no necesariamente al valor.
  • Tendencia Positiva: Verde (generalmente).
  • Tendencia Negativa: Rojo (generalmente).
  • Neutral: Gris.

4. Aplicar Ritmo Espacial (La Cuadrícula)

Las métricas rara vez se muestran de forma aislada. Agrúpalas usando responsive-grid-system:

• Diseño de Cuadrícula: 3 o 4 columnas en escritorio; 1 o 2 en móvil.
• Relleno Interno: Asegura un amplio espacio en blanco (--space-l o --space-xl) alrededor del valor para que "destaque".

5. Diseñar para Estados de Carga y Vacío

• Esqueleto: Usa skeleton-state-system para el valor y la tendencia mientras se obtienen los datos.
• Estados Cero: Si una métrica es 0, decide si debe mostrarse como "0" o un guión (—).

Reglas de Decisión

• La Regla "Bueno/Malo": Nunca uses Verde/Rojo para tendencias si la métrica no es inherentemente positiva/negativa (por ejemplo, "Temperatura" no debería ser verde solo porque subió). Usa Neutral (Gris/Azul) para cambios sin valoración.
• Lógica de Redondeo: Para estadísticas de marketing, redondea al "K" o "M" más cercano para una lectura instantánea (por ejemplo, "12.4K" vs "12,432"). Para paneles, usa la precisión requerida para la tarea.
• Uso de Iconos: Usa iconos solo si ayudan a distinguir entre diferentes categorías de métricas (por ejemplo, un icono de "Usuarios" vs un icono de "Ingresos"). No uses iconos solo como decoración.
• Colocación de Etiquetas: Las etiquetas alineadas en la parte superior son mejores para escanear una cuadrícula de métricas similares; las etiquetas alineadas en la parte inferior son mejores para estadísticas "Hero" donde el número es la atracción principal.

Restricciones

• Accesibilidad: Usa aria-label para proporcionar el contexto completo (por ejemplo, "Ingresos: 12,000 dólares, un 5% más que el mes pasado"). Asegura que el contraste de color para los indicadores de tendencia cumpla con WCAG AA (4.5:1).
• Capacidad de Respuesta: Los valores de las métricas nunca deben desbordar sus contenedores. Usa tipografía fluida (clamp() de CSS) o lógica de "ajuste al contenedor" para números muy grandes.
• Consistencia: Todas las métricas en un solo grupo deben usar el mismo redondeo, alineación y estilo de tendencia.

Patrones Comunes de Falla

• El "Número Desnudo": Mostrar un valor sin etiqueta ni contexto, dejando al usuario adivinando qué significa.
• Dependencia Excesiva del Color: Usar solo Rojo/Verde para indicar tendencia sin iconos (↑/↓), lo que lo hace inaccesible para usuarios daltónicos.
• Inversión de Jerarquía: Hacer que la etiqueta sea más grande o más audaz que el valor, ralentizando el proceso de "escaneo y comprensión".
• Aglomeración de Métricas: Colocar demasiadas métricas en una sola fila, causando que los números se superpongan.
• Sobrecarga de Precisión: Mostrar 4 decimales en una página de aterrizaje de marketing, creando una carga cognitiva innecesaria.

Criterios de Validación

• Cada métrica tiene una etiqueta clara y visible.
• Los valores usan un tamaño de tipografía "de Visualización" distinto (más grande que el texto del cuerpo).
• Las tendencias (Arriba/Abajo) se indican TANTO con color como con un icono/símbolo.
• El contexto de comparación (por ejemplo, período de tiempo) se indica explícitamente.
• Los colores semánticos (Verde/Rojo) se usan solo para cambios valorados.
• El diseño de cuadrícula mantiene la legibilidad en móvil (sin desbordamientos).
• Accesibilidad: el contexto completo está disponible para lectores de pantalla a través de ARIA.