Visual HTML Renderer

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のブロック型で表現が足りない場合、未再構成テキストへ戻さず、必要なブロック型やレンダリング拡張を検討する。

<!-- BEGIN SHARED: md-file-prohibition -->

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

<!-- END SHARED: md-file-prohibition -->

rendererブロック対応表

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

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

<!-- BEGIN SHARED: html-style-classes -->

html block で使える表現部品

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

多軸の比較表 (table.cmp)

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

<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="col" class="pick">案 B</th><th scope="col">案 C</th>
      </tr></thead>
      <tbody>
        <tr><th scope="row" class="axis">実装量<span class="axis-sub">行数の目安</span></th>
            <td><span class="num">40</span></td><td class="pick"><span class="num">180</span></td><td><span class="num">920</span></td></tr>
      </tbody>
    </table>
  </div>
</figure>

軸が 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.

<!-- END SHARED: html-style-classes -->

<!-- BEGIN SHARED: html-design-guidance -->

表現の質の指針

見た目の判断に迷った時は、次の 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 を使う。
• 直列手順をフローチャート化しない。 単純な直列手順は番号付きリストで表現する。
• Mermaid の mindmap を使わない。 mindmap は日本語などの CJK ラベルで箱の採寸を誤り、文字が箱からはみ出し・重なって崩れる (2026-08-06 実測)。放射状の分類は flowchart の中心ノード + 枝で表現する。
• 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) Do not use Mermaid mindmap: it mis-measures CJK labels so text overflows and overlaps its node boxes (observed 2026-08-06); express radial groupings as a flowchart with a central node and branches. (e) 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).

<!-- END SHARED: html-design-guidance -->

<!-- BEGIN SHARED: html-interactive-controls -->

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

読むだけでなく触って決める資料では、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 をまとめる
      window.RHWState.save("tuning", { duration: dur.value }, { debounce: 300 });
    });
  })();
</script>

<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("tuning", { duration: dur.value }, { debounce: 300 });
    });
  })();
</script>

<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.

<!-- END SHARED: html-interactive-controls -->

<!-- BEGIN SHARED: mermaid-kinds -->