hayatosc/html-artifacts

HTML Artifacts（HTML成果物）

ディスクから開いてオフラインで動作する、人間向けの単一 .html ファイルを提供します。CDNやフレームワークは使用せず、同梱された日本語版デジタル庁デザインシステム（DADS）のドキュメントアダプターを使用します。エージェント向けのソースはMarkdownで維持します。これは非公式のドキュメントアダプターであり、すべてのDADSコンポーネントを完全に実装したものではありません。

手順

1. 読者とソースを理解する

主題、読者、目的、エビデンスを特定してから構成を選択します。計画の場合、目的、完了のエビデンス、制約、チェックポイント、リスクを保持します。説明的なタイトル、簡潔な方向付け、ソース/日付の発信元情報を含めます。目次（TOC）は有用な場合のみ追加し、セクション数や図表を強制しません。

ゼロから説明する：具体的な状況と主題の動作から始め、その後で技術的な名前を導入します。専門用語は初出時に定義し、各ステップは1つのアイデアに絞り、ラベル付き画像は散文よりも明確に説明できる場合のみ使用します。比喩は、その関連性と限界が明示的な場合のみ使用し、子供向けでない限り、成人向けの直接的なトーンを保ちます。新規参入者が何が起こるか、なぜ起こるか、次に何をすべきかを理解できるようにします。

2. 機械的に構築する — CSSを再入力しない

build.md を読んでください。スキルディレクトリは、このファイルの場所から解決し、現在のプロジェクトの作業ディレクトリからは解決しません。Python 3.10以上を使用：

python /absolute/path/to/html-artifacts/scripts/build.py /absolute/path/to/output.html --title "主題"

ビルダーは assets/template.html を読み取り、assets/dads.css と assets/print.js のすべてを埋め込み、オフラインコンテンツセキュリティポリシー（CSP）を挿入します。既存のファイルを上書きすることは拒否します。ダウンロード、パッケージインストール、サーバー、バンドラー、隣接するアセットフォルダーは不要です。このリポジトリ内では、Pythonランナー（uv run python も使用可能）を使用します。

3. 基盤ではなくコンテンツを編集する

生成されたファイルを編集します。スターターの説明コンテンツ、発信元情報、目次を置き換え、不要なセクションを削除します。style#dads-css、script#dads-print、CSP、charset、viewport、only light カラースキームのメタデータはそのまま維持します。

• インラインSVGと埋め込みラスター画像のみ。リモート/ローカルのスタイルシート、スクリプト、フォント、画像、iframe、import、fetch、分析依存関係はありません。通常のソースハイパーリンクはウェブを指しても構いません。ローカルソースファイルは、壊れた相対リンクではなくテキストとしてラベル付けします。
• セマンティックHTMLとバンドルされたクラス/トークンを使用します。クラスAPI、公式ソース、ローカル適応については dads.md を読んでください。上流の data-type/data-size APIをこのアダプターの修飾子と混在させないでください。
• SVGを追加する前に diagrams.md を使用します。意味のある図には、タイトル、説明、ラベル、テキスト代替をそれぞれ与えます。広い図は、ラベル付けされキーボードフォーカス可能な .dads-diagram-scroll 領域に配置します。
• インストール済みフォントのフォールバックを使用します。Notoがない場合でもテキストが非表示にならないようにします。lang をコンテンツに一致させます。本文は1rem/1.7（デフォルト設定で16px）です。ブラウザのズームとリフローを維持します。
• デフォルトではリンクとネイティブ開示要素を使用します。開示要素は初期状態で open にしておき、スクリプトなしの印刷でもコンテンツが保持されるようにします。バンドルされたスクリプトは、読者が折りたたんだ開示要素も印刷用に開き、その後復元します。タブ、無効なボタン、任意のJavaScript、イベントハンドラー属性は追加しないでください。
• OSのダーク設定では明るいままにします：このアダプターには検証済みの公式ダークパレットはありません。ページの背景だけを反転させたり、ダークトークンセットを独自に作成したりしないでください。強制カラーモードとモーション軽減設定を尊重します。
• 既存のコンポーネントを優先します。どうしても必要な場合は、ドキュメント固有の小さなルールを別のインライン <style> に記述します。新しいクラスは artifact-* とし、そこで定義する必要があります。既知のトークンを使用し、それらを再定義したり、バンドルされたCSSを変更したりしないでください。これらのルールはブラウザで確認してください。静的検証はCSSパーサーやコントラスト監査ではありません。

4. 最終セルフチェック — 納品前に不具合を修正する

最後の編集後に以下を実行：

python /absolute/path/to/html-artifacts/scripts/check.py /absolute/path/to/output.html

次に、可能な場合はネットワークを無効にして、実際のファイルをブラウザで確認します：

1. コンテンツ： スターターの散文/プレースホルダーが削除されていること。要求されたエビデンス、ソース、日付、次のアクションが残っていること。図の説明を独立して読めること。意味が伝わること。
2. オフライン： リソース要求、失敗したアセット、CSP違反、コンソールエラーがないこと。ソースハイパーリンクはナビゲーションであり、埋め込み依存関係ではないこと。
3. モバイル/デスクトップ： 390pxと1280pxでのスクリーンショットを検査。さらに320px/200%テキストサイズでのリフローを確認。ページ全体の水平オーバーフローがないこと。ラベル付けされフォーカス可能なコード/テーブル/図の領域のみスクロール可能。実際の日本語グリフと長いURLを検査。
4. キーボード/状態： スキップリンクとTOCをたどり、スクロール領域にタブ移動し、開示要素をトグルし、可視フォーカスとボタンリンクのコントラスト（visited/hover含む）を検査。色のみの意味がないこと。
5. ダーク/印刷： ダーク設定をエミュレート（ページは明るいまま判読可能であること）。開示要素を閉じた状態で印刷し、その本文が印刷されることを確認。広いテーブル/コードと改ページを確認。開示要素は初期状態で開いたままにすることで、JavaScriptなしでコンテンツを保持。

チェッカーは、バンドルされたアセット/ポリシー契約、既知のクラス/トークン、および保守的なオフラインリソースルールを強制します。CSS構文、レイアウト、コントラスト、アクセシビリティ、任意のHTMLの正しさを証明するものではありません。ブラウザが利用できない場合は、どの視覚的/インタラクションチェックが未検証のままかを明示し、静的チェックのみでスクリーンショットを主張しないでください。

5. 納品

ソースの隣または作業ディレクトリに、主題にちなんだ名前（計画の場合は PLAN.html）で保存します。成果物へのリンクと重要な制限事項を返します。文書のコピーや2つ目の汎用セルフ監査は返さないでください。

SSH/別のデバイスの場合は、remote-preview.md に従ってください。リモートパスや xdg-open は、利用可能な表示の引き継ぎ手段ではありません。分離されたコピーのみを提供し、パブリックトンネルは公開共有が許可されたコンテンツにのみ使用し、それ以外はSSH転送/アクセス制御を使用し、クリーンアップ手順を提供します。元のHTMLはオフラインで安全なままにします。

リソース

• assets/template.html、assets/dads.css、assets/print.js：機械的に埋め込まれるソース。
• scripts/build.py、scripts/check.py：標準ライブラリでのビルドと最終契約チェック。
• build.md：編集パターンとトラブルシューティング。
• dads.md：公式発信元、トークン、アダプターコンポーネントAPI。
• diagrams.md：読みやすいインラインSVGパターン。
• remote-preview.md：安全なリモート引き継ぎ。

ゼロからの説明アプローチは、ELI5スキル に触発されています。