u-ichi/reviewable-html-workbench/reviewable-design-doc

reviewable-design-doc

役割

設計資料としてレビューできる構造を作り、最終HTML生成は visual-html-renderer に渡す。

レビュー完了後は annotations/comments.json を読み、明確な指摘は設計へ反映し、確認・回答が必要な指摘は add-reply CLI でHTMLの同じコメントスレッドへ書き戻す（チャットへの回答ではなくHTML上の返信として）。

Role

Create a design document that can be reviewed in the browser. This skill owns design structure, review intent, comment ingestion, and comment-thread replies. Final HTML rendering is delegated to visual-html-renderer. After review, read annotations/comments.json, apply clear resolved feedback, and write clarification replies back into the same HTML comment thread with add-reply.

言語方針 / Language behavior

Follow the language of the latest user request for progress updates, final responses, and review handoff text. レビューコメントへの返信は、原則としてそのコメント本文の言語に合わせる。日本語コメントには日本語で、英語コメントには英語で返信する。設計本文や引用内容は、ユーザーが翻訳を求めない限り勝手に翻訳しない。

基本手順

1. 設計対象、読者、レビュー目的、完了条件を整理する。
2. 要求、制約、アーキテクチャ、代替案、意思決定、未決事項へ分解する。
3. レビュー観点とコメントしてほしい範囲を明示する。
4. 最初から document-model.json を作る。設計本文の下書きや中間成果物として .md を作らない。
5. 文書モデルには、要求、制約、アーキテクチャ、代替案、意思決定、未決事項、レビュー観点を、それぞれ現行rendererで有効なHTML表現を選んだblockとして入れる。
6. image.generation_status=requested のブロックがある場合は、imagegen skillで画像を生成し、attach-image CLIで文書モデルへ添付する。
7. check-model CLIで最終render前の文書モデル品質を検査する。
8. render CLIでHTML bundleを生成する。
9. validate CLIでHTML bundleを検証する。
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>。イベント受信後の処理は「コメント自動回答と解決待ちゲート」セクションに従う。
12. ユーザーがコメントを入れたら「レビューコメントへの対応」セクションに従う。

Basic Workflow

1. Clarify the design target, audience, review purpose, and completion criteria.
2. Split the material into requirements, constraints, architecture, alternatives, decisions, unresolved issues, and review points.
3. Create document-model.json from the start; do not create a .md draft as the design body.
4. Choose renderer-supported HTML blocks for each design unit.
5. Generate requested images with imagegen and attach them before rendering.
6. Run check-model, render, validate, and preview.
7. Start watch-comments after preview startup.
8. When the user adds comments, ingest them, reply in the HTML thread to every thread listed in needs_agent_review_threads, and apply resolved feedback only after gates allow it.

設計資料モデル作成の規約

<!-- BEGIN SHARED: md-file-prohibition --> 設計資料作成は、.md 原稿をHTMLへ変換する作業ではない。reviewable-design-doc は、設計内容を最初からレビュー可能なHTML bundleの情報設計として作る。

• 新規に設計資料を作る場合、最初の保存対象は output/tmp/<purpose>/document-model.json または output/<YYYY-MM-DD>_<name>/document-model.json にする。
• .md ファイルを設計本文の下書き、中間成果物、HTML化対象として作らない。
• 一時的に自然文入力を保存する必要がある場合だけ、source.txt, input.txt, source-content.txt のようなプレーンテキスト名を使う。

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

• 設計資料の本文は、見出し記号を含む原稿ではなく、blocks[].title, blocks[].type, blocks[].heading_level, blocks[].content, review_required を持つ文書モデルとして表現する。
• 大区分のブロック（背景・要求、アーキテクチャ、代替案比較、意思決定、未決事項など）には heading_level: 2 を設定し、その配下の詳細ブロックには heading_level: 3 を使う。各章の冒頭にはその章で扱う内容を示す導入段落を置く。
• title に章番号を書かない。番号は renderer が heading_level と blocks の並びから自動で振るため、"3. 代替案の比較" と書くと本文でも目次でも番号が二重になる。順序と階層は blocks の並びと heading_level で表す。
• 比較・代替案・評価軸は html block内の <table>、手順は <ol>、並列項目は <ul>、操作例・ログ・コマンドは <pre><code>、処理・依存・構成はdiagramブロック、決定・前提・注意はplain textのcallout、レビューしてほしい論点は専用のレビュー観点blockにする。
• section, text, table block typeは現行rendererに専用描画がないため、最終モデルでは使わない。
• diagramブロックはMermaid sourceを構造保存用に残し、生成画像を主表示にする。生成画像が未添付の場合、全diagram kindを同梱 mermaid.js でブラウザ描画し、standalone publishでは mermaid.js と図の拡大用scriptをHTMLへinline化する。Mermaid v11系の記法に準拠してsourceを書く。sourceに無い関係や判断を画像側で追加しない。
• Mermaidで描画される図は、図右上の拡大ボタンから全画面表示に切り替え、pan / zoom で詳細を確認できる。
• 既存資料を取り込む場合も、既存ファイルをそのまま表示へ流し込まず、visual-html-renderer のHTML情報設計規約に従って文書モデルへ再構成する。
• build-model は最終HTMLモデルを作るplannerではなく、入力退避用のsource-capture draftに限る。既存本文やユーザー指定内容を取り込む場合も、そのdraftをそのままrenderせず、agentが設計構造を判断して文書モデルを直接作る。

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