namgung9406/visualize

Visualizar

Convierte cualquier idea, dato o contenido en una impresionante visualización HTML de un solo archivo.

Después de crear un archivo

Siempre haz AMBOS después de escribir el archivo HTML:

1. Abrir automáticamente en el navegador: Usa la herramienta de apertura de navegador del IDE cuando esté disponible. De lo contrario, ejecuta Invoke-Item <nombre-archivo>.html en Windows, open <nombre-archivo>.html en macOS, o xdg-open <nombre-archivo>.html en Linux.
2. Devuelve un enlace de archivo en el que se pueda hacer clic: En las respuestas de VS Code, usa un enlace Markdown al archivo generado en el espacio de trabajo. Usa una URL file:// solo cuando la salida esté fuera del espacio de trabajo y el cliente lo soporte.

Ejemplo de respuesta después de la creación:

¡Visualización creada! Abriendo en el navegador...
[mi-panel.html](mi-panel.html)

Requisitos críticos (NO NEGOCIABLES)

⚠️ SE GARANTIZA EL FRACASO DE LA EVALUACIÓN SIN ESTOS 8 ELEMENTOS ⚠️

CADA archivo DEBE comenzar con la plantilla esqueleto de references/skeleton.md — copia la plantilla COMPLETA y luego añade tu contenido.

1. Propiedades personalizadas CSS: Nombres exactos requeridos: --bg, --surface, --surface-hover, --border, --text, --text-secondary, --accent, --accent-secondary, --positive, --negative, --warning — NO otros nombres (no --bg-primary, no --text-primary). CRÍTICO: Estos nombres de propiedad exactos son necesarios para la compatibilidad con el sistema de evaluación.
2. Sistema de Menú de Utilidades (OBLIGATORIO): Elemento .viz-menu completo con botón .viz-menu-toggle, contenedor .viz-menu-dropdown, botón de descarga PNG (onclick="downloadImage()"), botón de impresión (onclick="window.print()"), y script CDN de html-to-image (<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/html-to-image.js"></script>). CRÍTICO PARA LA EVALUACIÓN: El sistema de menú se verifica automáticamente y CAUSARÁ FALLOS si falta.
3. Clases de Tema (CRÍTICO PARA LA EVALUACIÓN): Debe definir explícitamente AMBAS clases .theme-light y .theme-dark en la hoja de estilo con definiciones de propiedades personalizadas completas. EJEMPLO REQUERIDO:

:root { /* propiedades base */ }
.theme-light { --bg: #ffffff; --surface: #f8f9fa; --text: #1a1a1a; /* etc */ }
.theme-dark { --bg: #0a0a0a; --surface: #1a1a1a; --text: #ffffff; /* etc */ }

NUNCA confíes solo en :root o @media (prefers-color-scheme) — el sistema de evaluación busca temas basados en clases. 4. HTML Semántico: Elemento <main id="main-content">, OBLIGATORIO: Múltiples elementos <section> para bloques de contenido principales (encabezado, métricas, gráficos, etc.), enlace para saltar al contenido. Cada área de contenido distinta debe estar envuelta en etiquetas <section> semánticas. 5. Requisitos de Chart.js (CRÍTICO PARA LA EVALUACIÓN): DEBE incluir <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/chart.umd.min.js"></script> antes del cierre de </head>. OBLIGATORIO: INMEDIATAMENTE después del script de Chart.js, añade <script>Chart.defaults.animation = false;</script> (previene fallos de animación y el sistema de evaluación lo verifica automáticamente). VALIDACIÓN DE GRÁFICOS OBLIGATORIA: Cada función de gráfico DEBE comenzar con if (typeof Chart === 'undefined') { console.error('Chart.js no cargado'); return; }. ACCESIBILIDAD DE GRÁFICOS: Cada elemento canvas DEBE tener atributos role="img" y aria-label descriptivos. CONFIGURACIÓN CRÍTICA DE GRÁFICOS: Establece maintainAspectRatio: false, responsive: true, y plugins: { tooltip: { enabled: true } } para accesibilidad. NUNCA deshabilites los tooltips — el sistema de evaluación verifica que los tooltips estén habilitados. SISTEMA DE CONFIABILIDAD DE GRÁFICOS: Usa el patrón ChartManager dedicado para una integración a prueba de balas:

var ChartManager = {
  charts: new Map(),
  safeInit: function(canvasId, config) {
    if (typeof Chart === 'undefined') {
      console.error('Librería Chart.js no cargada - verificar inclusión de CDN');
      return null;
    }
    try {
      if (this.charts.has(canvasId)) {
        this.charts.get(canvasId).destroy();
        this.charts.delete(canvasId);
      }
      var ctx = document.getElementById(canvasId);
      if (!ctx) {
        console.error('Elemento canvas no encontrado: ' + canvasId);
        return null;
      }
      // Asegurar que no haya instancias de gráfico en conflicto
      if (ctx.chart) {
        ctx.chart.destroy();
        delete ctx.chart;
      }
      // Establecer atributos de accesibilidad
      ctx.setAttribute('role', 'img');
      if (!ctx.getAttribute('aria-label')) {
        ctx.setAttribute('aria-label', 'Visualización de gráfico');
      }
      // Inicializar con manejo de errores mejorado
      var chart = new Chart(ctx, config);
      this.charts.set(canvasId, chart);
      return chart;
    } catch (error) {
      console.error('La inicialización del gráfico falló para ' + canvasId + ':', error);
      return null;
    }
  },
  updateTheme: function() {
    if (typeof Chart === 'undefined') return;
    this.charts.forEach(function(chart, canvasId) {
      try {
        chart.update();
      } catch (error) {
        console.error('Actualización de tema del gráfico falló para ' + canvasId + ':', error);
      }
    });
  },
  destroyAll: function() {
    this.charts.forEach(function(chart) {
      try {
        chart.destroy();
      } catch (error) {
        console.error('Destrucción del gráfico falló:', error);
      }
    });
    this.charts.clear();
  }
};

Usa ChartManager.safeInit() en lugar de new Chart() sin formato. CONFIGURACIÓN CRÍTICA DE GRÁFICOS: Establece maintainAspectRatio: false, responsive: true, y plugins: { tooltip: { enabled: true } } para accesibilidad. DIMENSIONES DEL CONTENEDOR DE GRÁFICOS: El contenedor debe tener height explícita >= 300px para que los gráficos se rendericen correctamente. Usa colores conscientes del tema con propiedades personalizadas CSS, nunca colores hex estáticos. NUNCA uses sintaxis import/export con Chart.js CDN — usa solo declaraciones var estándar.

SOLUCIÓN DE PROBLEMAS DE CHART.JS (CRÍTICO): Si los gráficos aparecen como espacios en blanco:

• Verifica que el CDN de Chart.js esté incluido antes de </head>
• Verifica que Chart.defaults.animation = false; esté inmediatamente después del CDN
• Verifica que la inicialización del gráfico esté dentro del listener del evento DOMContentLoaded
• Verifica que no haya sintaxis de import/export de módulos en ninguna parte del archivo
• Verifica que el patrón ChartManager.safeInit() se use correctamente
• Verifica que el canvas tenga atributos role="img" y aria-label

6. Diseño Responsivo: Espaciado entre secciones ≥48px, CRÍTICO: SIN desbordamiento horizontal en viewport de 375px (OBLIGATORIO: añade @media (max-width: 375px) { body { overflow-x: hidden; } } para evitar el desplazamiento horizontal), JERARQUÍA DE TAMAÑO DE FUENTE OBLIGATORIA: h1 ≥ 2.5rem, h2 ≥ 2rem, h3 ≥ 1.5rem, body = 1rem. REQUISITOS DE PRESENTACIÓN DE DIAPOSITIVAS: h1 de diapositiva de título ≥ 3rem, títulos de diapositivas de contenido ≥ 2.5rem, diferenciación visual clara entre niveles de encabezado. ESPACIADO DE SECCIONES DE DIAPOSITIVAS: Las secciones principales dentro de las diapositivas deben tener espaciado ≥48px (título-a-contenido, contenido-a-gráficos, gráficos-a-navegación). Prueba todos los diseños a 375px de ancho — los paneles son especialmente propensos al desbordamiento del contenedor de gráficos. CONSULTAS DE CONTENEDOR CSS: Para capacidad de respuesta avanzada, usa consultas basadas en contenedor:

.chart-container { container-type: inline-size; }
@container (max-width: 400px) { 
  .chart-legend { display: none; } 
  .chart-title { font-size: 1rem; }
}

Esto proporciona una verdadera capacidad de respuesta a nivel de componente más allá de las consultas de medios del viewport. 7. Impresión y Accesibilidad: Estilos @media print, @media (prefers-reduced-motion: reduce) con animaciones deshabilitadas 8. Animaciones de Entrada (OBLIGATORIO): Debe incluir animaciones de entrada a través de clases .animate, atributos data-reveal o CSS @keyframes. CRÍTICO PARA LA EVALUACIÓN: La presencia de animaciones se detecta automáticamente y es obligatoria. 9. Funciones JavaScript: cycleTheme(), toggleMenu(), las variables de nivel superior usan var no let/const

🔥 CRÍTICO: Copia skeleton.md exactamente → Reemplaza "TU CONTENIDO AQUÍ" con el contenido de la visualización → Guarda el archivo

Principios Fundamentales

1. HTML de un solo archivo — un archivo .html con CSS/JS en línea. Se abre en cualquier navegador, funciona sin conexión, se envía fácilmente por correo electrónico.
2. Tema claro optimizado — los diseños modernos priorizan la calidad del modo claro. El tema oscuro está disponible mediante un interruptor.
3. Hermoso por defecto — el primer resultado debe verse profesional sin iteración cero.
4. Primero el contenido — la visualización sirve al mensaje. Nunca sacrifiques claridad por estética.
5. Responsivo — funciona en escritorio, tableta y móvil a menos que tenga dimensiones fijas explícitamente (por ejemplo, diapositivas 16:9).
6. Moderación visual — Los diseños profesionales evitan elementos decorativos que añaden ruido. Sin orbes de degradado flotantes, bordes de arcoíris o animaciones ornamentales.

Filosofía

HTML no es un "sitio web" — es una herramienta de visualización. El código es barato. Todos deberían sentirse capacitados para visualizar cualquier cosa. Esta habilidad convierte el contexto de la conversación, URLs, artículos, datos o ideas en bruto en algo visual y digerible en segundos.

Los usuarios invocan esto en mitad de la conversación con Claude Code. Usa el contexto completo de la conversación — cualquier cosa de la que hayan estado hablando, cualquier enlace que hayan compartido, cualquier dato que hayan pegado — como material de origen. Cuando se proporcione una URL, arrástrala y extrae el contenido para visualizarlo.

Reglas de Salida

PRIMER PASO OBLIGATORIO: Copia el esqueleto completo de references/skeleton.md — esto incluye todos los elementos requeridos (menú, sistema de temas, propiedades CSS, HTML semántico, características de accesibilidad). Nunca escribas HTML desde cero.

• Escribe UN archivo .html en ~/Downloads/ (o la ruta especificada por el usuario)
• Nombre de archivo: kebab-case descriptivo, ej., q4-revenue-dashboard.html, team-roadmap-deck.html
• Comienza con la plantilla skeleton.md, añade tu contenido a la sección <!-- TU CONTENIDO AQUÍ -->
• Todos los estilos personalizados en <style> después de los estilos base del esqueleto
• Las bibliotecas CDN son recomendadas — usa la mejor herramienta para el trabajo:
  • Tailwind CSS — https://cdn.tailwindcss.com (estilo basado en utilidades, úsalo libremente)
  • Chart.js — https://cdn.jsdelivr.net/npm/chart.js (barras, líneas, circulares, radar, doughnut)
  • D3.js — https://cdn.jsdelivr.net/npm/d3@7 (visualización de datos compleja/personalizada, gráficos de fuerza)
  • Mermaid — https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js (diagramas de flujo, diagramas de secuencia)
  • Three.js — 3D cuando sea apropiado
  • Reveal.js — motor de diapositivas completo cuando sea necesario. CRÍTICO: Debe establecer html, body { height: 100%; overflow: hidden; } y dar al contenedor .reveal height: 100%. La configuración DEBE usar dimensiones numéricas: Reveal.initialize({ width: 1280, height: 720, center: true, controls: false }) — NUNCA uses porcentajes de cadena como '100%' que causan un viewport de altura cero y diapositivas en blanco. OBLIGATORIO: Deshabilitar los controles predeterminados de Reveal.js (controls: false) — las superposiciones de flecha < > predeterminadas son feas. En su lugar, añade una barra de navegación inferior personalizada mínima:

<nav class="slide-nav" aria-label="Navegación de diapositivas">
  <button onclick="prevSlide()" aria-label="Diapositiva anterior">
    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M15 18l-6-6 6-6"/></svg>
  </button>
  <span class="slide-counter" id="slideCounter">1 / 8</span>
  <button onclick="nextSlide()" aria-label="Siguiente diapositiva">
    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M9 18l6-6-6-6"/></svg>
  </button>
</nav>

.slide-nav { position: fixed; bottom: 16px; left: 50%; transform: translateX(-50%); display: flex; align-items: center; gap: 8px; z-index: 9998; }
.slide-nav button { width: 28px; height: 28px; border-radius: 6px; background: transparent; border: none; color: var(--text-secondary); cursor: pointer; display: flex; align-items: center; justify-content: center; opacity: 0.3; transition: opacity 0.2s; }
.slide-nav button:hover { opacity: 0.7; }
.slide-counter { font-size: 12px; color: var(--text-secondary); font-weight: 400; min-width: 40px; text-align: center; opacity: 0.35; }

• Leaflet — mapas y datos geoespaciales (https://unpkg.com/[email protected]/dist/leaflet.js + CSS). Requerido para datos geográficos — nunca dibujes a mano formas de continentes SVG. Usa mosaicos de OpenStreetMap o un proveedor de mosaicos mínimo.
• SVG para iconos y gráficos simples — nunca uses URLs de imágenes externas a menos que el usuario las proporcione
• Prefiere animaciones CSS sobre JS cuando sea posible

Consulta references/libraries.md para enlaces CDN detallados, patrones y consejos.

Sistema de Diseño

Aplica estos valores predeterminados. Son dogmáticos y probados — anúdalos solo cuando el usuario lo solicite.

Referencia completa del sistema de diseño: Consulta references/design-system.md para especificaciones completas de tipografía, color, espaciado, animación, accesibilidad y pulido visual.

Aspectos destacados clave (consulta la referencia para obtener detalles completos):

Notas de Diseño

Sistema de Temas (CRÍTICO):

• Usa SOLO temas basados en clases — <html class="theme-dark"> o <html class="theme-light">
• El interruptor de tema cambia la clase html: document.documentElement.className = 'theme-' + newTheme
• Nunca uses atributos data-theme — el sistema de evaluación espera temas basados en clases
• Propiedades personalizadas CSS requeridas: --bg, --surface, --text, --accent, --border (conjunto mínimo para compatibilidad con la evaluación)

Tipografía:

• Fuente Inter obligatoria — https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700;800;900&display=swap
• JERARQUÍA DE PESO DE FUENTE OBLIGATORIA: h1 ≥ 700, h2 ≥ 600, h3 ≥ 500, body = 400 (requisito de evaluación crítico)
• Seguimiento de -0.03em en los encabezados
• EXCELENCIA TIPOGRÁFICA EN COREANO: Para contenido en coreano, usa Noto Sans KR para el texto del cuerpo con Inter para los elementos de la interfaz de usuario. Aplica line-height: 1.6 para coreano (frente a 1.4 para latín). El peso coreano Medium se asigna al Regular occidental (400). Incluye: https://fonts.googleapis.com/css2?family=Noto+Sans+KR:wght@300;400;500;600;700&display=swap

Colores:

• Solo temas basados en clases (NO @media prefers-color-scheme)
• Oscuro: fondo #0A0A0A, texto #EDEDED. Claro: fondo #FAFAF9, texto #0f172a
• Consulta la referencia para obtener más detalles.

Elementos y Patrones de la Interfaz de Usuario

Encabezados de Sección:

• Sin fondos decorativos ni bordes — solo tipografía limpia
• Anchura máxima de 800px para bloques de texto
• Subtítulos en --text-secondary con peso 400 y tamaño 0.9x
• Espaciado entre el título y el contenido de al menos 24px

Tarjetas y Contenedores:

• Esquinas ligeramente redondeadas (border-radius: 12px)
• Fondo: --surface, borde: 1px sólido --border
• Sombra en modo claro, sin sombra en modo oscuro
• Relleno: 24px en escritorio, 16px en móvil
• Al pasar el ratón: --surface-hover con sombra ligeramente elevada (solo modo claro)

Cuadrículas (Dashboard/Métricas/Tarjetas):

• Usa CSS Grid: grid-template-columns: repeat(auto-fit, minmax(300px, 1fr))
• Espaciado entre elementos de la cuadrícula: gap de 20px
• Al menos 2 columnas en escritorio, 1 columna por debajo de 640px
• Columnas de ancho fijo (por ejemplo, barra lateral de 320px) para diseños de dashboard

Tablas:

• Encabezados con fondo --surface, texto --text-secondary, peso 500
• Filas alternas con fondo --surface para mejor legibilidad (tr:nth-child(even))
• Celdas con relleno de 12px 16px
• Alineación del texto: números a la derecha, texto a la izquierda
• Ajuste de texto con white-space: nowrap para evitar que las columnas se rompan

Navegación (Tabs/Pasos):

• Pestañas con borde inferior (2px, --border), pestaña activa con borde --accent
• Indicador de paso: círculo numérico (24px, --accent), línea de conexión (--border)
• Barra de progreso: altura 4px, relleno --accent, fondo --surface

Efectos de Desplazamiento:

• Tarjetas: elevación sutil (modo claro), sin cambios (modo oscuro)
• Botones: opacity: 0.9 / scale: 1.02 — sin movimiento excesivo
• Enlaces: cambio de color, sin subrayado a menos que sea hover
• Tablas: resaltado de fila con background-color: var(--surface-hover)
• Desplazamiento suave en toda la página con scroll-behavior: smooth

Animaciones

Reglas de Animación de Entrada:

1. Los elementos visibles inicialmente en la carga deben animarse desde opacity: 0 para evitar el parpadeo del contenido. Para elementos del pliegue superior, establece opacity: 0 y usa animation-fill-mode: forwards.
2. Los elementos del pliegue inferior deben envolverse en un Intersection Observer o simplemente usar animation-delay (concatenado).
3. Las animaciones DEBEN respetar @media (prefers-reduced-motion: reduce) con una duración de 0s.
4. Las animaciones no deben retrasar la interacción del usuario — usa animation-fill-mode: both.

Animaciones Recomendadas:

• Las tarjetas aparecen con un translateY de 20px y opacity de 0 a 1
• Los gráficos se desvanecen (sin escala ni rotación)
• El texto solo aparece (sin movimiento en el eje X)
• Las barras de progreso se llenan de izquierda a derecha

Retrasos Escalonados:

• Usa la variable --i para escalonar: transition-delay: calc(var(--i) * 100ms)
• No más de 500ms de retraso total para cualquier elemento
• Los elementos deben animarse en orden de lectura (arriba a abajo, izquierda a derecha)

Animaciones Prohibidas:

• ❌ Fondos animados (gradientes en movimiento, partículas)
• ❌ Rotaciones continuas (loaders/spinners no relacionados con la carga de datos)
• ❌ Parpadeo o destellos
• ❌ Efectos hover que mueven todo el diseño

Accesibilidad

Contraste de Color:

• Relación de contraste de texto sobre fondo: ≥4.5:1 (AA) para texto de tamaño normal, ≥3:1 para texto grande (>18px normal o >14px negrita)
• Las propiedades personalizadas CSS deben mantenerse mediante comprobaciones de contraste, no de forma adivinatoria
• La superposición de temas debe mantener la relación de contraste sin necesidad de ajustes manuales

Navegación:

• Orden de tabulación lógico: navegación → contenido principal → pie de página
• Las superposiciones modales/de menú deben atrapar el foco
• Los enlaces de salto al contenido deben ser visibles al enfocarse (no ocultos para siempre)

Lector de Pantalla:

• Los botones de icono requieren aria-label
• Los gráficos requieren role="img" y aria-label descriptivo
• Las regiones de la página: <header>, <main>, <footer>, <nav> con aria-label descriptivos
• Usa aria-live="polite" para contenido que se actualiza dinámicamente

Rendimiento:

• No más de 2 bibliotecas externas (más allá del esqueleto base)
• Las animaciones preferiblemente deben usar transform y opacity (aceleradas por GPU)
• Archivo de salida por debajo de 2MB (los CDN no cuentan, solo el contenido HTML en línea)

Pulido Visual

Prácticas:

• Usa box-sizing: border-box universal
• Espaciado entre elementos: Consulta la tabla de espaciado del sistema de diseño
• Usa variantes de fuente: Regular 400, Medium 500, SemiBold 600, Bold 700
• Ajuste de texto: text-wrap: balance para encabezados, text-wrap: pretty para párrafos
• Evita usar !important a menos que sea para anular estilos de CDN
• Agrupa selectores de consultas de medios para un CSS más limpio

Técnicas:

• Capas de fondo para profundidad (usando pseudo-elementos y --surface)
• Cuadrícula de puntos sutil para fondos de sección (usando background-image: radial-gradient)
• Separadores de sección (borde inferior simple con --border, sin SVG ondulados)
• Badges, etiquetas y chips con border-radius: 6px, relleno 4px 10px, font-size: 0.8rem
• Animaciones de acordeón con grid-template-rows: 0fr a 1fr para transiciones suaves de altura

Patrones a Evitar:

• ❌ Fondos de cuadrícula ruidosos
• ❌ Degradados como fondos de sección
• ❌ Sombras de texto excesivas (text-shadow)
• ❌ Imágenes de marcador de posición (usa background: var(--surface) en su lugar)
• ❌ SVG decorativos que no son iconos funcionales
• ❌ Efectos de vidrio esmerilado (a menos que el usuario lo solicite explícitamente)

Referencias

Este readme sirve como especificación de origen para la habilidad de visualización. Las subpáginas de referencia proporcionan detalles de implementación adicionales:

• references/skeleton.md — Plantilla base que DEBE ser copiada para cada visualización. Contiene todos los elementos no negociables (sistema de menú, sistema de temas, HTML semántico, etc.)
• references/libraries.md — Enlaces CDN detallados, patrones de uso y consejos para todas las bibliotecas compatibles
• references/design-system.md — Especificaciones completas de tipografía, color, espaciado, animación, accesibilidad y pulido visual

Referencias de Versiones

• Chart.js v4.4.7 — Usa <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/chart.umd.min.js"></script>
• html-to-image v1.11.11 — Usa <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/html-to-image.js"></script>
• Mermaid v11 — Usa <script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
• D3 v7 — Usa <script src="https://cdn.jsdelivr.net/npm/d3@7"></script>
• Leaflet v1.9 — Usa <link rel="stylesheet" href="https://unpkg.com/[email protected]/dist/leaflet.css" /> y <script src="https://unpkg.com/[email protected]/dist/leaflet.js"></script>
• Reveal.js — Usa la versión estable más reciente del CDN de jsdelivr. Combínalo con highlight.js para el resaltado de sintaxis si es necesario.
• Inter 4.1 — Usa https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700;800;900&display=swap