HTML View
node <skill-dir>/scripts/htmlview es el punto de entrada del comando multiplataforma; a continuación, se usará la abreviatura htmlview. Requiere Node.js 22+. La verificación del navegador, la captura de pantalla, la exportación y el renderizado independiente de gráficos también necesitan Chrome o Chromium. Si no se encuentra el navegador, se maneja según error.next.
HTML existente: Solo cambiar tema
- Artefactos de
htmlview: Para documentos, informes o páginas de gráficos individuales, usahtmlview style file.html --theme cloudmusic(consultahtmlview style --listpara ver los temas); para prototipos de interfaz, usa--schemeo--brand.styleactualiza el lugar, solo reorganiza la carcasa y los gráficos derivados. Para generar un archivo nuevo, primero copia el archivo a un nombre no utilizado en el mismo directorio, ejecutastyleen la copia y luego usahtmlview diffpara comparar el contenido. - HTML normal:
styleno acepta HTML normal. Si es necesario usar la carcasa de la habilidad, crea un documento de tema nuevo (consulta Flujo de documentos y Componentes de documentos), migra el contenido existente al nuevo archivo; no reutilices el CSS ni los scripts de la carcasa anterior. Al solo cambiar el estilo, conserva los números, la granularidad de tiempo y las conclusiones originales; no recalculas los datos ni elimines detalles de la imagen original para pasar la verificación visual.
Seleccionar entrada según la tarea
| Lo que el usuario quiere | Qué hacer | Cuándo expandir |
|---|---|---|
| Propuesta técnica, informe, explicación, acta o resumen de una página fácil de leer y anotar | Si hay Markdown, usa doc build; si editas HTML directamente, usa doc new | Primero lee Flujo de documentos; al escribir componentes HTML a mano, agregar referencias cruzadas o procesar comentarios, lee Componentes de documentos |
| Informe o Dashboard para verificar cifras de negocio, métricas y gráficos | Crea un paquete de datos a partir del archivo de resumen ascendente; después de data validate, ejecuta data build | Primero lee Flujo de informes; al modificar campos, métricas, gráficos o narrativa, lee Paquete de datos; al hacer Dashboard, lee Diseño de panel |
| Esquemas, maquetas de alta fidelidad o prototipos que muestren pantallas, estados o flujos de interacción | Después de ui new, completa cada pantalla y usa valores reales de los controles | Primero lee Flujo de prototipos de interfaz; al seleccionar componentes o escribir interacciones, lee Índice de componentes; al definir diseños, colores o escribir componentes a mano, lee Diseño de interfaz; al dibujar paneles de datos, lee Diseño de panel |
| Gráfico SVG único o página de gráficos sin conexión | Selecciona la familia de gráficos en la tabla siguiente, escribe la declaración y luego viz render | Para gráficos de datos, primero lee Reglas generales de declaración; luego lee la familia de gráficos seleccionada; para diagramas estructurales, lee directamente la familia de gráficos correspondiente |
| Leer, inspeccionar, capturar o exportar HTML local | Usa read, check, shot, export o embed | Los parámetros y los resultados de la verificación se encuentran en Visualización y exportación |
- Cuando el material no es una estructura de página predefinida, como notas sueltas, actas de reuniones, JSON, CSV, registros o Markdown que necesita reorganización, antes de escribir el contenido, lee Del material a la página.
- Los artefactos HTML son archivos individuales que se pueden abrir sin conexión. Al escribirlos a mano, solo modifica el título y el contenido entre
<!-- htmlview:content -->y<!-- /htmlview:content -->; cada marcador se conserva una vez. El diseño, el tema y los scripts de ejecución los ensambla la CLI. - Los documentos construidos con Markdown modifican la fuente Markdown; los informes de datos modifican el paquete de datos, no el texto, gráficos o números generados directamente. No se pueden inventar datos sin fuente; los datos de demostración deben indicarse como ejemplos ficticios.
- Para sobrescribir artefactos independientes existentes, confirma el objetivo antes de usar
--force; la actualización de documentos de la misma fuente no necesita--force. - Cuando no se pasa
--lang, el comando de generación infiere el idioma de las expresiones del shell (títulos de figuras, índices, leyendas, etc.) a partir del título y el cuerpo: se usa inglés si la cantidad de palabras en inglés es al menos el doble de la cantidad de caracteres CJK; de lo contrario, se usa chino. Para otros idiomas o contenido mitad inglés y mitad chino, pasa explícitamente--lang.
Seleccionar gráfico según lo que el lector quiere ver
Por defecto se usan gráficos estáticos. Los gráficos de datos usan KChart JSON; los diagramas estructurales usan Mermaid o declaraciones nativas. Primero consulta las reglas generales de configuración, estilo, enlaces y diagnóstico; luego consulta el tipo de gráfico correspondiente. KChart no copia la apariencia de Mermaid. Solo completa los datos, la semántica y la intención de lectura; no escribas coordenadas, tamaños de fuente, colores ni scripts de dibujo. Los gráficos pueden tener desplazamiento interno si no caben; la página en sí no debe desbordarse horizontalmente.
| Pregunta del lector | Entrada del tipo de gráfico | Lectura según necesidad |
|---|---|---|
| ¿Cómo cambia? ¿Cuándo cambia? | line, area, sparkline, small-multiples, stream, combo, bump, candlestick, launch-fan | Tendencia |
| ¿Cuál es más grande? ¿Cuánta diferencia hay? ¿Qué tan lejos del objetivo? | bar, column, dumbbell, slope, bullet, gauge, interval, split-compare | Comparación |
| ¿Cómo se compone el total? ¿Cuánto se pierde en cada paso? | share, pie, donut, radial-share, rose, funnel, waterfall, waffle, tally, treemap, sunburst | Composición |
| ¿Cómo se distribuyen los valores? ¿Hay valores atípicos o correlaciones? | histogram, boxplot, violin, strip, scatter | Distribución |
| ¿Dónde hay anomalías en una matriz multidimensional o un calendario? | heatmap, bubble-matrix, calendar, radar, parallel | Matriz |
| ¿Quién se conecta con quién? ¿Cómo fluye la cantidad? | network, sankey, threads | Red |
| ¿Dónde se distribuye? | choropleth, geo-scatter | Mapas |
| ¿Cómo se clasifica? ¿Cómo se expande desde un tema? | KChart tree, mindmap; Mermaid mindmap, ishikawa, treeView-beta | Jerarquía y mapa mental |
| ¿Cómo fluye el proceso de quién a quién? ¿Cómo se transfieren los estados? | flowchart, stateDiagram-v2, journey, swimlane-beta, eventmodeling, agentflow-beta, nativo swimlane | Flujo |
| ¿Quiénes son las llamadas secuenciales y los participantes? | sequenceDiagram, usecase-beta | Secuencia |
| ¿Cómo programar, dividir en columnas o numerar? | gantt, timeline, gitGraph, kanban, packet, quadrantChart | Tiempo y cuadrícula |
| ¿Cómo se relacionan entidades, clases o requisitos? | erDiagram, classDiagram, requirementDiagram | Modelo de datos |
| ¿Cómo coincide una regla gramatical con los símbolos? | railroad-beta, railroad-ebnf-beta, railroad-abnf-beta, railroad-peg-beta | Modelo de datos |
| ¿Cómo se divide el sistema en capas, contenedores y dependencias? | C4Context, C4Container, C4Component, C4Dynamic, C4Deployment, architecture-beta, block, wardley-beta, nativo layers, blocks | Arquitectura |
| ¿Resumen de una página: tarjetas en grupos, flujo principal y leyendas? | Nativo blocks (tarjetas, insignias, leyendas, líneas de énfasis); si ya hay un diagrama de bloques de Mermaid, block | Arquitectura |
| ¿Ya tienes un gráfico numérico de Mermaid? | pie, xychart, sankey, radar-beta, treemap | Gráficos numéricos de Mermaid; para nuevos gráficos de datos, usa los tipos KChart anteriores |
| ¿Cómo se superponen los conjuntos? ¿Cómo se clasifican los escenarios? | venn-beta, cynefin-beta | Conjuntos, Escenarios |
| ¿Diagrama de llamadas usando sintaxis ZenUML? | zenuml (renderizado nativo por KChart, sin complementos externos) | ZenUML |
| ¿Solo quieres confirmar la versión del renderizador? | Mermaid info (no para entrega) | Reglas generales de Mermaid |
Markdown usa vallas kchart, mermaid, layers, blocks, swimlane; HTML escrito a mano usa <pre data-viz="sintaxis">, escapando los caracteres HTML especiales. Los títulos de las figuras se escriben en la declaración: KChart title, prefacio del diagrama estructural title: o la declaración de título compatible con esa sintaxis. Los títulos de las figuras y el texto dentro de las figuras usan el mismo idioma que el cuerpo. Cuando la familia de figuras incorporada no es suficiente o no se puede expresar, como anidamiento demasiado profundo, demasiadas relaciones o ilustración de mecanismos, primero divide en una figura general y figuras secundarias; si aún es necesario dibujar a mano, consulta SVG personalizado.
Referencia rápida de comandos
| Qué hacer | Comando |
|---|---|
| Redactar documento / Generar desde fuente | htmlview doc new plan.html --type plan --title 'Plan de evaluación de capacidad' o htmlview doc build spec.md --out spec.html --type tech-spec |
| Paquete de datos e informe | htmlview data init example → htmlview data validate example/report.json → htmlview data build example/report.json --out report.html |
| Esqueleto de prototipo de interfaz | htmlview ui new prototype.html --title 'Procesamiento de solicitud' --device mobile --screens 'Lista, Detalle' |
| Auditoría silenciosa, comparación de contenido | htmlview audit file.html; htmlview diff old.html new.html |
| Recargar módulos de figuras para documento o prototipo | htmlview style file.html (conserva el tema y el contenido existentes) |
| Verificación visual, captura de pantalla, exportación | htmlview check file.html; htmlview shot file.html --select 'figure'; htmlview export file.html --format pdf; imagen de página completa htmlview export file.html --format png |
| Leer cuerpo, incrustar recursos locales | htmlview read file.html [--outline o --section id]; htmlview embed file.html |
| Figura independiente, restricciones de campo, color del tema, medir cantidad de texto de figura hecha a mano | htmlview viz render spec.json --out chart.svg; htmlview viz schema bar; htmlview viz palette --theme paper; htmlview viz measure 'Servicio de pedidos' --size 13 |
Cuando el usuario proporciona su propia paleta, usa --theme-file <JSON>; los campos y ejemplos se encuentran en Archivo de tema. El tema está incrustado en el HTML; los prototipos de interfaz usan colores de marca independientes.
htmlview <subcomando> --help proporciona parámetros precisos. pass:false en comandos de verificación significa que la verificación se completó pero se encontraron problemas; repara según failures[].fix. ok:false significa que el comando no pudo completarse; maneja según error.next.
Verificar antes de entregar
- Después de crear o modificar un artefacto, ejecuta
audit. Si faltan módulos de figuras, ejecutastylepara reorganizar y luego auditar; si el informe tiene inconsistencias en la evidencia, corrige el paquete de datos. - Para cambios que afecten la visualización, ejecuta
checky luegoshotpara abrir la captura de pantalla real. Revisa los niveles de títulos, la pertenencia del texto, los espacios en blanco y la primera pantalla en dispositivos móviles; para figuras anchas, abre el SVG completo para inspeccionar. Para prototipos interactivos, recorre los caminos críticos manualmente. - Al entregar PDF, abre el PDF real y verifica que el título de la figura y la figura estén en la misma página y que los bordes estén completos. Si aparecen indicaciones de impresión, cambia al tamaño de papel adecuado o ajusta el diseño, manteniendo un tamaño de fuente legible; si no se puede imprimir correctamente, explica la limitación.