html-doc

HTML ドキュメント

完成した Markdown の PRD または技術設計書を、検証済みの静的 HTML ページに変換します。Markdown を正本として維持してください。意味は変えず、表示だけを変更します。

範囲

• 既存の Markdown ファイル、または正確なインライン Markdown を受け付けます。
• ドキュメントの種類は prd と design のみをサポートします。
• REQUIREMENTS.md の場合は、--kind prd を指定します。ARCHITECTURE.md または spec.md の場合は、--kind design を指定します。
• prd.md は prd、design.md は design として分類します。その他の名前の場合は、リクエストに従うか、種類が不明確であれば確認してください。
• 要件を書き起こしたり、設計上の選択を決定したり、欠落した内容を要約したり、ソースを編集したりしないでください。
• ソースが大まかな概要にすぎない場合は、先に適切な作成スキルを使用してください。
• 生成された HTML を手作業で編集しないでください。テンプレートまたはレンダラーを変更してから、再生成してください。
• ユーザーから別途依頼がない限り、結果を公開またはホストしないでください。

要件

生成には Python 3.11 以降、Pandoc 3 以降、Node.js 22.12 以降、および npm が必要です。スキルのディレクトリには、ロックされた Mermaid 依存関係ツリーが含まれています。

最初の Mermaid レンダリングを行う前に、次を実行してください。

npm ci --prefix <skill-directory>

すべての生成およびライフサイクル操作には、このスキルのディレクトリにある scripts/html_doc.py を使用してください。

ワークフロー

1. ソースを読み、分類する

ソース全体を読みます。サイズが 2 MiB 以下であることを確認します。リクエストまたは上記のベース名の対応表に基づいて、ドキュメントの種類を判断します。

内容上の問題と表示上の問題は分けて扱います。Markdown に矛盾がある、必須の決定事項が欠けている、または無効な図が含まれている場合は、そのソースの問題を報告してください。意味を黙って修正しないでください。

2. 候補を作成する

ファイルをソースとする場合：

python3 <skill-directory>/scripts/html_doc.py render <source.md> --kind <prd-or-design> --out <output.html>

--kind を省略できるのは、ベース名が正確に prd.md または design.md の場合のみです。--out を省略すると、同じディレクトリに HTML ファイルが作成されます。

正確なインライン Markdown の場合は、標準入力から渡し、種類と出力先の両方を指定してください。

python3 <skill-directory>/scripts/html_doc.py render --inline --kind <prd-or-design> --out <output.html>

このコマンドは、candidate、output、token を含む JSON を返します。最終出力は置き換えません。検証と最終確定のために、これらの値を正確に保持してください。

出力ロックがすでに存在する場合は、自動で削除しないでください。別の保留中レンダリングを表している可能性があります。そのパスを報告してください。状態が放棄されたことが確認できている場合に限り、discard --force-stale を使用してください。

3. 実際のブラウザーで候補を検証する

候補をローカルファイルとして開きます。ソースを確認しただけでブラウザーでの検証が済んだと見なさないでください。

次のすべてを確認してください。

• CSS ピクセル幅 1440 のデスクトップ表示。
• CSS ピクセル幅 768 のタブレット表示。
• CSS ピクセル幅 390 のモバイル表示。
• A4 および US Letter の印刷プレビュー。
• 目次のリンクとセクションのターゲット。
• スキップリンクからナビゲーション、ドキュメントのリンクまでのキーボード操作順。
• 視認できるフォーカスインジケーター。
• 1 つの main ランドマークと、適切な見出し構造。
• DOM ID の重複がないこと。
• 水平方向のはみ出し、テキスト、コード、表、図の切り取りがないこと。
• 図に役立つ代替テキストがあり、開閉コントロールがアクセシブルであること。
• コンソールエラーおよびリソースの読み込み失敗がないこと。
• ブラウザーのネットワークアクセスを無効にした状態でも動作すること。

main 内の正本コンテンツを Markdown の抽象構文木と比較します。ナビゲーション、ソースメタデータ、および派生したアクセシビリティ用テキストは正本コンテンツではありません。ソースの各トップレベルブロックは、SHA-256 の識別情報を持ち、入れ子になった内容がそのまま保持された 1 つの順序付き data-source-block ノードに対応している必要があります。Mermaid ブロックは 1 つの図に対応し、その開示部分に正確なソースが 1 回だけ含まれている必要があります。

表示上の欠陥が共通のレンダラーまたはスタイルに起因する場合は、そのソースを修正して再生成してください。内容上の欠陥の場合は、ソースと候補を変更せず、その問題を報告してください。

4. 最終確定または破棄する

すべてのチェックに合格した場合に限り、候補をアトミックにインストールしてください。

python3 <skill-directory>/scripts/html_doc.py finalize --out <output.html> --token <token>

いずれかのチェックに失敗した場合は、この保留中の候補のみを削除してください。

python3 <skill-directory>/scripts/html_doc.py discard --out <output.html> --token <token>

最終確定では、同じディレクトリ内で 1 回のアトミックな置き換えを行います。以前の出力を先に削除することはありません。レンダリング、チェック、または置き換えに失敗した場合、以前に検証済みの出力はバイト単位で変更されずに保持されなければなりません。

出力基準

最終ページは、以下の要件を満たす必要があります。

• 原文の表現と順序を維持する
• 標準の prd または design の機械可読メタデータを使用する
• ソースパスと SHA-256 ハッシュを記録する
• セマンティック HTML とインライン CSS を使用し、実行時 JavaScript は使用しない
• 外部の実行時アセットを含めない
• 落ち着いたブルーグレーのビジュアルシステムを使用する
• 色、マウス、広い画面、ネットワーク接続がなくても読みやすくする
• レスポンシブスタイルと印刷用スタイルを含める
• 検証済みの Mermaid SVG を Base64 画像として埋め込み、開閉可能な領域に正確なソースを保持する

返却

検証済み候補が確定したら終了してください。出力パス、ソースハッシュ、実施したブラウザチェックを報告してください。