HTML View
node <skill-dir>/scripts/htmlview is the cross-platform command entry point; below abbreviated as htmlview. Requires Node.js 22+; browser inspection, screenshot, export, and standalone chart rendering also require Chrome or Chromium. If no browser is found, follow error.next.
Existing HTML: Just Change Theme
- htmlview artifacts: For documents, reports, or single-chart pages, use
htmlview style file.html --theme cloudmusic(list themes withhtmlview style --list); for UI mockups, use--schemeor--brand.styleupdates in place, only restructuring the outer shell and derivative charts. To output a new file, first copy to an unused filename in the same directory, runstyleon the copy, then compare withhtmlview diff. - Plain HTML:
styledoes not accept plain HTML. When you need the skill's shell, create a themed document (see Document Flow and Document Components), migrate existing content into the new file; do not reuse CSS and scripts from the old shell. When only changing the style, preserve original numbers, time granularity, and conclusions; do not recalculate data or drop details from original charts just to pass display checks.
Choose Entry by Task
| User Wants | Approach | When to Expand |
|---|---|---|
| Technical plan, report, explanation, minutes, or one-pager for easy reading and annotation | If Markdown exists, use doc build; to edit HTML directly, use doc new | First read Document Flow; when writing HTML components, adding cross-references, or handling comments, read Document Components |
| Report or Dashboard with business figures, definitions, and charts to verify | Build data package from upstream summary files; data validate then data build | First read Data Flow; when modifying fields, metrics, charts, or narrative, read Data Package; for Dashboards, read Dashboard Design |
| Wireframes, high-fidelity mockups, or prototypes showing screens, states, or interaction flows | ui new then fill each screen with real control values | First read UI Mockup Flow; when selecting components or writing interactions, read Component Index; when setting layout, color scheme, or writing custom components, read UI Design; for data dashboards, read Dashboard Design |
| Single SVG or offline chart page | Select chart family from table below, write declaration, then viz render | For data charts, first read Declaration Common, then the selected chart family; for structural diagrams, read the corresponding chart family directly |
| Read, inspect, screenshot, or export local HTML | Use read, check, shot, export, or embed | See Display and Export for parameters and inspection results |
- When source material is not in page-ready format (e.g., scattered notes, meeting minutes, JSON, CSV, logs, or Markdown that needs restructuring), read From Source to Page before writing content.
- HTML artifacts are single files that can be opened offline. When hand-editing, only change the title and content between
<!-- htmlview:content -->and<!-- /htmlview:content -->; each marker appears exactly once. Layout, theme, and runtime scripts are assembled by the CLI. - Modify the Markdown source for documents built from Markdown; modify the data package for data reports, not the generated text, charts, or numbers. Do not fabricate data without a source; demo data must be labeled as fictitious examples.
- To overwrite existing standalone artifacts, use
--forceonly after confirming the target; updates to same-source documents do not require--force. - When
--langis not passed, generation commands infer the language for figure numbers, table of contents, legends, and other shell wording from the title and body: use English if the English word count is at least twice the CJK character count, otherwise use Chinese. For other languages or mixed content, explicitly pass--lang.
Choose Chart by What Reader Wants to See
Use static charts by default. Use KChart JSON for data charts; use Mermaid or native declarations for structural relationships. First check Configuration, Styles, Links, and Diagnostics Common, then the specific chart type; KChart does not replicate Mermaid's appearance. Only fill in data, semantics, and reading intent; do not write coordinates, font sizes, colors, or plotting scripts. Charts can scroll if content overflows; the page itself should not overflow horizontally.
| Reader Question | Chart Entry | Read as Needed |
|---|---|---|
| How does it change? When does it change? | line, area, sparkline, small-multiples, stream, combo, bump, candlestick, launch-fan | Trend |
| Which is bigger? How much difference? How far from target? | bar, column, dumbbell, slope, bullet, gauge, interval, split-compare | Comparison |
| How is the total composed? How much is lost at each step? | share, pie, donut, radial-share, rose, funnel, waterfall, waffle, tally, treemap, sunburst | Composition |
| How are values distributed? Any outliers or correlations? | histogram, boxplot, violin, strip, scatter | Distribution |
| Where are anomalies in a multi-dimensional matrix or calendar? | heatmap, bubble-matrix, calendar, radar, parallel | Matrix |
| Who connects to whom? How does volume flow? | network, sankey, threads | Network |
| Where is it distributed? | choropleth, geo-scatter | Maps |
| How to classify? How to expand from a topic? | KChart tree, mindmap; Mermaid mindmap, ishikawa, treeView-beta | Hierarchy and Mind Map |
| Who goes through what process? How does state transfer? | flowchart, stateDiagram-v2, journey, swimlane-beta, eventmodeling, agentflow-beta, native swimlane | Flow |
| Call order and participants? | sequenceDiagram, usecase-beta | Sequence |
| How to schedule, columnize, or number? | gantt, timeline, gitGraph, kanban, packet, quadrantChart | Time and Grid |
| How do entities, classes, or requirements relate? | erDiagram, classDiagram, requirementDiagram | Data Model |
| How does a syntax rule match symbols? | railroad-beta, railroad-ebnf-beta, railroad-abnf-beta, railroad-peg-beta | Data Model |
| How is the system layered? Where are containers and dependencies? | C4Context, C4Container, C4Component, C4Dynamic, C4Deployment, architecture-beta, block, wardley-beta, native layers, blocks | Architecture |
| One-page overview: cards in groups, main flow, and legend? | Native blocks (cards, badges, legends, emphasis lines); existing Mermaid block diagrams use block | Architecture |
| Have existing Mermaid value charts? | pie, xychart, sankey, radar-beta, treemap | Mermaid Value Charts; new data charts use KChart types above |
| How do sets overlap? How to classify scenarios? | venn-beta, cynefin-beta | Set, Scenario |
| Call diagram using ZenUML syntax? | zenuml (native KChart rendering, no external plugin needed) | ZenUML |
| Just want to confirm renderer version? | Mermaid info (not for delivery) | Mermaid Common |
Use kchart, mermaid, layers, blocks, swimlane fences in Markdown; in hand-written HTML, use <pre data-viz="syntax"> and escape HTML special characters in it. Write chart titles in declarations: KChart title, structural diagram preamble title: or the syntax's supported title statement. Chart titles and text should be in the same language as the body. If built-in chart families cannot express the content (e.g., too deeply nested, too many relationships, or mechanism illustration), first split into an overview chart and sub-charts; if still needed, read Hand-Drawn SVG.
Command Quick Reference
| Action | Command |
|---|---|
| Draft document / generate from source | htmlview doc new plan.html --type plan --title 'Capacity Evaluation Plan' or htmlview doc build spec.md --out spec.html --type tech-spec |
| Data package and report | htmlview data init example → htmlview data validate example/report.json → htmlview data build example/report.json --out report.html |
| UI mockup skeleton | htmlview ui new prototype.html --title 'Application Processing' --device mobile --screens 'List, Details' |
| Static review, content comparison | htmlview audit file.html; htmlview diff old.html new.html |
| Reload chart module for document or UI mockup | htmlview style file.html (preserves existing theme and content) |
| Display inspection, screenshot, export | htmlview check file.html; htmlview shot file.html --select 'figure'; htmlview export file.html --format pdf; full-page image htmlview export file.html --format png |
| Read content, embed local resources | htmlview read file.html [--outline or --section id]; htmlview embed file.html |
| Standalone chart, field constraints, theme colors, custom chart text sizing | htmlview viz render spec.json --out chart.svg; htmlview viz schema bar; htmlview viz palette --theme paper; htmlview viz measure 'Order Service' --size 13 |
When users provide their own color scheme, use --theme-file <JSON>; fields and examples in Theme File. Themes are embedded in the HTML; UI mockups use independent brand color schemes.
htmlview <subcommand> --help gives precise parameters. For inspection commands, pass:false means the check completed but found issues; fix according to failures[].fix. ok:false means the command did not complete; follow error.next.
Validate Before Delivery
- Run
auditafter creating or modifying an artifact. If chart modules are missing, runstyleto restructure, then audit again; if reports have inconsistent evidence, correct the data package. - For changes that affect display, run
check, thenshotto view the actual screenshot. Check heading hierarchy, text attribution, whitespace, and mobile first screen; for wide charts, open the full SVG to inspect. For interactive prototypes, manually click through critical paths. - When delivering a PDF, open the actual PDF and verify that chart titles and bodies are on the same page and edges are intact. If print hints appear, switch to a suitable paper size or adjust layout while maintaining readable font sizes; if complete printing is impossible, document the limitation.