u-ichi/reviewable-html-workbench/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内の見出しや本文は、元資料の言語、ユーザーの指定、レビュー対象読者に合わせる。

基本手順

1. Plan Mode 中の計画確認プレビュー、<proposed_plan> の視覚確認、計画URLの追加が目的なら、このskillではなく plan-preview を使う。
2. 文書モデルとレンダリングオプションを確認する。
3. 文書モデルが未指定の場合は、直前の成果物またはユーザー指定内容を読み、HTML表現設計フェーズで構成を決める。
4. 現行rendererのブロック型に合わせて、agentが document-model.json を直接作る。
5. 一時的な入力退避が必要な場合だけ build-model で source-capture draft を作ってよい。ただし draft は最終モデルではないため、そのまま render へ渡さない。
6. render前に document-model.json を読み返し、未再構成テキストの流し込みやrenderer非対応型の使用がないことを確認する。
7. image.generation_status=requested のブロックがある場合は、imagegen skillで画像を生成し、attach-image CLIで文書モデルへ添付する。
8. check-model CLIで最終render前の文書モデル品質を検査する。
9. render CLIでHTML bundleを生成する。
10. validate CLIでHTML、asset、comment schema、図・画像の非空を検証する。
11. ユーザー向け最終HTMLでは既定で preview CLIを --mode auto で起動し、返却JSONの url と stop_command を最終応答に必ず書く。
12. 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

1. 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.
2. Check the document model and rendering options.
3. If no document-model.json is provided, inspect the user's content or the latest artifact and design the HTML structure yourself.
4. Create the final document-model.json directly using the renderer-supported block types.
5. Use build-model only as a source-capture draft when temporary input storage is needed; never pass that draft straight to render.
6. Read back the model before rendering and confirm that raw or unsupported content was not dumped into the model.
7. If image blocks request generation, use the imagegen skill and attach images with attach-image.
8. Run check-model, then render, then validate, then preview.
9. For user-facing artifacts, use preview --mode auto by default and include the returned url and stop_command in the final response.
10. 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) に入れ、ページ全体を横スクロールさせない。

図と手順の表現指針