LawrenceHua/data-illustration

¿Qué hace data-illustration?

Las bibliotecas de gráficos simples (barras, líneas, radar) son precisas pero olvidables. El fallo opuesto —una imagen generada por IA que pretende ser una 'visualización de datos'— es bonita pero no puede codificar un número fielmente, así que es decoración disfrazada de datos. Este skill hace ambas cosas honestamente: los datos guían la geometría de un SVG generado (el núcleo preciso y reproducible), y cualquier imagen generada por IA se superpone solo como atmósfera, nunca para transmitir un valor.

Cuándo usarlo

• Alguien quiere visualizar puntuaciones/métricas/dimensiones pero un gráfico simple de barras/líneas/sectores resultaría aburrido o fuera de marca.
• Solicitudes como 'haz que esta visualización tenga un diseño real', 'algo más ilustrativo que un gráfico' o 'genera un gráfico real para el panel, no el gráfico por defecto'.
• Prefiérelo sobre codificar manualmente un gráfico aislado siempre que el resultado deba verse como diseñado intencionalmente, no como una biblioteca genérica.

El contrato de precisión (no negociable)

1. Cada cantidad en el resultado se calcula a partir de los valores de entrada, en código. Longitud de la forma, radio, texto de la etiqueta, el número central de lectura — todo derivado programáticamente, nunca estimado visualmente ni dibujado por un modelo de imagen.
2. La generación de imágenes por IA es solo decoración. Si superpones un fondo generado, limita el prompt a textura abstracta — sin texto, sin números, sin figuras, sin logotipos. Si la generación de imágenes no está disponible, el gráfico debe seguir siendo completo y correcto sin ella.
3. Todo está etiquetado. Cada elemento codificado recibe una etiqueta, el número principal tiene una lectura central, y una línea de leyenda indica qué significa realmente la forma. Un gráfico bonito que nadie puede decodificar es un fracaso, no un acierto.

Si alguna vez te sientes tentado a dejar que un modelo de imagen 'dibuje el gráfico' directamente —detente. Eso rompe el contrato y el resultado será sutilmente (o gravemente) incorrecto.

La forma por defecto: un 'bloom' orgánico

N dimensiones/puntuaciones → N pétalos que irradian desde un punto central. Por pétalo:

• La longitud codifica el valor (más largo = mayor), contra anillos de guía de números enteros tenues para que siga siendo legible como número, no solo como sensación.
• La plenitud se ensancha ligeramente con el valor — las puntuaciones altas se leen visualmente como 'más frondosas'.
• El color se asigna a la banda del valor mediante una rampa semántica (p. ej., verde para alto, ámbar para medio, rojo/terracota cálido para bajo).
• Una etiqueta en la punta indica el nombre de la dimensión y su número exacto.
• Un disco central muestra el promedio, coloreado según su propio valor, con un breve título.
• Una línea de leyenda indica la codificación en lenguaje claro ('longitud del pétalo = puntuación sobre 5').

Esto se lee como un organismo único por conjunto de datos —no como un gráfico radar genérico— mientras que cada valor sigue siendo exactamente legible.

Cómo construirlo

1. Toma la entrada como un mapa simple {dimensión: valor} más un título y un promedio.
2. Escribe un pequeño script (cualquier lenguaje con salida SVG es válido) que calcule la geometría de cada pétalo directamente a partir de los valores — ángulo = espaciado uniforme según el número de dimensiones, radio = una función del valor, color = una búsqueda según los umbrales de banda.
3. Renderiza las etiquetas y la leyenda como elementos de texto SVG reales, no incrustados en ninguna capa de imagen.
4. Capa de atmósfera opcional: genera un fondo abstracto temático a través de cualquier API de generación de imágenes a la que tengas acceso, compónlo debajo de la ilustración con baja opacidad detrás de una viñeta para que el centro se mantenga legible. Almacénalo en caché —genera una vez en tiempo de construcción/autoría, nunca en cada renderizado de página (es lento y cuesta dinero).
5. Haz que el resultado sea autónomo (un único archivo .svg, con cualquier fondo incrustado como URI de datos) para que no haya un activo separado que gestionar.
6. Si quieres que las formas sean interactivas (pasar el cursor/hacer clic para revelar la definición de cada dimensión + la puntuación exacta + la fuente), envuelve cada elemento con atributos de datos (data-dimension, data-score, data-definition) que un pequeño script pueda leer para controlar un panel lateral.

Ampliando la forma

El bloom es la opción por defecto, no la única —elige la forma que se ajuste a la estructura de los datos, pero mantén el contrato de precisión independientemente de la que uses:

• Cresta/contorno para una distribución o un valor seguido a lo largo de muchos elementos.
• Isotipo (glifos repetidos, el último parcialmente relleno) cuando contar es el objetivo y quieres que se lea como cantidad literal.
• Constelación cuando las relaciones entre elementos importan más que sus magnitudes individuales.

Anti-patrones

• Dejar que un modelo de imagen renderice el gráfico o los números — los valores serán incorrectos o inventados.
• Un gráfico magnífico sin etiquetas ni leyenda — indescifrable es inútil, por muy bonito que sea.
• Un fondo generado lo suficientemente fuerte para competir con la legibilidad de la capa de datos — mantenlo con baja opacidad, detrás de una viñeta.
• Llamar a una API de generación de imágenes en cada renderizado de página en lugar de usar caché — lento e innecesariamente caro.

Cómo usar

Instalación: copia esta carpeta en ~/.claude/skills/data-illustration/ para uso personal, o en .claude/skills/data-illustration/ dentro de un repositorio de proyecto.

Invocación:

Convierte estas 6 puntuaciones en un bloom de data-illustration en lugar de un gráfico de barras aburrido — titúlalo 'Retro Q3', añade un promedio central y una leyenda.

El gráfico de este panel se ve genérico. Usa data-illustration para convertirlo en una ilustración precisa y etiquetada — sin números dibujados por IA, todo calculado a partir de los datos reales.