visual-html-renderer

name	visual-html-renderer
description	HTMLを最終成果物として生成・検証・プレビューしたい時に使う共通レンダラー。Use this shared renderer when the user wants content turned into a final, validated, previewable HTML artifact. 現行rendererの表現能力を前提にagentが文書モデルを直接設計し、表・リスト・コード・注記・図・生成画像を選んだHTML bundleとセッション限定のプレビューURLを提示する。Triggers: html出力して, HTMLにして, HTMLで出して, この内容をHTMLで出して, HTMLでプレビューして, HTMLレンダラー, HTML出力を共通化, 図示つきHTML, visual HTML renderer, render this as HTML, turn this into HTML, create an HTML preview, generate a visual HTML report, make this a reviewable HTML document, diagrammed HTML report。使用しない場面: Plan Mode 中の計画確認プレビュー、設計内容そのものの作成、Notion投稿だけ、既存HTMLの軽微な見た目修正だけ。Do not use for: Plan Mode proposal previews, creating the design content itself, Notion-only publishing, or minor visual tweaks to existing HTML.
argument-hint	[document-model.json] [--output output/<date>_<slug>] [--preview auto|tailscale|local|off]
strict_procedure	true

visual-html-renderer

役割

HTML出力系skillの共通レンダラーとして、個別HTML生成ロジックを置き換える。

重い処理は scripts/html_review_workbench/ のPython実装に委譲し、このskillは入力確認、呼び出し順、ガード、検証を担当する。

Role

Use this skill as the shared renderer for HTML-output workflows. It replaces one-off HTML generation logic with a fixed flow: understand the requested content, design the document model, run the shared CLI, validate the bundle, and return a preview URL. Heavy implementation stays in scripts/html_review_workbench/; this skill owns input handling, workflow order, gates, and verification.

Plan Mode 中の計画確認プレビューには、このskillを使わない。その場合は plan-preview を使い、一時HTML previewとして扱う。visual-html-renderer は通常の最終HTML成果物、レポート、レビュー可能な文書のbundle生成だけを担当する。

Do not use this skill for Plan Mode proposal previews. Route those requests to plan-preview; this skill is only for final HTML artifacts, reports, and reviewable document bundles.

Strict procedure profile

• Strictness: strict-procedure。HTML表現設計、文書モデルread-back、render、validate、preview URL提示までがこのskillの成果。
• Hard gates: 外部サービス送信、画像生成、外部アップロード、shared state変更は該当する承認ゲートに従う。
• Forcing function: rendererブロック対応表、render前自己レビュー、check-model CLI、Completion receipt。
• Completion receipt: HTML表現設計、生成物、検証、preview、未実施層を最終応答に必ず含める。

言語方針 / Language behavior

Follow the language of the latest user request for progress updates, final responses, preview handoff text, and user-facing summaries. 日本語の依頼には日本語で、英語の依頼には英語で返す。入力本文や引用内容は、ユーザーが翻訳を求めない限り勝手に翻訳しない。HTML内の見出しや本文は、元資料の言語、ユーザーの指定、レビュー対象読者に合わせる。

基本手順

0. Plan Mode 中の計画確認プレビュー、<proposed_plan> の視覚確認、計画URLの追加が目的なら、このskillではなく plan-preview を使う。
1. 文書モデルとレンダリングオプションを確認する。
2. 文書モデルが未指定の場合は、直前の成果物またはユーザー指定内容を読み、HTML表現設計フェーズで構成を決める。
3. 現行rendererのブロック型に合わせて、agentが document-model.json を直接作る。
4. 一時的な入力退避が必要な場合だけ build-model で source-capture draft を作ってよい。ただし draft は最終モデルではないため、そのまま render へ渡さない。
5. render前に document-model.json を読み返し、未再構成テキストの流し込みやrenderer非対応型の使用がないことを確認する。
6. image.generation_status=requested のブロックがある場合は、imagegen skillで画像を生成し、attach-image CLIで文書モデルへ添付する。
7. check-model CLIで最終render前の文書モデル品質を検査する。
8. render CLIでHTML bundleを生成する。
9. validate CLIでHTML、asset、comment schema、図・画像の非空を検証する。
10. ユーザー向け最終HTMLでは既定で preview CLIを --mode auto で起動し、返却JSONの url と stop_command を最終応答に必ず書く。
11. preview 起動直後に、Monitor ツールで watch-comments を開始する。これによりブラウザからのコメントを自動検知できるようになる。Monitor 起動コマンド: python3 -m scripts.html_review_workbench.cli watch-comments --root <output-dir>。自前の polling スクリプトではなく、この CLI を使うこと。イベント受信後の処理は reviewable-design-doc skill の「コメント自動回答と解決待ちゲート」セクションに従う。

Basic Workflow

0. If the request is a Plan Mode proposal preview, <proposed_plan> visual check, or plan preview URL request, use plan-preview instead of this skill.
1. Check the document model and rendering options.
2. If no document-model.json is provided, inspect the user's content or the latest artifact and design the HTML structure yourself.
3. Create the final document-model.json directly using the renderer-supported block types.
4. Use build-model only as a source-capture draft when temporary input storage is needed; never pass that draft straight to render.
5. Read back the model before rendering and confirm that raw or unsupported content was not dumped into the model.
6. If image blocks request generation, use the imagegen skill and attach images with attach-image.
7. Run check-model, then render, then validate, then preview.
8. For user-facing artifacts, use preview --mode auto by default and include the returned url and stop_command in the final response.
9. Start watch-comments immediately after preview startup so browser comments can be detected.

HTML情報設計の規約

HTML出力はテキスト変換ではなく、最終HTML bundleの情報設計として扱う。

• 入力本文の記号や行構造をそのまま表示へ流し込まない。
• まず内容の意味、用途、読者、比較軸、時系列、依存関係、操作手順、注意点を読み取り、HTML上の表現を選ぶ。
• 比較は表、手順は番号付きリスト、並列項目はリスト、注意・決定・前提はcallout、処理や依存関係はdiagramブロック、画面イメージや説明画像が有効な箇所はimageブロック、コマンドやログはコードブロックにする。
• diagramブロックはMermaid sourceを構造保存用に残し、既定では生成画像を主表示にする。生成画像が未添付の場合、全diagram kindを同梱 mermaid.js でブラウザ描画する。Mermaid v11系の記法に準拠してsourceを書く。CDNは使わず、standalone publishでは mermaid.js と図の拡大用scriptをHTMLへinline化する。
• Mermaidで描画される図は、図右上の拡大ボタンから全画面表示に切り替え、pan / zoom で詳細を確認できる。
• 現行rendererのブロック型で表現が足りない場合、未再構成テキストへ戻さず、必要なブロック型やレンダリング拡張を検討する。

• 一時入力ファイルが必要な場合も .md は使わない。source.txt, input.txt, source-content.txt のようなプレーンテキスト名を使う。
• ユーザーへの進捗・最終報告では、.md やMarkdownという語をHTML出力の前提として扱わない。

rendererブロック対応表

現行rendererで最終HTMLに使う表現は、実装上の描画挙動に合わせて選ぶ。

block type	rendererの扱い	contentに書くもの
html	HTML片をそのまま挿入する	agentが設計した <p>, <table>, <ul>, <ol>, <pre><code> 等の構造化HTML
callout	HTML escapeしてcallout表示する	決定、注意、前提などの短いプレーンテキスト。HTMLタグは書かない
diagram	Mermaid sourceを保存し、同梱 mermaid.js のブラウザ描画、または生成画像を表示する	diagram_source または diagram.source にMermaid v11系のsource。sourceに無い関係を画像側で追加しない
image	添付済み生成画像を表示する	image.prompt, image.alt, image.caption, image.source_path
section / text / table	専用描画なし。通常段落へescapeされる	最終HTMLモデルでは使わない。表は html block内の <table> で表現する

html blockはraw insertされるため、外部入力をそのまま混ぜない。入力由来の文字列はagentが意味単位へ再構成し、必要な箇所だけescape済みHTMLとして入れる。

html block で使える表現部品

同梱の style.css には、html block 内でそのまま使える表現 class が実装済みである。比較・評価・推奨・決定がある内容では、素の <table> / <p> で終えず、該当する部品を選ぶ。

用途	class	書き方
表番号 + 表題	table-wrap / table-cap / t-no / t-title / table-scroll	<figure class="table-wrap"><figcaption class="table-cap"><span class="t-no">表 1</span><span class="t-title">3 案の比較</span></figcaption><div class="table-scroll"><table>…</table></div></figure>
表ヘッダの補助説明	axis-sub	<th scope="col">実装量<span class="axis-sub">行数の目安</span></th>
5 段階評価	rate + good/mid/low + r1〜r5 + pips / pip	<span class="rate good r4"><span class="pips"><i class="pip"></i><i class="pip"></i><i class="pip"></i><i class="pip"></i><i class="pip"></i></span>容易</span> (pip は常に 5 個。rN が塗る数、good/mid/low が色)
可否・対応状況	tag-yes / tag-no / tag-cell-note	<td><span class="tag-yes">対応</span><span class="tag-cell-note">v2.0 以降</span></td>
桁揃え数値	num	<td><span class="num">1,024</span></td> (表中の数値列に使う)
推奨パネル	reco / reco-tag	<div class="reco"><span class="reco-tag">推奨</span><p>案 B を採る。理由は…</p></div>
決定の枠囲み	decision-panel	<div class="decision-panel"><p>…</p></div>
コード内の着色 (新規は language-* 既定)	language-* (自動) / 互換の tok-k / tok-f / tok-s / tok-c / tok-n	新規: <pre><code class="language-python">def main():</code></pre>。手動着色 (互換): <pre><code><span class="tok-k">def</span> …</code></pre>。同梱 highlight.js が を自動着色する。 を含む code / / は自動着色しない

多軸の比較表 (table.cmp)

軸が 3 つ以上ある比較、または行数が多くて横スクロールが要る比較には <table class="cmp"> を使う。通常の <table> と違い、ヘッダ行と最初の列 (比較軸) がスクロール中も固定され、推奨案の列を緑で浮かせられる。

class	効果
cmp (table に付ける)	比較表本体。thead th が sticky ヘッダになる。最小幅 720px のため table-scroll の中に入れる
axis (最初の列の th / td に付ける)	比較軸の列が横スクロール中も左端に残る
pick (<col> / th / td に付ける)	推奨する案の列を緑系で強調する。<colgroup><col><col class="pick"></colgroup> で列単位、または個別セルに付ける

<figure class="table-wrap">
  <figcaption class="table-cap"><span class="t-no">表 1</span><span class="t-title">3 案の比較</span></figcaption>
  <div class="table-scroll">
    <table class="cmp">
      <colgroup><col><col><col class="pick"><col></colgroup>
      <thead><tr>
        <th scope="col" class="axis">評価軸</th>
        <th scope="col">案 A</th><th scope= =>案 B案 C
      
      
        実装量行数の目安
            40180920
      
    
  

軸が 2 つだけ、または行が少なく横スクロールが不要な表では、cmp を使わず素の <table> にする。sticky と最小幅は狭い表では邪魔になる。

使い分けの基準:

• 比較表には table-wrap + table-cap で番号と表題を付ける。本文からの参照は「表 1」で行う。
• 軸が 3 つ以上あるなら table.cmp + axis を使い、推奨案の列に pick を付ける。
• 評価軸 (容易さ・成熟度・リスク等) は文字だけでなく rate の点表示でも符号化する。
• 推奨・決定は本文の段落に埋めず、reco または decision-panel で独立させる。
• 段落を文字の大きさで強調しない。強調したい段落があるなら、それは推奨・決定・注意のいずれかなので、reco / decision-panel / callout block のうち内容に合うものを使う。文書全体の導入は metadata.deck が担うので、節ごとに導入段落を作らない。
• これらは class 指定だけで効く。style 属性の直書きで同等の見た目を再実装しない。
• 色は metadata.palette の brand / brand_soft だけ主題に合わせて上書きできる。コントラスト比は check-model / render / validate が WCAG 4.5:1 で検査し、不足すると error で止まる (brand は最も薄い地色との比、brand_soft は本文色との比、両方指定時は 2 色の相互比も見る)。

Style Classes Available in html Blocks

The bundled style.css ships ready-to-use presentation classes for html blocks. When the content contains comparisons, ratings, recommendations, or decisions, do not stop at bare <table> / <p>: use table-wrap + table-cap (numbered table captions), axis-sub (header sub-labels), rate good|mid|low r1..r5 with five pip elements (dot ratings), tag-yes / tag-no / tag-cell-note (availability cells), num (tabular figures), reco + reco-tag (recommendation panel), decision-panel (decision box), language-* on <pre><code> for automatic syntax highlighting via bundled highlight.js (default for new docs; keep tok-k / tok-f / tok-s / tok-c / tok-n only for compatibility with manually colored spans), pre.diff with .add / .del / .ctx for code diffs (explain the change in prose first, then show only the needed fragment), and dl.glossary for term definitions at the top of the document. Automatic highlighting skips pre.diff, .nohighlight, and any code that already has tok-* descendants. Reference numbered tables from body text as "表 1" / "Table 1". These work by class alone; do not re-implement the same look with inline style attributes. Do not emphasize a paragraph by making its type larger — if a paragraph deserves emphasis it is a recommendation, a decision, or a warning, so use reco, decision-panel, or a callout block instead. The document-level intro is metadata.deck; do not add a per-section intro paragraph.

For comparisons with three or more axes, use <table class="cmp"> inside table-scroll: the header row stays sticky while scrolling, axis on the first column keeps the comparison axis pinned during horizontal scroll, and pick on a <col>, th, or td tints the recommended option's column green. Keep plain <table> for narrow two-column comparisons — the sticky behavior and 720px minimum width get in the way there.

表現の質の指針

見た目の判断に迷った時は、次の 4 つに従う。ユーザーが見た目の方向を明示した場合は、その指定が常に優先する。

1. AI が作りがちな見た目を避ける。 次の定番の組み合わせは、指定が無い限り選ばない: cream 地 (#F4F1EA) + serif 見出し + terracotta accent / near-black 地 + acid-green や vermilion の一点差し / 絵文字を節の目印にする / 全要素センタリング / 一様な大きい角丸 / 角丸カードの左端 accent バー。
2. 構造装飾は内容の事実を符号化する。 01 / 02 / 03 のような番号は、内容が本当に順序を持つ時 (手順・時系列) だけ使う。区切り線・eyebrow・ラベルも、内容の区分を実際に表す時だけ入れ、装飾目的では入れない。
3. 読む文書と操作する画面で作法を変える。 一覧・ダッシュボード的な内容は上から順に読まれず走査される。要約を詳細より先に置き、状態は数値だけでなく形 (rate の点、tag-yes の色、callout の左帯) でも符号化して、注意が要る箇所が一目で分かるようにする。
4. 余白は layout で作る。 兄弟要素の間隔は gap を持つ flex / grid で作り、要素ごとの margin を積まない。幅の広い表・コード・図は自前の overflow-x: auto コンテナ (表は table-scroll) に入れ、ページ全体を横スクロールさせない。

図と手順の表現指針

• 原典図の引用優先。 原典に重要な図がある場合は出所を明示して引用し、模倣図を作らない。
• 矢印文字・絵文字を図記号にしない。 図が要るなら Mermaid diagram block か inline SVG を使う。
• 直列手順をフローチャート化しない。 単純な直列手順は番号付きリストで表現する。
• inline SVG の色は theme に追従させる。 紙面に直接乗る文字・線 (軸ラベル・行列の見出し・凡例の説明文・座標軸・区切り線) は fill="currentColor" / stroke="currentColor" で書き、#333 のような固定色を直書きしない。固定色は light theme でしか読めず、dark theme では紙面と同化して消える。塗りつぶした図形 (rect / path) 自体の色と、その塗りの上に重ねる文字は、両 theme で読める固定色でよい。

印刷と PDF

ブラウザの印刷ダイアログ (@media print) で topbar / toc / comment rail 等の操作 UI が消え、横スクロールしていた表・コードは折り返して全内容が残る。PDF 化が必要な時だけ python3 -m scripts.html_review_workbench.cli export-pdf --root <output-dir> [--output <pdf-path>] を実行する (headless Chrome 必須。不在時は error JSON)。preview URL の提示が既定であり、ユーザーが PDF を明示依頼した時だけ export-pdf する。

Design Quality Guidance

When unsure about visual choices, follow four rules; explicit user direction always wins. (1) Avoid stereotypical AI-generated looks — cream (#F4F1EA) with serif display and terracotta accent, near-black with a lone acid-green pop, emoji as section markers, centering everything, uniformly large border radii, accent bars on rounded cards. (2) Structural devices must encode facts: numbered markers (01/02/03) only when the content truly is a sequence; rules, eyebrows, and labels only when they mark real divisions. (3) Documents are read, dashboards are scanned: put summaries before detail and encode state in form (rating dots, tag colors, callout stripes), not numbers alone. (4) Create spacing with gap in flex/grid rather than stacked per-element margins, and give wide tables/code/diagrams their own overflow-x: auto container (table-scroll for tables) so the page body never scrolls sideways.

Diagram and procedure guidance: (a) Prefer citing an original figure with attribution over redrawing it. (b) Do not use arrow characters or emoji as diagram symbols — use a Mermaid diagram block or inline SVG when a figure is needed. (c) Do not turn a simple linear procedure into a flowchart; use a numbered list. (d) In inline SVG, draw text and strokes that sit directly on the page (axis labels, row/column headings, legend captions, rules) with fill="currentColor" / stroke="currentColor" instead of hard-coded colors such as #333, which are legible only in the light theme and disappear against the dark theme's paper; fills of shapes and the text placed on top of those fills may keep fixed colors as long as both themes can read them.

Print and PDF: browser print (@media print) hides chrome (topbar, toc, comment rail) and unwraps horizontal-scroll tables/code so content is preserved. Run export-pdf only when the user explicitly asks for a PDF (python3 -m scripts.html_review_workbench.cli export-pdf --root <output-dir>); preview URLs remain the default. Headless Chrome is required; missing Chrome returns an error JSON (no external service fallback).

操作部品 (触って試す / 触った結果を作業へ戻す)

読むだけでなく触って決める資料では、html block に操作部品を直接書ける。値を試すスライダー、切り替えのトグル、並べ替えできるカードなどが対象。

書ける範囲

• html block の中に <script> を inline で書ける。onclick= 等の inline event handler も使える。
• 外部 host からの読み込みは check-model が error にする (<script src="…"> と <link rel="stylesheet" href="https://…"> の両方)。bundle が手元で完結する性質を保つため。図表の描画ライブラリが要る場合は Mermaid の diagram block を使う。
• 部品の見た目は既存の class (rate / tag-yes / num 等) と揃える。inline style の直書きは最小限にする。

触った結果を保存する

同梱の RHWState を使う。preview server があれば PUT /annotations/state/<name>.json で保存し、端末をまたいで同じ状態を見せる。server が無い場合 (publish した standalone、file:// で開いた場合) は localStorage に落ち、どちらも使えない環境ではメモリ上だけで動く。操作そのものは止まらない。

<label>duration <input type="range" id="dur" min="0" max="2000" value="300"></label>
<output id="durOut">300</output>ms
<script>
  (async function () {
    var dur = document.getElementById("dur");
    var out = document.getElementById("durOut");
    // 保存済みの値があれば復元する
    var saved = await window.RHWState.load("tuning");
    if (saved && saved.duration) { dur.value = saved.duration; out.textContent = saved.duration; }
    dur.addEventListener("input", function () {
      out.textContent = dur.value;
      // 動かしている間の表示更新と一緒に呼んでよい。debounce が server への PUT をまとめる
      ..(, { : dur. }, { :  });
    });
  })();

<name> は英数字とハイフン・アンダースコアだけ (最大 64 文字)。保存した内容は agent が annotations/state/<name>.json として読める。触って決めた結果を作業へ戻す経路がこれになる。文書の中で用途ごとに名前を分ける (tuning / priority-order など)。

連続して動く部品 (スライダー、テキスト入力) では { debounce: 300 } を渡す。手元の保存 (localStorage) は毎回すぐ行い、server への書き込みだけを入力が止まってから 1 回にまとめる。これを渡さずに input で呼ぶと、つまみを端から端まで動かすだけで PUT が 100 回以上飛ぶ。

逆に debounce を渡さないのは、操作が 1 回で完結する部品 (ボタン、dragend、チェックボックス) のとき。その場で保存され、戻り値の saved が remote / local / memory のどれかになる。

debounce 付きで待っている間の戻り値は superseded になる (新しい値で予約が取り直された、という意味)。最後の呼び出しだけが実際の保存結果を返す。画面に保存状態を出す場合は superseded を「保存中」として扱う。

使う判断

• 値の範囲を試したい、順序を決めたい、選択肢を絞りたい場面で使う。読んで終わる資料には入れない。
• 操作した結果を agent が受け取る必要があるなら RHWState.save() を必ず呼ぶ。呼ばないと結果は画面上だけで消える。
• 操作部品を入れた資料は、preview で server 越しに開いて動作を確認する。file:// で開くと状態が端末間で共有されない状態の確認になる。

Interactive Controls (Try Values, Return the Result to the Session)

For documents where the reader decides by manipulating rather than only reading, write controls directly into an html block: sliders for trying values, toggles, reorderable cards.

Inline <script> and inline event handlers are allowed inside html blocks. Loading from an external host is rejected by check-model — both <script src="…"> and <link rel="stylesheet" href="https://…"> — so the bundle stays self-contained. Use the diagram block when you need diagram rendering.

To persist what the reader manipulated, use the bundled RHWState. With a preview server it saves through PUT /annotations/state/<name>.json so state is shared across devices; without one (published standalone, opened via file://) it falls back to localStorage, and to memory when neither is available. The interaction never breaks.

<label>duration <input type="range" id="dur" min="0" max="2000" value="300"></label>
<output id="durOut">300</output>ms
<script>
  (async function () {
    var dur = document.getElementById("dur");
    var out = document.getElementById("durOut");
    var saved = await window.RHWState.load("tuning");
    if (saved && saved.duration) { dur.value = saved.duration; out.textContent = saved.duration; }
    dur.addEventListener("input", function () {
      out.textContent = dur.value;
      window.RHWState.save(, { : dur. }, { :  });
    });
  })();

<name> accepts alphanumerics, hyphens, and underscores (64 chars max). Saved state is readable by the agent at annotations/state/<name>.json — that is the path by which a decision made in the browser returns to the session. Use distinct names per purpose (tuning, priority-order). For continuously moving controls (sliders, text inputs) pass { debounce: 300 }: local storage is written on every call, while the server write is coalesced into one after input stops. Omit debounce for one-shot interactions (buttons, dragend, checkboxes). While a debounced write is waiting, save() resolves with saved: "superseded" — treat that as "saving" in any status display; only the final call reports the real result.

Add controls only when the reader needs to try values, decide an order, or narrow options; leave them out of read-only documents. If the agent must receive the outcome, RHWState.save() is required — otherwise the result stays on screen and disappears. Verify interactive documents through preview over the server, since opening via file:// exercises the fallback path instead.

Mermaid 対応 kind と最小サンプル

diagramブロックのMermaid sourceは、mermaid.js v11系が対応する記法から選ぶ。同梱済み mermaid.min.js がHTML上でSVGに置換する。

主要 kind:

kind	用途
flowchart / graph	処理・依存関係のフロー
sequenceDiagram	相互作用・時系列メッセージ
stateDiagram-v2	状態遷移
classDiagram	クラス構造・継承・関連
erDiagram	エンティティ関係
gantt	期間・スケジュール
journey	ユーザー体験の順序
timeline	時系列イベント
mindmap	概念マップ・分類
pie	割合
gitGraph	ブランチ・マージ
requirementDiagram	要件・トレーサビリティ
quadrantChart	2軸マトリクス
sankey	フロー量
xychart-beta	2次元数値プロット
architecture-beta	システム構成
block-beta	ブロック配置
packet-beta	パケット構造
kanban	カンバンボード
radar	レーダーチャート
treemap	階層構造の面積表現
zenuml	ZenUML記法

最小サンプル:

erDiagram

erDiagram
    CUSTOMER ||--o{ ORDER : places
    CUSTOMER {
        string id PK
        string name
    }
    ORDER {
        string id PK
        string customer_id FK
    }

sequenceDiagram

sequenceDiagram
    participant User
    participant API
    User->>API: request
    API-->>User: response

stateDiagram-v2

stateDiagram-v2
    [*] --> Idle
    Idle --> Running: start
    Running --> Idle: stop

flowchart LR

flowchart LR
    A[Input] --> B{Decide}
    B -->|yes| C[Do it]
    B -->|no| D[Skip]

sourceの記法が不確かな場合は mermaid.js 公式docs (https://mermaid.js.org/) を参照する。schemaの diagram_kind は表示ラベル用のグループ名で、Mermaidの内部kind名と一致させる必要はない。

Mermaid Kinds and Minimal Samples

Use Mermaid source supported by mermaid.js v11. The bundled mermaid.min.js renders diagram blocks into SVG in the browser, and rendered Mermaid diagrams can be opened from the zoom button for full-screen pan / zoom inspection. Common kinds include flowchart / graph, sequenceDiagram, stateDiagram-v2, classDiagram, erDiagram, gantt, journey, timeline, mindmap, pie, gitGraph, requirementDiagram, quadrantChart, sankey, xychart-beta, architecture-beta, block-beta, packet-beta, kanban, radar, treemap, and zenuml. If syntax is uncertain, check the Mermaid docs. The schema diagram_kind is a display grouping label and does not need to match Mermaid's internal kind name.

見出し階層

rendererは <h1> を文書タイトルに使う。本文ブロックの見出しは heading_level フィールドで制御する。

heading_level	HTML タグ	用途
2	<h2>	章見出し。文書を大きく区切る上位セクション。読者が目次で選ぶ単位
3	<h3>	節見出し。章の中を細分化するサブセクション
4	<h4>	項見出し。節の中をさらに分けるサブサブセクション

• heading_level は必須。2（章）、3（直前の章の配下の節）、4（直前の節の配下の項）のいずれかを指定する。
• 目次と自動採番は 3 階層に対応する（1. / 1.2 / 1.2.3）。既定は 2 階層で足りる文書が多く、4 は章・節・項の 3 段が内容として実在する場合だけ使う。
• title に章番号を書かない。 番号は renderer が heading_level と blocks の並びから自動で振る。"3. 解決すべき顧客・業界の課題" と書くと、本文でも目次でも番号が二重になる（3. 3. 解決すべき…）。元の資料が番号付きの構成でも title は "解決すべき顧客・業界の課題" とし、順序と階層は blocks の並びと heading_level で表す。
• content 内に <h2> や <h3> を直接書かない。小見出しが必要な場合は <h4> を使う（renderer が block の階層に合わせて自動シフトする。節の中では <h4> のまま、項の中では <h5> になる）。

html block 内の HTML 品質

html block の content に書く HTML は、セマンティックな構造を意識する。

• 表は <table> に <thead> と <tbody> を含め、ヘッダセルは <th scope="col"> または <th scope="row"> にする。
• 手順は <ol>、並列項目は <ul>、用語と説明の対は <dl> にする。
• 長い本文は <p> で段落分けし、<div> に流し込まない。
• 強調は <strong>（重要）と <em>（ニュアンス）を使い分ける。

HTML表現設計フェーズ

文書モデルを作る前に、agentは次を決める。

• 読者と用途。
• 章構成。文書全体を概要→各論→結論のような読み手を誘導する流れに分ける。どのブロックが章（heading_level: 2）でどのブロックが節（heading_level: 3）かを先に決める。1つの章に節が偏りすぎないようバランスを取る。
• 主要な情報単位。
• 比較軸、時系列、依存関係、操作手順、決定、前提、未決事項。
• 各blockの type, title, heading_level, content, review_required。
• 各 heading_level: 2 ブロックの冒頭に、その章で扱う内容の文脈を示す導入段落を置く。
• html block内で使う表、番号付きリスト、箇条書き、コードブロック、通常本文の構成。
• 図示または画像が必要な箇所と、Mermaid sourceまたは生成画像prompt。
• accent 色。主題の世界にある色 (対象領域の道具・素材・慣習色) から 1 色選び、metadata.palette に light / dark 別の brand / brand_soft として書く。決められない場合は palette を書かず既定 (青系) のままにする。大胆さは 1 箇所に集中させ、周囲は静かに保つ。accent が地色と競う場合は、色相を近づけるか彩度を落とす。コントラスト比 (WCAG 4.5:1) は check-model / render / validate が機械検査し、不足は error で止まる。

"metadata": {
  "palette": {
    "light": { "brand": "#2f6093", "brand_soft": "#e8eff7" },
    "dark":  { "brand": "#7fb0e6", "brand_soft": "#1b2b3d" }
  }
}

上書きできるのは brand / brand_soft だけ。中立色・地色・レビュー状態色 (open / reply / resolved) は固定で、変更できない。

入力がMarkdownや箇条書きで整理されていても、記号構造をそのまま変換しない。最終HTMLで読みやすい単位へ組み替えてから文書モデルにする。

HTML Information Design Rules

Treat HTML output as information design for the final bundle, not as text conversion. Identify the audience, purpose, comparison axes, chronology, dependencies, steps, decisions, assumptions, and unresolved issues before writing the model. Use tables for comparisons, ordered lists for procedures, lists for parallel items, callouts for decisions or cautions, diagrams for flows and dependencies, images for useful visual explanations, and code blocks for commands or logs. Even when the input is Markdown or a list, restructure it into readable HTML blocks instead of mechanically converting the symbols.

入力モデル未指定時の規約

ユーザーが「html出力して」「HTMLにして」「HTMLで出して」「render this as HTML」「turn this into HTML」「create an HTML preview」「generate a visual HTML report」「make this a reviewable HTML document」「diagrammed HTML report」のように自然文で依頼し、document-model.json を指定していない場合も、このskillを発火させる。

その場合は、次の順で入力を決める。

1. ユーザーが明示した対象ファイル、本文、直前の成果物をHTML化対象にする。
2. 対象が曖昧で、直前の成果物も特定できない場合だけ、短く確認する。
3. 対象を特定できる場合は、確認で止めずにHTML表現設計フェーズへ進み、output/tmp/<purpose>/document-model.json または output/<YYYY-MM-DD>_<name>/document-model.json を直接作る。
4. 作成する文書モデルは schema_version, document_id, title, generated_at, blocks を必ず持つ。
5. image.generation_status=requested のブロックがある場合は画像生成と attach-image を完了してから、check-model → render → validate → preview まで進める。

build-model は最終HTMLモデルを作るplannerではない。入力を安全に保持する source-capture draft を作るだけで、Markdown表・リスト・コード等の機械変換や、内容に応じた表現選択は行わない。最終HTML出力では、agentがHTML表現設計フェーズで文書モデルを直接設計する。画像生成が外部サービス送信・機密情報・ユーザー承認を要する条件に当たる場合は、該当する承認ゲートに従う。設計判断、要求整理、レビュー観点の作成が主目的の場合は reviewable-design-doc を使う。

When No Input Model Is Provided

Natural requests such as render this as HTML, turn this into HTML, create an HTML preview, generate a visual HTML report, make this a reviewable HTML document, and diagrammed HTML report should still trigger this skill. Use the explicitly named file, pasted content, or latest artifact as the HTML source. Ask only when the target cannot be identified. If the target is clear, proceed into HTML information design and create output/tmp/<purpose>/document-model.json or output/<YYYY-MM-DD>_<name>/document-model.json directly.

render前自己レビュー

render CLIを呼ぶ前に、文書モデルを読み返して次を確認する。

• heading_level: 2 のブロックが少なくとも1つある。heading_level: 3 のブロックが最初の heading_level: 2 ブロックより前に出現していない。
• 各 heading_level: 2 ブロックの content が導入段落で始まっている。
• html block の <table> に <thead> と <th> がある。content 内に <h2> や <h3> を直接書いていない。
• html blockが未再構成テキストを <p> または <pre> だけで抱えていない。
• 比較対象がある場合は、html block内の <table> 等で比較軸を明示している。
• 手順がある場合は、html block内の <ol> 等で順序を明示している。
• 決定、前提、注意は callout または専用の html blockとして本文に埋もれないようにしている。
• callout blockの content にHTMLタグを書いていない。
• section, text, table block typeを最終モデルで使っていない。
• diagram blockは有効なMermaid sourceを持ち、画像生成promptはsourceに無い事実を追加していない。
• image blockは source_path が添付済みになるまで render しない。
• 比較を出す箇所は table-wrap + table-cap で表に番号と表題を付けている。評価軸があるなら rate 等で視覚化している。
• 推奨・決定は本文の段落に埋めず、reco または decision-panel で独立させている。

Pre-render Self Review

Before calling render, read the model back and confirm the heading hierarchy, introductory paragraphs, supported block types, table semantics, ordered steps, callouts, diagram sources, attached images, and absence of raw unstructured dumps. Do not render until requested images have been attached and unsupported block types have been removed.

生成画像promptの規約

• diagramブロックの生成画像は、Mermaid sourceのノード、ラベル、矢印方向、関係を保持する。sourceに無い事実、指標、関係、ブランド要素、装飾を追加しない。
• diagramブロックではMermaid sourceを assets/diagrams/*.mmd に保存し、HTML上は生成画像を主表示にする。生成画像が未添付の場合だけMermaid fallbackを表示する。
• imageブロックの生成画像は、白背景、十分な余白、資料向けの落ち着いた見た目、必要最小限の文字量を基本にする。
• 画面イメージは実在スクリーンショットではなくmockupとして生成する。公式ロゴ、ブランド名、UIラベル、数値、根拠を入力に無い形で作らない。
• 概念画像は直感理解の補助に限定する。事実関係、依存関係、数値、判断順を説明する場合はdiagramブロックを優先する。

CodexでのCLI呼び出し

このskillは、低レベル実装へ直接importせず、共通CLIだけを呼ぶ。

CLI実行前に、この SKILL.md の配置から renderer repo root を決める。 skills/visual-html-renderer/SKILL.md の2階層上が renderer repo root であり、 そこに scripts/html_review_workbench/cli.py が存在することを確認する。 すべての python3 -m scripts.html_review_workbench.cli ... は renderer repo root を 作業ディレクトリにして実行する。現在のチャットやworkspaceのcwdをrepo rootとして扱わない。 cwdに scripts/html_review_workbench/cli.py が無い場合は、代替HTMLを作らず、 renderer repo rootへ移動してCLIを実行する。

python3 -m scripts.html_review_workbench.cli build-model \
  --text "<content>" \
  --output <document-model.json>

python3 -m scripts.html_review_workbench.cli attach-image \
  --model <document-model.json> \
  --block-id <generated-image-block-id> \
  --image <generated-image-path>

python3 -m scripts.html_review_workbench.cli check-model \
  --model <document-model.json>

python3 -m scripts.html_review_workbench.cli render \
  --model <document-model.json> \
  --output <output-dir>

python3 -m scripts.html_review_workbench.cli validate \
  --root <output-dir>

python3 -m scripts.html_review_workbench.cli preview \
  --root <output-dir> \
  --mode auto

python3 -m scripts.html_review_workbench.cli publish \
  --root <rendered-bundle-dir> \
  --output <publish-output-dir>

Codex / Claude では preview コマンドを一回限りの shell から起動することがあるため、標準手順では --owner-pid を渡さない。preview server は 24時間アクセスが無い場合に idle timeout で自動停止する。

Codex sandbox内で tailscale ip -4 が設定ファイル読み取りに失敗する場合は、preview本体をsandbox内で起動したまま、IPだけを小さいresolverで先に取得して渡す。

python3 -m scripts.html_review_workbench.preview_host_resolve

HTML_REVIEW_WORKBENCH_TAILSCALE_IP=<tailscale-ip> \
  python3 -m scripts.html_review_workbench.cli preview \
    --root <output-dir> \
    --mode auto

長寿命の所有プロセスが明確に分かる場合だけ --owner-pid <pid> を使ってよい。一回限りの shell の $$ や $PPID は短命プロセスを指すため使わない。

ユーザーが明示的にプレビュー不要と言った場合、または自動テスト・fixture検証で副作用を抑える場合だけ --mode off を使う。ユーザー向け成果物では --mode off を既定にしない。 成果物はユーザーが直接読む最終HTMLなら output/<YYYY-MM-DD>_<name>/、再利用しない検証なら output/tmp/<purpose>/ に置く。

CLI Usage in Codex

Call only the shared CLI. Resolve the renderer repo root from this SKILL.md: two levels above skills/visual-html-renderer/SKILL.md. Run every python3 -m scripts.html_review_workbench.cli ... command from that repo root. If the current workspace does not contain scripts/html_review_workbench/cli.py, move to the renderer repo root instead of creating fallback HTML. Use --mode off only for explicit no-preview requests or tests; user-facing artifacts should default to --mode auto.

Preview URL提示とライフサイクル

• preview が status: running を返した場合、最終応答に url を必ず含める。ファイルパスだけで完了しない。
• preview が status: off または status: failed の場合、URLが無い理由を明示し、可能なら --mode auto で再実行してURL提示まで進める。
• 標準では --owner-pid を渡さず、24時間アクセスが無い場合に idle timeout で自動停止させる。長寿命の所有プロセスが明確な場合だけ --owner-pid <pid> を使う。
• 手動停止が必要な時だけ、返却JSONの stop_command を使う。PIDなしで全previewを停止しない。

Preview URL and Lifecycle

When preview returns status: running, include the url in the final response; a file path alone is not completion. If preview is off or failed, state the reason and try --mode auto when appropriate. Do not pass --owner-pid by default; the preview server stops after 24 hours without access. Use the returned stop_command only when manual cleanup is needed.

完了時の確認

• index.html と renderer-manifest.json が生成されている。
• validate が status: ok を返している。
• preview 有効時は提示URL、bind先、PID、停止方法をユーザーへ伝える。
• preview は 0.0.0.0 にbindしていない。

実シナリオ検証

自動テスト pass と CLI の JSON 出力確認は、実シナリオ検証ではない。「動作確認」を求められた場合、以下を実行する。

1. 実際の内容について document-model.json を作り、render → validate → preview を実行する。
2. preview URL をユーザーに提示し、ブラウザで表示を確認してもらう。
3. 表示に問題がある場合は、文書モデルを修正して再 render する。

検証の完了条件: ユーザーがブラウザ上で最終 HTML の表示を確認した時点。validate が status: ok を返したことではない。

Real Scenario Verification

Passing unit tests and receiving valid CLI JSON are prerequisites, not real scenario verification. When the user asks for an operational check, create a real document-model.json, run render -> validate -> preview, provide the preview URL, and have the user confirm the rendered HTML in the browser. Verification is complete only after the browser-visible result is accepted.

Completion receipt

最終応答には次を含める。

• HTML表現設計: 使用した主要block型と、その表現にした理由。
• 生成物: index.html と renderer-manifest.json の場所。
• 検証: validate の結果。
• preview: URL、bind先、PID、stop_command。
• 未実施: 画像生成、manual-acceptance-testing 等の未実施層があれば理由。

Final responses must include: HTML design choices, generated index.html and renderer-manifest.json paths, validation result, preview URL/bind/PID/stop_command, and any unperformed verification layers with reasons.

ガード

• レンダラーは内容判断を作らない。
• 図示は入力された構造を補助する目的に限定する。
• ブラウザを自動で開かない。URL提示までを責務とする。
• Preview Runtime は 0.0.0.0 にbindしない。
• 外部サービスへ投稿・アップロードする場合は別途承認ゲートを通す。

Guards

The renderer does not invent content decisions. Diagrams only support the provided structure. Do not open the browser automatically; return the URL. Never bind Preview Runtime to 0.0.0.0. Any external posting, upload, or service transmission requires the appropriate approval gate.