HTML View は何をしますか?
node <skill-dir>/scripts/htmlview はクロスプラットフォームコマンドエントリです。以下 htmlview と省略します。Node.js 22+ が必要です。ブラウザチェック、スクリーンショット、エクスポート、スタンドアロン図のレンダリングにはChromeまたはChromiumが必要です。ブラウザが見つからない場合は error.next に従って処理します。
既存HTML:テーマのみ変更
- htmlview 成果物:ドキュメント、レポート、単一図ページには
htmlview style file.html --theme cloudmusic(htmlview style --listでテーマ一覧)。UIモックアップには--schemeまたは--brandを使用します。styleはその場で更新し、外殻と派生図のみを再構成します。新しいファイルに出力するには、同じディレクトリで未使用のファイル名にコピーし、コピーに対してstyleを実行し、その後htmlview diffで内容を比較します。 - 通常のHTML:
styleは通常のHTMLを受け付けません。スキル外殻が必要な場合は、新しいテーマドキュメントを作成し(ドキュメントフロー と ドキュメントコンポーネント を参照)、既存の内容を新しいファイルに移行します。古い外殻のCSSやスクリプトは引き継ぎません。スタイルのみを変更する場合は、元の数字、時間粒度、結論を保持し、データを再計算せず、表示チェックを通過させるために元の図の詳細を破棄しません。
タスク別エントリ選択
| ユーザーが求める結果 | 方法 | いつ展開するか |
|---|---|---|
| 読みやすく注釈可能な技術提案書、レポート、説明書、議事録、一枚紙 | Markdownがある場合は doc build。HTMLを直接編集する場合は doc new | まずドキュメントフローを読む。HTMLコンポーネントを手書きしたり、相互参照を追加したり、コメントを処理する場合はドキュメントコンポーネントを読む |
| 経営数値、定義、グラフを確認したいレポートやダッシュボード | 上流の集計ファイルからデータパッケージを作成。data validate の後 data build | まずレポートフローを読む。フィールド、指標、グラフ、記述を変更する場合はデータパッケージを読む。ダッシュボードを作成する場合はダッシュボードデザインを読む |
| 画面、状態、インタラクションフローを表示するワイヤーフレーム、高忠実度モックアップ、プロトタイプ | ui new の後、各画面を埋め、実際のコントロールを使用して値を取得 | まずUIモックアップフローを読む。コンポーネントの選択やインタラクションの記述にはコンポーネントインデックスを読む。レイアウト、配色、手書きコンポーネントの場合はUIデザインを読む。データダッシュボードを描画する場合はダッシュボードデザインを読む |
| 単一SVGまたはオフライン図ページ | 下の図族テーブルから選択し、宣言を記述して viz render | データ図はまず宣言共通ルールを読み、次に選択した図族を読む。構造図は対応する図族を直接読む |
| ローカルHTMLの読み取り、チェック、スクリーンショット、エクスポート | read、check、shot、export、embed を使用 | パラメータとチェック結果は表示とエクスポートを参照 |
- 素材が既製のページ構造でない場合(例:断片的なメモ、会議記録、JSON、CSV、ログ、再配置が必要なMarkdown)は、内容を記述する前に素材からページへを読んでください。
- HTML成果物はオフラインで開ける単一ファイルです。手書きする場合は、タイトルと
<!-- htmlview:content -->と<!-- /htmlview:content -->の間の内容のみを変更します。各マークは1回だけ保持し、レイアウト、テーマ、実行スクリプトはCLIが組み立てます。 - Markdownから構築されたドキュメントはMarkdownソースを変更します。データレポートはデータパッケージを変更し、生成されたテキスト、グラフ、数字を直接変更しません。ソースのないデータは捏造してはいけません。デモデータは架空の例であることを明記してください。
- 既存の独立した成果物を上書きする場合は、ターゲットを確認した後に
--forceを使用します。同一ソースのドキュメント更新には--forceは不要です。 --langが指定されていない場合、生成コマンドはタイトルと本文から図番号、目次、凡例などの外殻用語を推測します。英単語数が中日韓文字数の2倍以上の場合は英語、それ以外は中国語を使用します。他の言語や中英半々の内容は明示的に--langを指定します。
読者が見たいものによる図の選択
デフォルトでは静的図を使用します。データ図にはKChart JSONを使用。構造関係にはMermaidまたはネイティブ宣言を使用します。まず設定、スタイル、リンク、診断の共通ルールを確認し、次に対応する図形を確認します。KChartはMermaidの外観をそのままコピーしません。データ、セマンティクス、読み取り意図のみを記述し、座標、フォントサイズ、色、描画スクリプトは記述しません。図内に収まらない場合はスクロール可能にし、ページ自体は横方向にはみ出さないようにします。
| 読者の質問 | 図形エントリ | 必要に応じて読む |
|---|---|---|
| どのように変化するか、いつ変わるか? | line、area、sparkline、small-multiples、stream、combo、bump、candlestick、launch-fan | トレンド |
| どちらが大きいか、どのくらい差があるか、目標からどれだけ離れているか? | bar、column、dumbbell、slope、bullet、gauge、interval、split-compare | 比較 |
| 合計はどのように構成されているか、各ステップでどれだけ損失があるか? | share、pie、donut、radial-share、rose、funnel、waterfall、waffle、tally、treemap、sunburst | 構成 |
| 数値はどのように分布しているか、外れ値や相関はあるか? | histogram、boxplot、violin、strip、scatter | 分布 |
| 多次元行列やカレンダーでどこに異常があるか? | heatmap、bubble-matrix、calendar、radar、parallel | 行列 |
| 誰が誰と接続されているか、量はどのように流れているか? | network、sankey、threads | ネットワーク |
| どこに分布しているか? | choropleth、geo-scatter | 地図 |
| どのように分類するか、トピックからどのように展開するか? | KChart tree、mindmap;Mermaid mindmap、ishikawa、treeView-beta | 階層とマインドマップ |
| プロセスは誰から誰へ、状態はどのように遷移するか? | flowchart、stateDiagram-v2、journey、swimlane-beta、eventmodeling、agentflow-beta、ネイティブ swimlane | フロー |
| 呼び出しの順序と参加者は誰か? | sequenceDiagram、usecase-beta | シーケンス |
| どのようにスケジュール、カラム、番号付けするか? | gantt、timeline、gitGraph、kanban、packet、quadrantChart | 時間とグリッド |
| エンティティ、クラス、要件はどのように関連しているか? | erDiagram、classDiagram、requirementDiagram | データモデル |
| 構文規則がどのようにシンボルと一致するか? | railroad-beta、railroad-ebnf-beta、railroad-abnf-beta、railroad-peg-beta | データモデル |
| システムはどのように階層化されているか、コンテナと依存関係はどこにあるか? | C4Context、C4Container、C4Component、C4Dynamic、C4Deployment、architecture-beta、block、wardley-beta、ネイティブ layers、blocks | アーキテクチャ |
| 1ページ概要:グループ内のカード、メインフロー、凡例? | ネイティブ blocks(カード、バッジ、凡例、強調線)。既存のMermaidブロック図がある場合は block | アーキテクチャ |
| 既存のMermaid数値図があるか? | pie、xychart、sankey、radar-beta、treemap | Mermaid数値図。新しいデータ図は上記のKChart図形を使用 |
| 集合はどのように重なるか、コンテキストはどのように分類されるか? | venn-beta、cynefin-beta | 集合、コンテキスト |
| ZenUML構文を使用した呼び出し図? | zenuml(KChartネイティブレンダリング、外部プラグイン不要) | ZenUML |
| レンダラーバージョンの確認のみ? | Mermaid info(納品には使用しない) | Mermaid共通ルール |
Markdownでは kchart、mermaid、layers、blocks、swimlane フェンスを使用。手書きHTMLでは <pre data-viz="構文"> を使用し、HTML特殊文字をエスケープします。ドキュメントの図タイトルは宣言に記述します。KChart title、構造図の前言 title: または構文がサポートするタイトル文。図タイトルと図内テキストは本文と同じ言語を使用します。組み込み図族で収まらない、または表現できない場合(ネストが深すぎる、関係が多すぎる、メカニズムの図解など)は、まず全体図と部分図に分割します。それでも手書きが必要な場合は手書きSVGを読んでください。
コマンドクイックリファレンス
| やりたいこと | コマンド |
|---|---|
| ドキュメント起草/ソースから生成 | htmlview doc new plan.html --type plan --title '容量評価計画' または htmlview doc build spec.md --out spec.html --type tech-spec |
| データパッケージとレポート | htmlview data init example → htmlview data validate example/report.json → htmlview data build example/report.json --out report.html |
| UIモックアップスケルトン | htmlview ui new prototype.html --title '申請処理' --device mobile --screens 'リスト,詳細' |
| 静的分析、内容比較 | htmlview audit file.html;htmlview diff old.html new.html |
| ドキュメントまたはUIモックアップの図モジュール再読み込み | htmlview style file.html(既存のテーマと内容を保持) |
| 表示チェック、スクリーンショット、エクスポート | htmlview check file.html;htmlview shot file.html --select 'figure';htmlview export file.html --format pdf;ページ全体の長尺画像 htmlview export file.html --format png |
| 本文の読み取り、ローカルリソースの埋め込み | htmlview read file.html [--outline または --section id];htmlview embed file.html |
| スタンドアロン図、フィールド制約、テーマカラー、手書き図の文字数測定 | htmlview viz render spec.json --out chart.svg;htmlview viz schema bar;htmlview viz palette --theme paper;htmlview viz measure '注文サービス' --size 13 |
ユーザーが独自の配色を持ち込む場合は --theme-file <JSON> を使用します。フィールドと例はテーマファイルを参照してください。テーマはHTMLに埋め込まれます。UIモックアップは独立したブランド配色を使用します。
htmlview <サブコマンド> --help で正確なパラメータを取得できます。チェック系コマンドの pass:false はチェックは完了したが問題が見つかったことを意味します。failures[].fix に従って修正します。ok:false はコマンドが完了できなかったことを意味し、error.next に従って処理します。
検証してから納品
- 新規作成または変更後は
auditを実行します。図モジュールがない場合はstyleを実行して再構成し、再度監査します。レポートに証拠の不一致がある場合はデータパッケージに戻って修正します。 - 表示に影響を与える変更には
checkを実行し、次にshotで実際のスクリーンショットを開きます。見出し階層、テキストの帰属、余白、スマートフォンのファーストビューを確認します。ワイド図は完全なSVGを開いて確認します。インタラクティブなプロトタイプは実際に重要なパスをクリックしてテストします。 - PDFを納品する場合は実際のPDFを開き、図タイトルと図本体が同じページにあり、端が欠けていないことを確認します。印刷に関するプロンプトが表示された場合は、適切な用紙サイズに変更するかレイアウトを調整し、読みやすいフォントサイズを維持します。完全に印刷できない場合は制限を説明します。